idnits 2.17.1 draft-ietf-ipp-not-spec-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 6 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1603 has weird spacing: '...ipients do no...' == Line 3919 has weird spacing: '...FC xxxx m.n...' == Line 4060 has weird spacing: '...FC xxxx m.n...' == Line 4075 has weird spacing: '...FC xxxx m.n...' == Line 4491 has weird spacing: '...reation opera...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Unrecognized Status in '[Target Category: standards track]', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 27, 2002) is 7974 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2717 (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2910 (Obsoleted by RFC 8010) ** Obsolete normative reference: RFC 2911 (Obsoleted by RFC 8011) -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. 'IANA-CON') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 2565 (Obsoleted by RFC 2910) -- Obsolete informational reference (is this intentional?): RFC 2566 (Obsoleted by RFC 2911) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 7 errors (**), 0 flaws (~~), 9 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Printing Protocol WG R. Herriot 3 INTERNET-DRAFT consultant 4 T. Hastings 5 Updates RFC 2910 and 2911 Xerox Corporation 6 [Target Category: standards track] June 27, 2002 7 Expires: December 27, 2002 9 Internet Printing Protocol (IPP): 10 Event Notifications and Subscriptions 12 Copyright (C) The Internet Society (2002). All Rights Reserved. 14 Status of this Memo 16 This document is an Internet-Draft and is in full conformance with 17 all provisions of Section 10 of RFC 2026. Internet-Drafts are 18 working documents of the Internet Engineering Task Force (IETF), its 19 areas, and its working groups. Note that other groups may also 20 distribute working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress". 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.html 29 The list of Internet-Draft Shadow Directories can be accessed as 30 http://www.ietf.org/shadow.html. 32 Abstract 34 This document describes an OPTIONAL extension to the Internet 35 Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). 36 This extension allows a client to subscribe to printing related 37 Events. Subscriptions are modeled as Subscription Objects. The 38 Subscription Object specifies that when one of the specified Events 39 occurs, the Printer sends an asynchronous Event Notification to the 40 specified Notification Recipient via the specified Push or Pull 41 Delivery Method (i.e., protocol). 43 A client associates Subscription Objects with a particular Job by 44 performing the Create-Job-Subscriptions operation or by submitting a 45 Job with subscription information. A client associates Subscription 46 Objects with the Printer by performing a Create-Printer-Subscriptions 47 operation. Four other operations are defined for Subscription 48 Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- 49 Subscription, and Cancel-Subscription. 51 Table of Contents 53 1 Introduction.....................................................6 54 1.1 Notification Overview..........................................6 56 2 Models for Notification..........................................9 57 2.1 Model for Notification (Simple Case)...........................9 58 2.2 Model for Notification with Cascading Printers................10 59 2.3 Distributed Model for Notification............................10 60 2.4 Extended Notification Recipient...............................11 62 3 Terminology.....................................................11 63 3.1 Conformance Terminology.......................................11 64 3.2 Other Terminology.............................................12 66 4 Object Relationships............................................15 67 4.1 Printer and Per-Printer Subscription Objects..................15 68 4.2 Printer, Job and Per-Job Subscription Objects.................15 70 5 Subscription Object.............................................15 71 5.1 Rules for Support of Subscription Template Attributes.........16 72 5.2 Rules for Processing Subscription Template Attributes.........17 73 5.3 Subscription Template Attributes..............................21 74 5.3.1 notify-recipient-uri (uri)..................................23 75 5.3.2 notify-pull-method (type2 keyword)..........................23 76 5.3.3 notify-events (1setOf type2 keyword)........................24 77 5.3.3.1 Standard Values for Subscribed Events.....................24 78 5.3.3.1.1 No Events...............................................25 79 5.3.3.1.2 Subscribed Printer Events...............................25 80 5.3.3.1.3 Subscribed Job Events...................................26 81 5.3.3.2 Rules for Matching of Subscribed Events...................28 82 5.3.3.2.1 Rules for Matching of Printer Events....................28 83 5.3.3.2.2 Rules for Matching of Job Events........................28 84 5.3.3.2.3 Special Cases for Matching Rules........................29 85 5.3.4 notify-attributes (1setOf type2 keyword)....................30 86 5.3.5 notify-user-data (octetString(63))..........................31 87 5.3.6 notify-charset (charset)....................................32 88 5.3.7 notify-natural-language (naturalLanguage)...................32 89 5.3.8 notify-lease-duration (integer(0:67108863)).................33 90 5.3.9 notify-time-interval (integer(0:MAX)).......................34 91 5.4 Subscription Description Attributes...........................35 92 5.4.1 notify-subscription-id (integer (1:MAX))...................36 93 5.4.2 notify-sequence-number (integer (0:MAX))....................36 94 5.4.3 notify-lease-expiration-time (integer(0:MAX))...............37 95 5.4.4 notify-printer-up-time (integer(1:MAX)).....................38 96 5.4.5 notify-printer-uri (uri)....................................38 97 5.4.6 notify-job-id (integer(1:MAX))..............................39 98 5.4.7 notify-subscriber-user-name (name(MAX)).....................39 99 6 Printer Description Attributes Related to Notification..........40 100 6.1 printer-state-change-time (integer(1:MAX))....................40 101 6.2 printer-state-change-date-time (dateTime).....................40 103 7 New Values for Existing Printer Description Attributes..........41 104 7.1 operations-supported (1setOf type2 enum)......................41 106 8 Attributes Only in Event Notifications..........................41 107 8.1 notify-subscribed-event (type2 keyword).......................42 108 8.2 notify-text (text(MAX)).......................................42 110 9 Event Notification Content......................................42 111 9.1 Content of Machine Consumable Event Notifications.............45 112 9.1.1 Event Notification Content Common to All Events.............46 113 9.1.2 Additional Event Notification Content for Job Events........48 114 9.1.3 Additional Event Notification Content for Printer Events....49 115 9.2 Content of Human Consumable Event Notification................49 116 9.2.1 Event Notification Content Common to All Events.............50 117 9.2.2 Additional Event Notification Content for Job Events........52 118 9.2.3 Additional Event Notification Content for Printer Events....53 120 10 Delivery Methods...............................................53 122 11 Operations for Notification....................................55 123 11.1 Subscription Creation Operations.............................56 124 11.1.1 Create-Job-Subscriptions Operation.........................56 125 11.1.1.1 Create-Job-Subscriptions Request.........................57 126 11.1.1.1.1 notify-job-id (integer(1:MAX)).........................57 127 11.1.1.2 Create-Job-Subscriptions Response........................57 128 11.1.2 Create-Printer-Subscriptions operation.....................59 129 11.1.2.1 Create-Printer-Subscriptions Request.....................59 130 11.1.2.2 Create-Printer-Subscriptions Response....................59 131 11.1.3 Job Creation Operations - Extensions for Notification......59 132 11.1.3.1 Job Creation Request.....................................60 133 11.1.3.2 Job Creation Response....................................61 134 11.2 Other Operations.............................................62 135 11.2.1 Restart-Job Operation - Extensions for Notification........62 136 11.2.2 Validate-Job Operation - Extensions for Notification.......62 137 11.2.3 Get-Printer-Attributes - Extensions for Notification.......63 138 11.2.4 Get-Subscription-Attributes operation......................64 139 11.2.4.1 Get-Subscription-Attributes Request......................64 140 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)).............65 141 11.2.4.1.2 "requested-attributes" (1setOf keyword)................65 142 11.2.4.2 Get-Subscription-Attributes Response.....................65 143 11.2.5 Get-Subscriptions operation................................66 144 11.2.5.1 Get-Subscriptions Request................................67 145 11.2.5.1.1 "notify-job-id" (integer(1:MAX)).......................68 146 11.2.5.1.2 "limit" (integer(1:MAX))...............................68 147 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword)..........68 148 11.2.5.1.4 "my-subscriptions" (boolean)...........................68 149 11.2.5.2 Get-Subscriptions Response...............................69 150 11.2.6 Renew-Subscription operation...............................70 151 11.2.6.1 Renew-Subscription Request...............................70 152 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)).............71 153 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX))...............71 154 11.2.6.2 Renew-Subscription Response..............................71 155 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX))...............72 156 11.2.7 Cancel-Subscription operation..............................72 157 11.2.7.1 Cancel-Subscription Request..............................73 158 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)).............73 159 11.2.7.2 Cancel-Subscription Response.............................73 161 12 Status Codes...................................................74 162 12.1 successful-ok-ignored-subscriptions (0x0003).................74 163 12.2 client-error-ignored-all-subscriptions (0x0414)..............75 165 13 Status Codes in Subscription Attributes Groups.................75 166 13.1 client-error-uri-scheme-not-supported (0x040C)...............75 167 13.2 client-error-attributes-or-values-not-supported (0x040B).....75 168 13.3 client-error-too-many-subscriptions (0x0415).................76 169 13.4 successful-ok-too-many-events (0x0005).......................76 170 13.5 successful-ok-ignored-or-substituted-attributes (0x0001).....76 172 14 Encodings of Additional Attribute Tags.........................76 174 15 Conformance Requirements.......................................76 175 15.1 Conformance requirements for clients.........................77 176 15.2 Conformance requirements for Printers........................77 178 16 Normative References...........................................78 180 17 Informative References.........................................79 182 18 Security Considerations........................................80 183 18.1 Client access rights.........................................80 184 18.2 Printer security threats.....................................82 185 18.3 Notification Recipient security threats......................82 187 19 IANA Considerations............................................82 188 19.1 Attribute Registrations......................................83 189 19.2 Additional Enum Attribute Value Registrations for the 190 "operations-supported" Printer Attribute..........................84 191 19.3 Operation Registrations......................................84 192 19.4 Status code Registrations....................................85 193 19.5 Attribute Group tag Registrations............................85 194 19.6 Registration of Events.......................................85 195 19.7 Registration of Event Notification Delivery Methods..........86 196 19.7.1 Requirements for Registration of Event Notification Delivery 197 Methods................................................86 198 19.7.1.1 Required Characteristics.................................86 199 19.7.1.2 Naming Requirements......................................87 200 19.7.1.3 Functionality Requirements...............................87 201 19.7.1.4 Usage and Implementation Requirements....................87 202 19.7.1.5 Publication Requirements.................................87 203 19.7.2 Registration Procedure.....................................88 204 19.7.2.1 Present the proposal to the Community....................88 205 19.7.2.2 Delivery Method Reviewer.................................88 206 19.7.2.3 IANA Registration........................................88 207 19.7.3 Delivery Method Document Registrations.....................89 208 19.7.4 Registration Template......................................89 210 20 Internationalization Considerations............................90 212 21 Contributors...................................................90 214 22 Author's Addresses.............................................91 216 A. Appendix - Model for Notification with Cascading Printers......92 218 B. Appendix - Distributed Model for Notification..................93 220 C. Appendix - Extended Notification Recipient.....................94 222 D. Appendix - Details about Conformance Terminology...............95 224 E. Appendix - Object Model for Notification.......................96 225 E.1 Appendix - Object relationships..............................97 226 E.2 Printer Object and Per-Printer Subscription Objects..........98 227 E.3 Job Object and Per-Job Subscription Objects..................98 229 F. Appendix - Per-Job versus Per-Printer Subscription Objects.....98 231 G. Appendix - Description of the base IPP documents...............99 233 H. Appendix - Full Copyright Statement...........................100 235 Tables 236 Table 1 - Subscription Template Attributes........................22 237 Table 2 - Subscription Description Attributes.....................36 238 Table 3 - Printer Description Attributes Associated with Notification 239 ..............................................................40 240 Table 4 - Operation-id assignments................................41 241 Table 5 - Attributes in Event Notification Content................47 242 Table 6 - Additional Event Notification Content for Job Events....48 243 Table 7 - Combinations of Events and Subscribed Events for "job- 244 impressions-completed" ........................................48 246 Table 8 - Additional Event Notification Content for Printer Events49 247 Table 9 - Printer Name in Event Notification Content..............51 248 Table 10 - Event Name in Event Notification Content...............51 249 Table 11 - Event Time in Event Notification Content...............51 250 Table 12 - Job Name in Event Notification Content.................52 251 Table 13 - Job State in Event Notification Content................52 252 Table 14 - Printer State in Event Notification Content............53 253 Table 15 - Information about the Delivery Method..................54 254 Table 16 - Printer Conformance Requirements for Operations........78 256 Figures 257 Figure 1 - Model for Notification.................................10 258 Figure 2 - Model for Notification with Cascading Printers.........93 259 Figure 3 - Opaque Use of a Notification Service Transparent to the 260 Client ........................................................94 261 Figure 4 - Use of an Extended Notification Recipient transparent to 262 the Printer ...................................................95 263 Figure 5 - Object Model for Notification..........................97 265 1 Introduction 267 This IPP notification specification is an OPTIONAL extension to 268 Internet Printing Protocol/1.1: Model and Semantics [RFC2911, 269 RFC2910]. See Appendix G for a description of the base IPP 270 documents. This document in combination with the following documents 271 is intended to meet the most important notification requirements 272 described in [ipp-not-req]: 274 Internet Printing Protocol (IPP): "Job Progress Attributes" 275 [ipp-prog] 276 Internet Printing Protocol (IPP): "The 'ippget' Delivery Method 277 for Event Notifications" [ipp-get-method] 279 This specification REQUIRES that clients and Printers support the 280 'ippget' Pull Delivery Method [ipp-get-method]. Conforming client 281 and Printer implementations MAY support additional Push or Pull 282 Delivery Methods as well. Note: this document does not define any 283 Delivery Methods itself, but it does define the rules for conformance 284 for Delivery Method Documents and their registration with IANA (see 285 section 19.7.3). 287 Refer to the Table of Contents for the layout of this document. 289 1.1 Notification Overview 291 This document defines operations that a client can perform in order 292 to create Subscription Objects in a Printer and carry out other 293 operations on them. A Subscription Object represents a Subscription 294 abstraction. The Subscription Object specifies that when one of the 295 specified Events occurs, the Printer sends an asynchronous Event 296 Notification to the specified Notification Recipient via the 297 specified Delivery Method (i.e., protocol). 299 When a client (called a Subscribing Client) performs an operation 300 that creates a Subscription Object, the operation contains one or 301 more Subscription Template Attributes Groups. Each such group holds 302 information used by the Printer to initialize a newly created 303 Subscription Object. The Printer creates one Subscription Object for 304 each Subscription Template Attributes Group in the operation. This 305 group is like the Job Template Attributes group defined in [RFC2911]. 306 The following is an example of the information included in a 307 Subscription Template Attributes Group (see section 5 for details on 308 the Subscription Object attributes): 310 1.The names of Subscribed Events that are of interest to the 311 Notification Recipient. 312 2.The address (URL) of one Notification Recipient for a Push 313 Delivery Method or the method for a Pull Delivery Method. 314 3.The Delivery Method (i.e., the protocol) which the Printer uses 315 to send the Event Notification. 316 4.Some opaque data that the Printer sends to the Notification 317 Recipient in the Event Notification. The Notification Recipient 318 might use this opaque data as a forwarding address for the Event 319 Notification. 320 5.The charset to use in text fields within an Event Notification 321 6.The natural language to use in the text fields of the Event 322 Notification 323 7.The requested lease time in seconds for the Subscription Object 324 An operation that creates a Subscription Object is called a 325 Subscription Creation Operation. These operations include the 326 following operations (see section 11.1 for further details): 328 - Job Creation operation: When a client performs such an 329 operation (Print-Job, Print-URI, and Create-Job), a client can 330 include zero or more Subscription Template Attributes Groups in 331 the request. The Printer creates one Subscription Object for 332 each Subscription Template Attributes Group in the request, and 333 the Printer associates each such Subscription Object with the 334 newly created Job. This document extends these operations' 335 definitions in [RFC2911] by adding Subscription Template 336 Attributes Groups in the request and Subscription Attributes 337 Groups in the response. 339 - Create-Job-Subscriptions operation: A client can include one or 340 more Subscription Template Attributes Groups in the request. 341 The Printer creates one Subscription Object for each 342 Subscription Template Attributes Group and associates each with 343 the job that is the target of this operation. 345 - Create-Printer-Subscriptions operation: A client can include 346 one or more Subscription Template Attributes Groups in the 347 request. The Printer creates one Subscription Object for each 348 Subscription Template Attributes Group and associates each with 349 the Printer that is the target of this operation. 351 For each of the above operations: 353 - the Printer associates a Subscription Object with the Printer 354 or a specific Job. When a Subscription Object is associated 355 with a Job Object, it is called a Per-Job Subscription Object. 356 When a Subscription Object is associated with a Printer Object, 357 it is called a Per-Printer Subscription Object. 359 - the response contains one Subscription Attributes Group for 360 each Subscription Template Attributes Group in the request and 361 in the same order. When the Printer successfully creates a 362 Subscription Object, its corresponding Subscription Attributes 363 Group contains the "notify-subscription-id" attribute. This 364 attribute uniquely identifies the Subscription Object and is 365 analogous to a "job-id" for a Job object. Some operations 366 described below use the "notify-subscription-id" to identify 367 the target Subscription Object. 369 This document defines the following additional operations (see 370 section 11.2 for further details): 372 - Restart-Job operation: When a client performs the Restart-Job 373 operation [RFC2911], the Printer re-uses the same Job and its 374 Subscription Objects. 376 - Validate-Job operation: When a client performs this operation, 377 a client can include zero or more Subscription Template 378 Attributes Groups in the request. The Printer determines if it 379 could create one Subscription Object for each Subscription 380 Template Attributes Group in the request. This document 381 extends this operation's definition in [RFC2911] by adding 382 Subscription Template Attributes Groups in the request and 383 Subscription Attributes Groups in the response. 385 - Get-Subscription-Attributes operation: This operation allows a 386 client to obtain the specified attributes of a target 387 Subscription Object. 389 - Get-Subscriptions operation: This operation allows a client to 390 obtain the specified attributes of all Subscription Objects 391 associated with the Printer or a specified Job. 393 - Renew-Subscription operation: This operation renews the lease 394 on the target Per-Printer Subscription Object before it 395 expires. A newly created Per-Printer Subscription Object 396 receives an initial lease. It is the duty of the client to use 397 this operation frequently enough to preserve a Per-Printer 398 Subscription Object. The Printer deletes a Per-Printer 399 Subscription Object when its lease expires. A Per-Job 400 Subscription Object last exactly as long as its associated Job 401 Object and thus doesn't have a lease. 403 - Cancel-Subscription operation: This operation (1) cancels the 404 lease on the specified Per-Printer Subscription Object and 405 thereby deletes the Per-Printer Subscription Object or (2) 406 deletes the Per-Job Subscription Object. 408 When an Event occurs, the Printer finds all Subscription Objects 409 listening for the Event (see section 9 for details on finding such 410 Subscription Objects). For each such Subscription Object, the 411 Printer: 413 a)generates an Event Notification with information specified in 414 section 9, AND 415 b)either: 416 i) If the Delivery Method is a Push Delivery Method as 417 indicated by the presence of the Subscription Object's 418 "notify-recipient-uri" attribute, delivers the Event 419 Notification using the Delivery Method and target address 420 identified in the Subscription Object's "notify-recipient- 421 uri" attribute, OR 422 ii) If the Delivery Method is a Pull Delivery Method as 423 indicated by the presence of the Subscription Object's 424 "notify-pull-method" attribute, saves Event Notification 425 for a time period called the Event Life defined by the 426 Delivery Method, i.e., the Notification Recipient is 427 expected to fetch the Event Notifications. 429 2 Models for Notification 431 2.1 Model for Notification (Simple Case) 433 As part of a Subscription Creation Operation, an IPP Printer (i.e., 434 located in an output device or a server) creates one or more 435 Subscription Objects. In a Subscription Creation Operation, the 436 client specifies the Notification Recipient to which the Printer is 437 to deliver Event Notifications. A Notification Recipient can be the 438 Subscribing Client or a third party. 440 Figure 1 shows the Notification model for a simple Client-Printer 441 relationship. 443 embedded printer: 444 output device or server 445 PDA, desktop, or server +---------------+ 446 +--------+ | ########### | 447 | client |-----Subscription ---------># Printer # | 448 +--------+ Creation Operation | # Object # | 449 +------------+ | #####|##### | 450 |Notification| +-------|-------+ 451 |Recipient |<----IPP Event Notifications----+ 452 +------------+ (Job and/or Printer Events) 454 Figure 1 - Model for Notification 456 2.2 Model for Notification with Cascading Printers 458 With this model, there is an intervening Print server between the 459 human user and the Printer in the output device. If the Printer in 460 the output device generates an Event, the system can be configured to 461 send Event Notification either 463 - directly to the Notification Recipient specified by the 464 Subscribing Client or 466 - via the Print Server to the Notification Recipient specified by 467 the Subscribing Client. 469 See Appendix A for more details. 471 2.3 Distributed Model for Notification 473 The preceding sections (2.1 and 2.2) assume that the Notification 474 software resides in the same device or Server box as the rest of the 475 Printer software. In many implementations, the assumption is 476 correct. However, the Notification model also permits a distributed 477 implementation. 479 For example, the software that supports both Subscription Creation 480 Operations and sending of Event Notifications could be on hardware 481 that is separate from the output device. To make this work, there 482 must be a symbiotic relationship between the output device software 483 and the remote Notification software. Without the remote 484 Notification software, the output device software is not a complete 485 Printer. 487 The term "Printer" in this document includes the software on the 488 output device or server box as well as Notification software that is 489 local to or remote from the output device. 491 Appendix B describes this example in detail. 493 2.4 Extended Notification Recipient 495 The model allows for an extended Notification Recipient that is 496 itself a Notification service that forwards each Event Notification 497 to another recipient. The client contacts this Notification 498 Recipient to arrange for forwarding by means outside the scope of 499 this document. The Printer need not be aware that the Notification 500 Recipient forwards Event Notifications. 502 Appendix C describes this example in detail. 504 3 Terminology 506 This section defines terminology used throughout this document. 507 Other terminology is defined in [RFC2911]. 509 3.1 Conformance Terminology 511 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 512 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 513 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 514 12.1. If an implementation supports the extension defined in this 515 document, then these terms apply; otherwise, they do not. These 516 terms define conformance to this document only; they do not affect 517 conformance to other documents, unless explicitly stated otherwise. 518 See Appendix D for complete details. 520 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 521 the Printer implements a Delivery Method that REQUIRES the feature. 523 READ-ONLY - an adjective used in an attribute definition to indicate 524 that an IPP Printer MUST NOT allow the attribute's value to be 525 modified. 527 3.2 Other Terminology 529 This document uses the same terminology as [RFC2911], such as 530 "client", "Printer", "attribute", "attribute value", "keyword", 531 "operation", "request", "response", and "support". In addition, the 532 following terms are defined for use in this document and the Delivery 533 Method Documents: 535 Administrator - A human user who establishes policy for and 536 configures the print system. 538 Operator - A human user who carries out the policy established by the 539 Administrator and controls the day to day running of the print 540 system. 542 IPP Client (or client) - The software component (PDA, desktop, or 543 server) that performs an IPP operation directed at an IPP Printer 544 (located in a server or output device). 546 Job Creation operation - One of the operations that creates a Job 547 object: Print-Job, Print-URI and Create-Job. The Restart-Job 548 operation [RFC2911] is not considered a Job Creation operation, 549 since the Printer re-uses the existing Job object. The Validate- 550 Job operation is not considered a Job Creation operation because 551 no Job object is created. Therefore, when a statement also 552 applies to either the Restart-Job and/or the Validate-Job 553 operation, they are mentioned explicitly. 555 Event - some occurrence (either expected or unexpected) within the 556 printing system of a change of state, condition, or configuration 557 of a Job or Printer object. An Event occurs only at one instant 558 in time and does not span the time the physical Event takes place. 559 For example, jam-occurred and jam-cleared are two distinct, 560 instantaneous Events, even though the jam may last for a while. 562 Event Notification - the information about an Event that the Printer 563 sends when an Event occurs. 565 Compound Event Notification - two or more Event Notifications that a 566 Printer sends together as a single entity. The Delivery Method 567 Document specifies whether the Delivery Method supports Compound 568 Event Notifications. 570 Job Event - an Event caused by some change in a particular job on the 571 Printer, e.g., 'job-completed'. 573 Printer Event - an Event caused by some change in the Printer that is 574 not specific to a job, e.g., 'printer-state-changed'. 576 Subscribed Event - an Event that the Subscribing Client expresses 577 interest in by making it a value of the "notify-events" attribute 578 on a Subscription Object. 580 Subscribed Job Event - a Subscribed Event that is a Job Event. 582 Subscribed Printer Event - a Subscribed Event that is a Printer 583 Event. 585 Notification Recipient - the entity to which the Printer sends an 586 Event Notification. 588 Delivery Method - the mechanism by which the Printer delivers the 589 Event Notification, e.g., via email or via an Event Notification 590 Delivery Method protocol defined for delivering IPP Event 591 Notifications. 593 Delivery Method Document - a document, separate from this document, 594 that defines a Delivery Method. 596 Push Delivery Method -The Printer sends the Event Notification 597 shortly after an Event occurs. For some Push Delivery Methods, 598 the Notification Recipient MUST send a response; for others it 599 MUST NOT send a response. 601 Pull Delivery Method - The Printer saves Event Notifications for some 602 event life time and expects the Notification Recipient to request 603 Event Notifications. The Printer returns the Event Notifications 604 in a response to such a request. 606 Event Life - For a Pull Delivery Method, the length of time in 607 seconds after an Event occurs during which the Printer will 608 return that Event in response to a request for Event 609 Notifications. After the Event Life expires, the Printer will 610 no longer return an Event Notification for that Event in such a 611 response. 613 Subscription Object - An object containing a set of attributes that 614 indicate: the Notification Recipient, the Delivery Method, the 615 Subscribed Events that cause the Printer to send an Event 616 Notification, and the information to send in an Event 617 Notification. 619 Per-Job Subscription Object - A Subscription Object that is 620 associated with a single Job. The Create-Job-Subscriptions 621 operation and Job Creation operations create such an object. 623 Per-Printer Subscription Object - A Subscription Object that is 624 associated with the Printer as a whole. The Create-Printer- 625 Subscriptions operation creates such an object. 627 Subscribing Client - The client that creates the Subscription Object. 629 Subscription Creation Operation - An operation that creates a 630 Subscription Object: Job Creation operations, Create-Job- 631 Subscriptions operation, Create-Printer-Subscriptions operation. 632 In the context of a Job Creation operation, a Subscription 633 Creation Operation is the part of the Job Creation operation that 634 creates a Subscription object. The Restart-Job operation 635 [RFC2911] is not considered a Subscription Creation Operation, 636 since the Printer re-uses the Job's existing Subscription Objects, 637 rather than creating any new Subscription Objects. 639 Subscription Creation Request - The request portion of a Subscription 640 Creation Operation. 642 Subscription Template Attributes - Subscription Object attributes 643 that a client can supply in a Subscription Creation Operation and 644 associated Printer Object attributes that specify supported and 645 default values for the Subscription Object attributes. 647 Subscription Description Attributes - Subscription Object attributes 648 that a Printer supplies during a Subscription Creation Operation. 650 Subscription Template Attributes Group - The attributes group in a 651 request that contains Subscription Object attributes that are 652 Subscription Template Attributes. 654 Subscription Attributes Group - The attributes group in a response 655 that contains Subscription Object attributes. 657 Human Consumable Event Notification - localized text for human 658 consumption only. There is no standardized format and thus 659 programs should not try to parse this text. 661 Machine Consumable Event Notification - bytes for program 662 consumption. The bytes are formatted according to the Delivery 663 Method document. 665 Printer - the software that supports an output device or print server 666 (see IPP/1.1 [RFC2911] which uses the terms Printer and Printer 667 object interchangeably). This document extends the IPP/1.1 668 Printer definition to include the software that implements 669 Subscription Creation Operations and the sending of Event 670 Notifications, even if the software for such a Printer would be 671 distributed across a network (see section 2.3). 673 Notification - when not in the phrases 'Event Notification' and 674 'Notification Recipient' - the concepts of this specification, 675 i.e., Events, Subscription Objects, and Event Notifications. 677 4 Object Relationships 679 This section defines the object relationships between the Printer, 680 Job, and Subscription Objects. It does not define the 681 implementation. For an illustration of these relationships, see 682 Appendix E. 684 4.1 Printer and Per-Printer Subscription Objects 686 1.A Printer object can be associated with zero or more Per-Printer 687 Subscription Objects. 689 2.Each Per-Printer Subscription Object is associated with exactly 690 one Printer object. 692 4.2 Printer, Job and Per-Job Subscription Objects 694 1.A Printer object is associated with zero or more Job objects. 696 2.Each Job object is associated with exactly one Printer object. 698 3.A Job object is associated with zero or more Per-Job Subscription 699 Objects. 701 4.Each Per-Job Subscription Object is associated with exactly one 702 Job object. 704 5 Subscription Object 706 A Subscribing Client creates a Subscription Object with a 707 Subscription Creation Operation in order to indicate its interest in 708 certain Events. See section 11 for a description of these 709 operations. When an Event occurs, the Subscription Object specifies 710 to the Printer where to send Event Notifications, how to send them 711 and what to put in them. See section 9 for details on the contents 712 of an Event Notification. 714 Using the IPP Job Template attributes as a model (see [RFC2911] 715 section 4.2), the attributes of a Subscription Object are divided 716 into two categories: Subscription Template Attributes and 717 Subscription Description Attributes. 719 Subscription Template attributes are, in turn, like the Job Template 720 attributes, divided into 722 1.Subscription Object attributes that a client can supply in a 723 Subscription Creation Request and 725 2.their associated Printer Object attributes that specify 726 supported and default values for the Subscription Object 727 attributes 729 The remainder of this section specifies general rules for 730 Subscription Template Attributes and describes each attribute in a 731 Subscription Object. 733 5.1 Rules for Support of Subscription Template Attributes 735 Subscription Template Attributes are fundamental to the Notification 736 model described in this specification. The client supplies these 737 attributes in Subscription Creation Operations and the Printer uses 738 these attributes to populate a newly created Subscription Object. 740 Subscription Objects attributes that are Subscription Template 741 Attributes conform to the following rules: 743 1.Each attribute's name starts with the prefix string "notify-" 744 and this document calls such attributes "notify-xxx". 746 2.For each "notify-xxx" Subscription Object attribute defined in 747 column 1 of Table 1 in section 5.3, Table 1 specifies 748 corresponding Printer attributes: "notify-xxx-default", "notify- 749 xxx-supported", "yyy-supported" and "notify-max-xxx-supported" 750 defined in column 2 of Table 1. Note "xxx" stands for the same 751 string in each case and "yyy" stands for some other string. 753 3.If a Printer supports "notify-xxx" in column 1 of Table 1, then 754 the Printer MUST support all associated attributes specified in 755 column 2 of Table 1. For example, Table 1 shows that if the 756 Printer supports "notify-events", it MUST support "notify- 757 events-default", "notify-events-supported" and "notify-max- 758 events-supported". 760 4.If a Printer does not support "notify-xxx" in column 1 of Table 761 1, then the Printer MUST NOT support any associated "notify-yyy" 762 attributes specified in column 2 of Table 1. For example, Table 763 1 shows that if the Printer doesn't support "notify-events", it 764 MUST NOT support "notify-events-default", "notify-events- 765 supported" and "notify-max-events-supported". Note this rule 766 does not apply to attributes whose names do not start with the 767 string "notify-" and are thus defined in another object and used 768 by other attributes. 770 5.Most "notify-xxx" attributes have a corresponding "yyy- 771 supported" attribute that specifies the supported values for 772 "notify-xxx". Column 2 of Table 1 specifies the name of each 773 "yyy-supported" attribute. The naming rules of IPP/1.1 (see 774 [RFC2911]) are used when "yyy-supported" is "notify-xxx- 775 supported". 777 6.Some "notify-xxx" attributes have a corresponding "notify-xxx- 778 default" attribute that specifies the value for "notify-xxx" if 779 the client does not supply it. Column 2 of Table 1 specifies 780 the name of each "notify-xxx-default" attribute. The naming 781 rules of IPP/1.1 (see [RFC2911]) are used. 783 If a client wishes to present an end user with a list of supported 784 values from which to choose, the client SHOULD query the Printer for 785 its supported value attributes. The client SHOULD also query the 786 default value attributes. If the client then limits selectable 787 values to only those values that are supported, the client can 788 guarantee that the values supplied by the client in the create 789 request all fall within the set of supported values at the Printer. 790 When querying the Printer, the client MAY enumerate each attribute by 791 name in the Get-Printer-Attributes Request, or the client MAY just 792 supply the 'subscription-template' group name in order to get the 793 complete set of supported attributes (both supported and default 794 attributes - see section 11.2.3). 796 5.2 Rules for Processing Subscription Template Attributes 798 This section defines a detailed set of rules that a Printer follows 799 when it processes Subscription Template Attributes in a Subscription 800 Creation Request. These rules are similar to the rules for 801 processing Operation attributes in [RFC2911]. That is, the Printer 802 may or may not support an attribute and a client may or may not 803 supply the attribute. Some combinations of these cases are OK. 804 Others return warnings or errors, and perhaps a list of unsupported 805 attributes. 807 A Printer MUST implement the following behavior for processing 808 Subscription Template Attributes in a Subscription Creation Request: 810 1.If a client supplies a "notify-xxx" attribute from column 1 of 811 Table 1 and the Printer supports it and its value, the Printer 812 MUST populate the attribute on the created Subscription Object. 814 2.If a client supplies a "notify-xxx" attribute from column 1 of 815 Table 1 and the Printer doesn't support it or its value, the 816 Printer MUST NOT populate the attribute on the created 817 Subscription Object with it. The Printer MUST do one of the 818 following: 820 a) If the value of the "notify-xxx" attribute is unsupported, the 821 Printer MUST return the attribute with its value in the 822 Subscription Attributes Group of the response. 824 b) If "notify-xxx" is an unsupported attribute, the Printer MUST 825 return the attribute in the Subscription Attributes Group of the 826 response with the 'unsupported' out-of-band value. 828 Note: The rules of this step are the same as for Unsupported 829 Attributes [RFC2911] section 3.1.7. except that the unsupported 830 attributes are returned in the Subscription Attributes Group 831 rather than the Unsupported Attributes Group because Subscription 832 Creation Operations can create more than one Subscription Object). 834 3.If a client is REQUIRED to supply a "notify-xxx" attribute from 835 column 1 of Table 1 and the Printer doesn't support the supplied 836 value, the Printer MUST NOT create a Subscription Object. The 837 rules for Unsupported Attributes in step #2 still apply. 839 4.If a client does not supply a "notify-xxx" attribute from column 1 840 of Table 1 and the attribute is REQUIRED for the client to supply, 841 the Printer MUST reject the Subscription Creation Operation 842 (including Job Creation operations) without creating a 843 Subscription Object, and MUST return in the response: 845 c) the status code 'client-error-bad-request' AND 847 d) no Subscription Attribute Groups. 849 5.If a client does not supply a "notify-xxx" attribute from column 1 850 of Table 1 that is OPTIONAL for the client to supply, and column 2 851 of Table 1 either: 853 a) specifies a "notify-xxx-default" attribute, the Printer MUST 854 behave as if the client had supplied the "notify-xxx-default" 855 attribute (see step #1) and populate the Subscription object 856 with the value of the "notify-xxx-default" attribute as part of 857 the Subscription Creation operation (unlike Job Template 858 attributes where the Printer does not populate the Job object 859 with defaults - see [RFC2911]) OR 861 b) does not specify a "notify-xxx-default" attribute, the Printer 862 MUST populate the "notify-xxx" attribute on the Subscription 863 Object according to the definition of the "notify-xxx" attribute 864 in a section 5.3. For some attributes, the "notify-xxx" is 865 populated with the value of some other attribute, and for 866 others, the "notify-xxx" is NOT populated on the Subscription 867 object at all. 869 6.A Printer MUST create a Subscription Object for each Subscription 870 Template Attributes group in a request unless the Printer: 872 a) encounters some attributes in a Subscription Template Attributes 873 Group that require the Printer not to create the Subscription 874 Object OR 876 b) would create a Per-Job Subscription Object when it doesn't have 877 space for another Per-Job Subscription Object OR 879 c) would create a Per-Printer Subscription Object when it doesn't 880 have space for another Per-Printer Subscription Object. 882 7.A response MUST contain one Subscription Attributes Group for each 883 Subscription Template Attributes Group in the request (and in the 884 same order) whether the Printer creates a Subscription Object from 885 the Subscription Template Attributes Group or not. However, the 886 attributes in each Subscription Attributes Group can be in any 887 order. 889 8.The Printer MUST populate each Subscription Attributes Group of 890 the response such that each contains: 892 a) the "notify-subscription-id" attribute (see section 5.4.1), if 893 and only if the Printer creates a Subscription Object. 895 b) the "notify-lease-duration" attribute (see section 5.3.8), if 896 and only if the Printer creates a Per-Printer Subscription 897 Object. The value of this attribute is the value of the 898 Subscription Object's "notify-lease-duration" attribute. This 899 value MAY be different from the client-supplied value (see 900 section 5.3.8). If a client supplies this attribute in the 901 creation of a Per-Job Subscription Object, it MUST appear in 902 this group with the out-of-band value 'unsupported' to indicate 903 that the Printer doesn't support it in this context. 905 c) all of the unsupported Subscription Template Attributes from 906 step #2. Note, they are not returned in the Unsupported 907 Attributes Group in order to separate the unsupported attributes 908 for each Subscription Object. 910 d) the "notify-status-code" attribute if the Printer does not 911 create the Subscription Object or if there are unsupported 912 attributes from step #2. The possible values of the "notify- 913 status-code" attribute are shown below (see section 13 for more 914 details). The Printer returns the first value in the list below 915 that describes the status. 917 'client-error-uri-scheme-not-supported': the Subscription 918 Object was not created because the scheme of the "notify- 919 recipient-uri" attribute is not supported. See section 920 13.1 for more details about this status code. See step #3 921 in this section for the case that causes this error, and 922 the resulting step #6a) that causes the Printer not to 923 create the Subscription Object. 925 'client-error-attributes-or-values-not-supported': the 926 Subscription Object was not created because the method of 927 the "notify-pull-method" attribute is not supported. See 928 section 13.1 for more details about this status code. See 929 step #3 in this section for the case that causes this 930 error, and the resulting step #6a) that causes the Printer 931 not to create the Subscription Object. 933 'client-error-too-many-subscriptions': the Subscription 934 Object was not created because the Printer has no space for 935 additional Subscription Objects. The client SHOULD try 936 again later. See section 13.3 for more details about this 937 status code. See steps #6b) and #6c) in this section for 938 the cases that causes this error. 940 'successful-ok-too-many-events': the Subscription Object was 941 created without the "notify-events" values included in this 942 Subscription Attributes Group because the "notify-events" 943 attribute contains too many values. See section 13.4 for 944 more details about this status code. See step #2 in this 945 section and section 5.3.3 for the cases that cause this 946 status code. 948 'successful-ok-ignored-or-substituted-attributes' : the 949 Subscription Object was created but some supplied 950 Subscription Template Attributes are unsupported. These 951 unsupported attributes are also in the Subscription 952 Attributes Group. See section 13.5 for more details about 953 this status code. See step #2 in this section for the 954 cases that cause this status code. 956 9.The Printer MUST validate all Subscription Template Attributes and 957 MUST return all unsupported attributes and values in the 958 corresponding Subscription Attributes Group of the response (see 959 step #2) unless it determines that it could not create additional 960 Subscription Objects because of condition #6b) or condition #6c). 962 Then, the Printer NEED NOT validate these additional Subscription 963 Template Attributes and the client MUST NOT expect to find 964 unsupported attributes from step #2 in such additional 965 Subscription Attribute Groups. 967 5.3 Subscription Template Attributes 969 This section contains the Subscription Template Attributes defined 970 for the Subscription and Printer objects. 972 Table 1 below shows the Subscription Template Attributes and has two 973 columns: 975 - Attribute in Subscription Object: the name and attribute syntax 976 of each Subscription Object Attribute that is a Subscription 977 Template Attribute 979 - Default and Supported Printer Attributes: the default attribute 980 and supported Printer attributes that are associated with the 981 attribute in column 1. 983 The "notify-recipient-uri" attribute is for use with Push Delivery 984 Methods. The "notify-pull-method" attribute is for use with Pull 985 Delivery Methods. 987 For Push Delivery Methods, a Printer MUST support all attributes in 988 Table 1 below except for "notify-pull-method" and "notify-attributes" 989 (and "notify-pull-method-supported" and "notify-attributes- 990 supported"). For Pull Delivery Methods, a Printer MUST support all 991 attributes in Table 1 below except for "notify-recipient-uri" and 992 "notify-attributes" (and "notify-schemes-supported" and "notify- 993 attributes-supported"). If a Printer supports both Push and Pull 994 Delivery Methods, then it MUST support both "notify-recipient-uri" 995 and "notify-pull-method" attributes. 997 For Pull Delivery Methods, a client MUST supply "notify-recipient- 998 uri" and MAY omit any of the rest of the attributes in column 1 of 999 Table 1 in a Subscription Creation Request. For Push Delivery 1000 Methods, a client MUST supply "notify-pull-method" and MAY omit any 1001 of the rest of the attributes in column 1 of Table 1 in a 1002 Subscription Creation Request. A client MUST NOT supply both 1003 "notify-recipient-uri" and "notify-pull-method" attributes in the 1004 same Subscription Creation Request. 1006 Note: The Default and Supported Printer attributes listed in column 1007 2 of Table 1 do not have separate sections in this specification 1008 defining their semantics. Instead, the section for the corresponding 1009 Subscription Object attribute (column 1 of Table 1) contains the 1010 semantics of these Printer attributes. This approach follows the 1011 precedence of the Job Template attributes in section 4.2 of [RFC2911] 1012 where the corresponding "xxx-default" and "xxx-supported" Printer 1013 attributes are defined in the same section as the "xxx" Job 1014 attribute. 1016 Table 1 - Subscription Template Attributes 1018 Attribute in Subscription Default and Supported Printer 1019 Object Attributes 1021 notify-recipient-uri (uri) * notify-schemes-supported (1setOf 1022 uriScheme) 1024 notify-pull-method (type2 -pull-method-supported (1setOf 1025 keyword) ** type2ykeyword) 1027 notify-events (1setOf type2 notify-events-default (1setOf type2 1028 keyword) keyword) 1029 notify-events-supported (1setOf type2 1030 keyword) 1031 notify-max-events-supported 1032 (integer(2:MAX)) 1034 notify-attributes (1setOf notify-attributes-supported (1setOf 1035 type2 keyword) type2 keyword) 1037 notify-user-data 1038 (octetString(63)) 1040 notify-charset (charset) charset-supported (1setOf charset) 1042 notify-natural-language generated-natural-language-supported 1043 (naturalLanguage) (1setOf naturalLanguage) 1045 notify-lease-duration notify-lease-duration-default 1046 (integer(0:MAX)) (integer(0:67108863)) 1047 notify-lease-duration-supported 1048 (1setOf (integer(0: 67108863) | 1049 rangeOfInteger(0:67108863))) 1051 notify-time-interval 1052 (integer(0:MAX)) 1054 * "notify-recipient-uri" is for Push Delivery Methods only. 1055 ** "notify-pull-method" is for Pull Delivery Methods only. 1057 5.3.1 notify-recipient-uri (uri) 1059 This attribute's value is a URL, which is a special case of a URI. 1060 Its value consists of a scheme and an address. The address specifies 1061 the Notification Recipient and the scheme specifies the Push Delivery 1062 Method for each Event Notification associated with this Subscription 1063 Object. 1065 If a Printer supports any Push Delivery Methods, a Printer MUST 1066 support this attribute and return the value as supplied by the client 1067 (no case conversion or other canonicalization) in any operation 1068 response that includes this attribute. 1070 For a Push Delivery Method, a client MUST supply this attribute in a 1071 Subscription Creation Operation. Thus there is no need for a default 1072 Printer attribute. 1074 The URI scheme of the value of this attribute on a Subscription 1075 object MUST be a value of the "notify-schemes-supported (1setOf 1076 uriScheme)" Printer attribute. Note: According to [RFC2396] the ":" 1077 terminates the scheme and so is not part of the scheme. Therefore, 1078 values of the "notify-schemes-supported" Printer attribute do not 1079 include the ":" character. 1081 If the client supplies an unsupported scheme in the value of this 1082 attribute, then the Printer MUST NOT create the Subscription Object 1083 and MUST return the "notify-status-code" attribute with the 'client- 1084 error-uri-scheme-not-supported' value in the Subscription Attributes 1085 Group in the response. 1087 The Printer MUST treat the address part of this attribute as opaque. 1089 5.3.2 notify-pull-method (type2 keyword) 1091 This attribute's value is a type2 keyword indicating which Pull 1092 Delivery Method is to be used. 1094 Since a Printer MUST support the 'ippget' Pull Delivery Method [ipp- 1095 get-method] (see section 15), a Printer MUST support this attribute 1096 and return the value as supplied by the client in any operation 1097 response that includes this attribute. 1099 For a Pull Delivery Method, a client MUST supply this attribute in a 1100 Subscription Creation Operation. Thus there is no need for a default 1101 Printer attribute. 1103 The keyword value of this attribute on a Subscription object MUST be 1104 a value of the "notify-pull-method-supported (1setOf type2 keyword)" 1105 Printer attribute. 1107 If the client supplies an unsupported method in the value of this 1108 attribute, then the Printer MUST NOT create the Subscription Object 1109 and MUST return the "notify-status-code" attribute with the 'client- 1110 error-attributes-or-values-not-supported' value in the Subscription 1111 Attributes Group in the response. 1113 5.3.3 notify-events (1setOf type2 keyword) 1115 This attribute contains a set of Subscribed Events. When an Event 1116 occurs and it "matches" a value of this attribute, the Printer sends 1117 an Event Notification using information in the Subscription Object. 1118 The details of "matching" are described subsection 5.3.3.2. 1120 A Printer MUST support this attribute. 1122 A client MAY supply this attribute in a Subscription Creation 1123 Operation. If the client does not supply this attribute in 1124 Subscription Creation Operation, the Printer MUST populate this 1125 attribute on the Subscription Object with its "notify-events-default" 1126 attribute value. 1128 Each keyword value of this attribute on a Subscription Object MUST be 1129 a value of the "notify-events-supported (1setOf type2 keyword)" 1130 Printer attribute. 1132 The number of values of this attribute MUST NOT exceed the value of 1133 the "notify-max-events-supported" attribute. A Printer MUST support 1134 at least 2 values per Subscription Object. If the number of values 1135 supplied by a client in a Subscription Creation Operation exceeds the 1136 value of this attribute, the Printer MUST treat extra values as 1137 unsupported values and MUST use the value of 'successful-ok-too-many- 1138 events' for the "notify-status-code" attribute in the Subscription 1139 Attributes Group of the response. 1141 5.3.3.1 Standard Values for Subscribed Events 1143 Each value of this attribute is a keyword and it specifies a 1144 Subscribed Event that represents certain changes. Some keywords 1145 represent a subset of changes of another keyword, e.g., 'job- 1146 completed' is an Event value which is a sub-value of 'job-state- 1147 change'. See section 5.3.3.2 for the case where this attribute 1148 contains both a value and a sub-value. 1150 The values in this section are divided into three categories: No 1151 Events, Job Events and Printer Events. 1153 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1154 support the Events indicated as "OPTIONAL". 1156 5.3.3.1.1 No Events 1158 The standard and only keyword value for No Events is: 1160 'none': REQUIRED - no Event Notifications for any Events. As the 1161 sole value of "notify-events-supported", this value means that the 1162 Printer does not support the sending of Event Notifications. As 1163 the sole value of "notify-events-default", this value means that a 1164 client MUST specify the "notify-events" attribute in order for a 1165 Subscription Creation Operation to succeed. If the Printer 1166 receives this value as the sole value of a Subscription Creation 1167 Operation, it does not create a Subscription Object. If a Printer 1168 receives this value with other values of a Subscription Creation 1169 Operation, the Printer MUST treat this value as an unsupported 1170 value. 1172 5.3.3.1.2 Subscribed Printer Events 1174 The standard keyword values for Subscribed Printer Events are: 1176 'printer-state-changed': REQUIRED - the Printer changed state from 1177 any state to any other state. Specifically, the value of the 1178 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1179 accepting-jobs" attributes changed. 1181 This Subscribed Event value has the following sub-values: 1182 'printer-restarted' and 'printer-shutdown'. A client can listen 1183 for any of these sub-values if it doesn't want to listen to all 1184 printer-state changes: 1186 'printer-restarted': OPTIONAL - when the printer is powered 1187 up . 1189 'printer-shutdown': OPTIONAL - when the device is being 1190 powered down . 1192 'printer-stopped: REQUIRED - when the printer stops printing, 1193 i.e. the value of the "printer-state" Printer attribute 1194 becomes 'stopped'. 1196 'printer-config-changed': OPTIONAL - when the configuration of a 1197 Printer has changed, i.e., the value of the "printer-message-from- 1198 operator" or any "configuration" Printer attribute has changed. A 1199 "configuration" Printer attribute is an attribute which can change 1200 value because of some human interaction either direct or indirect, 1201 and which is not covered by one of the other Events in this 1202 section. Examples of "configuration" Printer attributes are any 1203 of the Job Template attributes, such as "xxx-supported", "xxx- 1204 ready" and "xxx-default". The client has to perform a Get- 1205 Printer-Attributes to find out the new values of these changed 1206 attributes. This Event is useful for GUI clients and drivers to 1207 update the available printer capabilities to the user. 1209 This Event value has the following sub-values: 'printer-media- 1210 changed' and 'printer-finishings-changed'. A client can listen 1211 for any of these sub-values if it doesn't want to listen to all 1212 printer-configuration changes: 1214 'printer-media-changed': OPTIONAL - when the media loaded on 1215 a printer has been changed, i.e., the "media-ready" 1216 attribute has changed. This Event includes two cases: an 1217 input tray that goes empty and an input tray that receives 1218 additional media of the same type or of a different type. 1219 The client must check the "media-ready" Printer attribute 1220 (see [RFC2911] section 4.2.11) separately to find out what 1221 changed. 1223 'printer-finishings-changed': OPTIONAL - when the finisher on 1224 a printer has been changed, i.e., the "finishings-ready" 1225 attribute has changed. This Event includes two cases: a 1226 finisher that goes empty and a finisher that is refilled 1227 (even if it is not full). The client must check the 1228 "finishings-ready" Printer attribute separately to find out 1229 what changed. 1231 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1232 Printer's queue has changed, so that an application that is 1233 monitoring the queue can perform a Get-Jobs operation to determine 1234 the new order. This Event does not include when a job enters the 1235 queue (the 'job-created' Event covers that) and does not include 1236 when a job leaves the queue (the 'job-completed' Event covers 1237 that). 1239 5.3.3.1.3 Subscribed Job Events 1241 The standard keyword values for Subscribed Job Events are: 1243 'job-state-changed': REQUIRED - the job has changed from any state 1244 to any other state. Specifically, the Printer sends this Event 1245 whenever the value of the "job-state" attribute or "job-state- 1246 reasons" attribute changes. When a Job is removed from the Job 1247 Retention or Job History phases (see [RFC2911] section 4.3.7.1), 1248 no Event is generated. 1250 This Event value has the following sub-values: 'job-created', 1251 'job-completed' and 'job-stopped'. A client can listen for any of 1252 these sub-values if it doesn't want to listen to all 'job-state 1253 changes'. 1255 'job-created': REQUIRED - the Printer has accepted a Job 1256 Creation operation, a Restart-Job operation [RFC2911], or 1257 any job operation that creates a Job object from an 1258 existing Job object. The Printer populates the job's 1259 "time-at-creation" attribute value (see [RFC2911] section 1260 4.3.14.1). The Printer puts the job in the 'pending', 1261 'pending-held' or 'processing' states. 1263 'job-completed': REQUIRED - the job has reached one of the 1264 completed states, i.e., the value of the job's "job-state" 1265 attribute has changed to: 'completed', 'aborted', or 1266 'canceled'. The Job's "time-at-completed" and "date-time- 1267 at-completed" (if supported) attributes are set (see 1268 [RFC2911] section 4.3.14). When a Job completes, a 1269 Notification Recipient MAY query the Job using the Get-Job- 1270 Attributes operation. To allow such a query, the Printer 1271 retains the Job in the Job Retention and/or the Job History 1272 phases (see [RFC2911] section 4.3.7.1) for a suitable 1273 amount of time that depends on implementation and the 1274 Delivery Methods supported. The Printer also sends this 1275 Event when a Job is removed with the Purge-Job operation 1276 (see [RFC2911] section 3.2.9). In this case, the Event 1277 Notification MUST report the 'job-state' as 'canceled' and 1278 the Job object is no longer present for query. 1280 'job-stopped: OPTIONAL - when the job stops printing, i.e. 1281 the value of the "job-state" Job attribute becomes 1282 'processing-stopped'. 1284 'job-config-changed': OPTIONAL - when the configuration of a job has 1285 changed, i.e., the value of the "job-message-from-operator" or any 1286 of the "configuration" Job attributes have changed. A 1287 "configuration" Job attribute is an attribute that can change 1288 value because of some human interaction either direct or indirect. 1289 Examples of "configuration" Job attributes are any of the job 1290 template attributes and the "job-name" attribute. The client 1291 performs a Get-Job-Attributes to find out the new values of the 1292 changed attributes. This Event is useful for GUI clients and 1293 drivers to update the job information to the user. 1295 'job-progress': OPTIONAL - when the Printer has completed Printing a 1296 sheet. See the separate [ipp-prog] specification for additional 1297 attributes that a Printer MAY send in an Event Notification caused 1298 by this Event. The "notify-time-interval" attribute affects this 1299 Event by causing the Printer NOT to send an Event Notification 1300 every time a 'job-progress' Events occurs. See section 5.3.9 for 1301 full details. 1303 5.3.3.2 Rules for Matching of Subscribed Events 1305 When an Event occurs, the Printer MUST find each Subscription object 1306 whose "notify-events" attribute "matches" the Event. The rules for 1307 "matching" of Subscribed Events are described separately for Printer 1308 Events and for Job Events. This section also describes some special 1309 cases. 1311 5.3.3.2.1 Rules for Matching of Printer Events 1313 Suppose that the Printer causes Printer Event E to occur. For each 1314 Per-Job or Per-Printer Subscription S in the Printer, if E equals a 1315 value of this attribute in S or E is a sub-value of a value of this 1316 attribute in S, the Printer MUST generate an Event Notification. 1318 Consider the example. There are three Subscription Objects each with 1319 the Subscribed Printer Event 'printer-state-changed'. Subscription 1320 Object A is a Per-Printer Subscription Object. Subscription Object B 1321 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1322 is a Per-Job Subscription Object for Job 2. When the Printer enters 1323 the 'stopped' state, the Printer sends an Event Notification to the 1324 Notification Recipients of Subscription Objects A, B, and C because 1325 this is a Printer Event. Note if Job 1 has already completed, the 1326 Printer would not send an Event Notification for its Subscription 1327 Object, even if Job 1 is retained in the Job Retention and/or the Job 1328 History phases (see [RFC2911] section 4.3.7.1). 1330 5.3.3.2.2 Rules for Matching of Job Events 1332 Suppose that Job J causes Job Event E to occur. 1334 1.For each Per-Printer Subscription S in the Printer, if E equals 1335 a value of this attribute in S or E is a sub-value of a value of 1336 this attribute in S, the Printer MUST generate an Event 1337 Notification. 1339 2.For each Per-Job Subscription S associated with Job J, if E 1340 equals a value of this attribute in S or E is a sub-value of a 1341 value of this attribute in S, the Printer MUST generate an Event 1342 Notification. 1344 3.For each Per-Job Subscription S that is NOT associated Job J, if 1345 E equals a value of this attribute in S or E is a sub-value of a 1346 value of this attribute in, the Printer MUST NOT generate an 1347 Event Notification from S. 1349 Consider the example: There are three Subscription Objects listening 1350 for the Job Event 'job-completed'. Subscription Object A is a Per- 1351 Printer Subscription Object. Subscription Object B is a Per-Job 1352 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1353 Subscription Object for Job 2. In addition, Per-Printer Subscription 1354 Object D is listening for the Job Event 'job-state-changed'. When 1355 Job 1 completes, the Printer sends an Event Notification to the 1356 Notification Recipient of Subscription Object A (because it is Per- 1357 Printer) and Subscription Object B because it is a Per-Job 1358 Subscription Object associated with the Job generating the Event. 1359 The Printer also sends an Event Notification to the Notification 1360 Recipient of Subscription Object D because 'job-completed' is a sub- 1361 value of 'job-state-changed' - the value that Subscription Object D 1362 is listening for. The Printer does not send an Event Notification to 1363 the Notification Recipients of Subscription Object C because it is a 1364 Per-Job Subscription Object associated with some Job other than the 1365 Job generating the Event. 1367 5.3.3.2.3 Special Cases for Matching Rules 1369 This section contains rule for special cases. 1371 If an Event matches Subscribed Events in two different Subscription 1372 Objects and the Printer would send two identical Event Notifications 1373 (except for the "notify-subscription-id" attribute) to the same 1374 Notification Recipient using the same Delivery Method, the Printer 1375 MUST send both Event Notifications. That is, the Printer MUST NOT 1376 try to consolidate seemingly identical Event Notifications that occur 1377 in separate Subscription objects. Incidentally, the Printer MUST NOT 1378 reject Subscription Creation Operations that would create this 1379 scenario. 1381 If an Event matches two values of this "notify-events" attribute in a 1382 single Subscription object (e.g., a value and its sub-value), a 1383 Printer MAY send one Event Notification for each matched value in the 1384 Subscription Object or it MAY send only one Event Notification per 1385 Subscription Object. The rules in sections 5.3.3.2.1 and 5.3.3.2.2 1386 are purposefully ambiguous about the number of Event Notification 1387 sent when Event E matches two or more values in a Subscription 1388 Object. 1390 Consider the example: There are two Per-Printer Subscription Objects 1391 when a Job completes. Subscription Object A has the Subscribed Job 1392 Event 'job-state-changed'. Subscription Object B has the Subscribed 1393 Job Events 'job-state-changed' and 'job-completed'. The Printer 1394 sends an Event Notification to the Notification Recipient of 1395 Subscription Object A with the value of 'job-state-changed' for the 1396 "notify-subscribing-event" attribute. The Printer sends either one 1397 or two Event Notifications to the Notification Recipient of 1398 Subscription Object B, depending on implementation. If it sends two 1399 Event Notifications, one has the value of 'job-state-changed' for 1400 the "notify-subscribing-event" attribute, and the other has the value 1401 of 'job-completed' for the "notify-subscribing-event" attribute. If 1402 it sends one Event Notification, it has the value of either 'job- 1403 state-changed' or 'job-completed' for the "notify-subscribing-event" 1404 attribute, depending on implementation. The algorithm for choosing 1405 such a value is implementation dependent. 1407 5.3.4 notify-attributes (1setOf type2 keyword) 1409 This attribute contains a set of attribute names. When a Printer 1410 sends a Machine Consumable Event Notification, it includes a fixed 1411 set of attributes (see section 9.1). If this attribute is present 1412 and the Event Notification is Machine Consumable, the Printer also 1413 includes the attributes specified by this attribute. 1415 A Printer MAY support this attribute. 1417 A client MAY supply this attribute in a Subscription Creation 1418 Operation. If the client does not supply this attribute in 1419 Subscription Creation Operation or the Printer does not support this 1420 attribute, the Subscription Object either (1) MAY contain the 1421 "notify-attributes" attribute with a 'none' value or (2) NEED NOT 1422 contain the attribute at all. There is no "notify-attributes- 1423 default" Printer attribute. 1425 Each keyword value of this attribute on a Subscription Object MUST be 1426 a value of the "notify-attributes-supported (1setOf type2 keyword)" 1427 Printer attribute. The "notify-attributes-supported" MAY contain any 1428 Printer attribute, Job attribute or Subscription Object attribute 1429 that the Printer supports in an Event Notification. It MUST NOT 1430 contain any of the attributes in Section 9.1 that a Printer 1431 automatically puts in an Event Notification; it would be redundant. 1432 If a client supplies an attribute in Section 9.1, the Printer MUST 1433 treat it as an unsupported attribute value of the "notify-attributes" 1434 attribute. 1436 The following rules apply to each keyword value N of the "notify- 1437 attributes" attribute: If the value N names: 1439 a)a Subscription attribute, the Printer MUST use the attribute N in 1440 the Subscription Object that is being used to generate the Event 1441 Notification. 1443 b)a Job attribute and the Printer is generating an Event 1444 Notification from a Per-Job Subscription Object S, the Printer 1445 MUST use the attribute N in the Job object associated with S. 1447 c)a Job attribute and the Printer is generating an Event 1448 Notification from a Per-Printer Subscription Object and the Event 1449 is: 1451 ? a Job Event, the Printer MUST use the attribute N in the Job 1452 object that caused the Event. 1454 ? a Printer Event, the Printer MUST use the attribute N in the 1455 active Job. 1457 If a Printer supports this attribute and a Subscription Object 1458 contains this attribute and the Delivery Method generates a Machine 1459 Consumable Event Notification, the Printer MUST include in each Event 1460 Notification: 1462 a)the attributes specified in section 9.1 and 1464 b)each attribute named by this attribute. 1466 The Printer MUST NOT use this attribute to generate a Human 1467 Consumable Event Notification. 1469 5.3.5 notify-user-data (octetString(63)) 1471 This attribute contains opaque data that some Delivery Methods 1472 include in each Machine Consumable Event Notification. The opaque 1473 data might contain, for example: 1475 - the identity of the Subscriber 1477 - a path or index to some Subscriber information 1479 - a key that identifies to the Notification Recipient the 1480 ultimate recipient of the Event Notification 1482 - the id for a Notification Recipient that had previously 1483 registered with an Instant Messaging Service 1485 A Printer MUST support this attribute. 1487 A client MAY supply this attribute in a Subscription Creation 1488 Operation. If the client does not supply this attribute in the 1489 Subscription Creation Operation, the Subscription Object either (1) 1490 MAY contain the "notify-user-data" attribute with a zero length value 1491 or (2) NEED NOT contain the attribute at all. There is no "notify- 1492 user-data-default" Printer attribute. 1494 There is no "notify-user-data-supported" Printer attribute. Rather, 1495 any octetString whose length does not exceed 63 octets is a supported 1496 value. If the length exceeds 63 octets, the Printer MUST treat it as 1497 an unsupported value. 1499 5.3.6 notify-charset (charset) 1501 This attribute specifies the charset to be used in the Event 1502 Notification content sent to the Notification Recipient, whether the 1503 Event Notification content is Machine Consumable or Human Consumable. 1505 A Printer MUST support this attribute. 1507 A client MAY supply this attribute in a Subscription Creation 1508 Operation. If the client does not supply this attribute in 1509 Subscription Creation Operation or supplies an unsupported value, the 1510 Printer MUST populate this attribute in the Subscription Object with 1511 the value of the "attributes-charset" operation attribute, which is a 1512 REQUIRED attribute in all IPP requests (see [RFC2911]). If the value 1513 of the "attributes-charset" attribute is unsupported, the Printer 1514 MUST populate this attribute in the Subscription Object with the 1515 value of the Printer's "charset-configured" attribute. There is no 1516 "notify-charset-default" Printer attribute. 1518 The value of this attribute on a Subscription Object MUST be a value 1519 of the "charset-supported (1setOf charset)" Printer attribute. 1521 5.3.7 notify-natural-language (naturalLanguage) 1523 This attribute specifies the natural language to be used in any human 1524 consumable text in the Event Notification content sent to the 1525 Notification Recipient, whether the Event Notification content is 1526 Machine Consumable or Human Consumable. 1528 A Printer MUST support this attribute. 1530 A client MAY supply this attribute in a Subscription Creation 1531 Operation. If the client does not supply this attribute in 1532 Subscription Creation Operation or supplies an unsupported value, the 1533 Printer MUST populate this attribute in the Subscription Object with 1534 the value of the "attributes-natural-language" operation attribute, 1535 which is a REQUIRED attribute in all IPP requests (see [RFC2911]). 1536 If the value of the "attributes-natural-language" attribute is 1537 unsupported, the Printer MUST populate this attribute in the 1538 Subscription Object with the value of the Printer's "natural- 1539 language-configured" attribute. There is no "notify-natural- 1540 language-default" Printer attribute. 1542 The value of this attribute on a Subscription Object MUST be a value 1543 of the "generated-natural-language-supported (1setOf type2 1544 naturalLanguage)" Printer attribute. 1546 5.3.8 notify-lease-duration (integer(0:67108863)) 1548 This attribute specifies the duration of the lease (in seconds) 1549 associated with the Per-Printer Subscription Object at the time the 1550 Subscription Object was created or the lease was renewed. The 1551 duration of the lease is infinite if the value is 0, i.e., the lease 1552 never expires. See section 5.4.3 on "notify-lease-expiration-time 1553 (integer(0:MAX))" for more details. 1555 This attribute is not present on a Per-Job Subscription Object 1556 because the Subscription Object lasts exactly as long as the 1557 associated Job object. See discussion of the 'job-completed' event 1558 in section 5.3.3.1.3 about retention of the Job object after 1559 completion. 1561 A Printer MUST support this attribute. 1563 For a Subscription Object Creation operation of a Per-Job 1564 Subscription Object, the client MUST NOT supply this attribute. If 1565 the client does supply this attribute, the Printer MUST treat it as 1566 an unsupported attribute. 1568 For a Subscription Creation Operation of a Per-Printer Subscription 1569 Object or a Renew-Subscription operation, a client MAY supply this 1570 attribute. If the client does not supply this attribute, the Printer 1571 MUST populate this attribute with its "notify-lease-duration-default" 1572 (0:67108863) attribute value. If the client supplies this attribute 1573 with an unsupported value, the Printer MUST populate this attribute 1574 with a supported value, and this value SHOULD be as close as possible 1575 to the value requested by the client. Note: this rule implies that a 1576 Printer doesn't assign the value of 0 (infinite) unless the client 1577 requests it. 1579 After the Printer has populated this attribute with a supported 1580 value, the value represents the "granted duration" of the lease in 1581 seconds and the Printer updates the value of the Subscription 1582 Object's "notify-lease-expiration-time" attribute as specified in 1583 section 5.4.3. 1585 The value of this attribute on a Subscription Object MUST be a value 1586 of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) 1587 | rangeOfInteger(0:67108863))) Printer attribute. 1589 A Printer MAY require authentication in order to return the value of 1590 0 (the lease never expires) as one of the values of "notify-lease- 1591 duration-supported", and to allow 0 as a value of the "notify-lease- 1592 duration" attribute. 1594 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1595 1 and is about 2 years in seconds. The value is considerably less 1596 than MAX so that there is virtually no chance of an overflow when it 1597 is added to "printer-up-time" to produce "notify-lease-expiration- 1598 time". 1600 5.3.9 notify-time-interval (integer(0:MAX)) 1602 The 'job-progress' Event occurs each time that a Printer completes a 1603 sheet. Some Notification Recipients do not want to receive an Event 1604 Notification every time this Event occurs. This attribute allows a 1605 Subscribing Client to request how often it wants to receive Event 1606 Notifications for 'job-progress' Events. The value of this attribute 1607 MAY be any nonnegative integer (0,MAX) indicating the minimum number 1608 of seconds between 'job-progress' Event Notifications. 1610 The Printer MUST support this attribute if and only if the Printer 1611 supports the 'job-progress' Event. 1613 A client MAY supply this attribute in a Subscription Creation 1614 Operation. If the client does not supply this attribute in the 1615 Subscription Creation Operation, the Subscription Object either (1) 1616 MAY contain the "notify-time-interval" attribute with a '0' value or 1617 (2) NEED NOT contain this attribute at all. There is no "notify- 1618 time-interval-default" Printer attribute. 1620 There is no "notify-time-interval-supported" Printer attribute. 1622 If the 'job-progress' Event occurs and a Subscription Object contains 1623 the 'job-progress' Event as a value of the 'notify-events' attribute, 1624 there are two cases to consider: 1626 1.This attribute is not present on the Subscription Object or has 1627 the value of 0. The Printer MUST generate and send an Event 1628 Notification (as is the case with other Events). 1630 2.This attribute is present with a nonzero value of N: 1632 a)If the Printer has not sent an Event Notification for the 'job- 1633 progress' Event for the associated Subscription Object within 1634 the past N seconds, the Printer MUST send an Event Notification 1635 for the Event that just occurred. Note when the Printer 1636 completes the first page of a Job, this rule implies that the 1637 Printer sends an Event Notification for a Per-Job Subscription 1638 Object. 1640 b)Otherwise, the Printer MUST NOT generate or send an Event 1641 Notification for the associated Subscription Object. The 1642 Printer MUST NOT increase the value of the "notify-sequence- 1643 number" Subscription Object attribute (i.e., the sequence of 1644 values of the "notify-sequence-number" attribute counts the 1645 Event Notifications that the Printer sent and not the Events 1646 that do not cause an Event Notification to be sent). 1648 It is RECOMMENDED that a Subscribing Client use this attribute when 1649 it subscribes to the 'job-progress' Event, and that the value be 1650 sufficiently large to limit the frequency with which the Printer 1651 sends Event Notifications requests. 1653 This attribute MUST NOT effect any Events other than 'job-progress'. 1655 5.4 Subscription Description Attributes 1657 Subscription Description Attributes are those attributes that a 1658 Printer adds to a Subscription Object at the time of its creation. 1660 A Printer MUST support all attributes in this Table 2. 1662 A client MUST NOT supply the attributes in Table 2 in a Subscription 1663 Template Attributes Group of a Subscription Creation Operation. 1664 There are no corresponding default or supported attributes. 1666 Table 2 - Subscription Description Attributes 1668 Subscription Object attributes: 1670 notify-subscription-id (integer(1:MAX)) 1672 notify-sequence-number (integer(0:MAX)) 1674 notify-lease-expiration-time (integer(0:MAX)) 1676 notify-printer-up-time (integer(1:MAX)) 1678 notify-printer-uri (uri) 1680 notify-job-id (integer(1:MAX)) 1682 notify-subscriber-user-name (name(MAX)) 1684 5.4.1 notify-subscription-id (integer (1:MAX)) 1686 This attribute identifies a Subscription Object instance with a 1687 number that is unique within the context of the Printer. The Printer 1688 generates this value at the time it creates the Subscription Object. 1690 A Printer MUST support this attribute. 1692 The Printer MAY assign the value of this attribute sequentially as it 1693 creates Subscription Objects. However, if there is no security on 1694 Subscription objects, sequential assignment exposes the system to a 1695 passive traffic monitoring threat. 1697 The Printer SHOULD avoid re-using recent values of this attribute 1698 during continuous operation of the Printer as well as across power 1699 cycles. Then a Subscribing Client is unlikely to find that a stale 1700 reference accesses a new Subscription Object. 1702 The 0 value is not permitted in order to allow for compatibility with 1703 "job-id" and with SNMP index values, which also cannot be 0. 1705 5.4.2 notify-sequence-number (integer (0:MAX)) 1707 The value of this attribute indicates the number of times that the 1708 Printer has generated and attempted to send an Event Notification for 1709 this Subscription object. When an Event Notification contains this 1710 attribute, the Notification Recipient can determine whether it missed 1711 some Event Notifications (i.e., numbers skipped) or received 1712 duplicates (i.e., same number twice). 1714 A Printer MUST support this attribute. 1716 When the Printer creates a Subscription Object, it MUST populate this 1717 attribute with a value of 0. This value indicates that the Printer 1718 has not sent any Event Notifications for this Subscription Object. 1720 Each time the Printer sends a newly generated Event Notification, it 1721 MUST increase the value of this attribute by 1. For some Delivery 1722 Methods, the Printer MUST include this attribute in each Event 1723 Notification, and the value MUST be the value after it is increased 1724 by 1. That is, the value of this attribute in the first Event 1725 Notification after Subscription object creation MUST be 1, the second 1726 MUST be 2, etc. If a Delivery Method is defined such that the 1727 Notification Recipient returns a response, the Printer can re-try 1728 sending an Event Notification a certain number of times with the same 1729 sequence number when the Notification Recipient fails to return a 1730 response. 1732 If a Subscription Object lasts long enough to reach the value of MAX, 1733 its next value MUST be 0, i.e., it wraps. 1735 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1737 This attribute specifies the time in the future when the lease on the 1738 Per-Printer Subscription Object will expire, i.e. the "printer-up- 1739 time" value at which the lease will expire. If the value is 0, the 1740 lease never expires. 1742 A Printer MUST support this attribute. 1744 When the Printer creates a Per-Job Subscription Object, this 1745 attribute MUST NOT be present - the Subscription Object lasts exactly 1746 as long as the associated Job object. See also the discussion of the 1747 'job-completed' event in section 5.3.3.1.3 about retention of the Job 1748 object after completion so that a Notification Recipient can query 1749 the Job object after receiving the 'job-completed' Event 1750 Notification. 1752 When the Printer creates a Per-Printer Subscription Object, it 1753 populates this attribute with a value that is the sum of the values 1754 of the Printer's "printer-up-time" attribute and the Subscription 1755 Object's "notify-lease-duration" attribute with the following 1756 exception. If the value of the Subscription Object's "notify-lease- 1757 duration" attribute is 0 (i.e., no expiration time), then the value 1758 of this attribute MUST be set to 0 (i.e., no expiration time). 1760 When the Printer powers up, it MUST populate this attribute in each 1761 persistent Subscription Object with a value using the algorithm in 1762 the previous paragraph. 1764 When the "printer-up-time" equals the value of this attribute, the 1765 Printer MUST delete the Subscription Object. A client can extend a 1766 lease of a Per-Printer Subscription Object with the Renew- 1767 Subscription operation (see section 11.2.6). 1769 Note: In order to compute the number of seconds remaining in a lease 1770 for a Per-Printer Subscription Object, a client can subtract the 1771 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1772 from the Subscription's "notify-lease-expiration-time" attribute. 1774 5.4.4 notify-printer-up-time (integer(1:MAX)) 1776 This attribute is an alias for the Printer's "printer-up-time" 1777 attribute " (see [RFC2911] section 4.4.29). In other words, when 1778 this attribute is queried with the Get-Subscriptions or Get- 1779 Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), 1780 the value returned is the current value of the Printer's "printer-up- 1781 time" attribute, rather than the time at which the Subscription 1782 Object was created. 1784 A Printer MUST support this attribute. 1786 When the Printer creates a Per-Job Subscription Object, this 1787 attribute MUST NOT be present. When the Printer creates a Per- 1788 Printer Subscription Object, this attribute MUST be present. 1790 Note: this attribute exists in a Per-Printer Subscription Object so 1791 that a client using the Get-Subscription-Attributes or Get- 1792 Subscription operations can convert the Per-Printer Subscription's 1793 "notify-lease-expiration-time" attribute to wall clock time with one 1794 request. If the value of the "notify-lease-expiration-time" 1795 attribute is not 0 (i.e., no expiration time), then the difference 1796 between the "notify-lease-expiration-time" attribute and the "notify- 1797 printer-up-time" is the remaining number of seconds on the lease from 1798 the current time. 1800 5.4.5 notify-printer-uri (uri) 1802 This attribute identifies the Printer object that created this 1803 Subscription Object. 1805 A Printer MUST support this attribute. 1807 During a Subscription Creation Operation, the Printer MUST populate 1808 this attribute with the value of the "printer-uri" operation 1809 attribute in the request. From the Printer URI, the client can, for 1810 example, determine what security scheme was used. 1812 5.4.6 notify-job-id (integer(1:MAX)) 1814 This attribute specifies whether the containing Subscription Object 1815 is a Per-Job or Per-Printer Subscription Object, and for Per-Job 1816 Subscription Objects, it specifies the associated Job. 1818 A Printer MUST support this attribute. 1820 If this attribute is not present, the Subscription Object MUST be a 1821 Per-Printer Subscription. If this attribute is present, the 1822 Subscription Object MUST be a Per-Job Subscription Object and this 1823 attribute MUST identify the Job with which the Subscription Object is 1824 associated. 1826 Note: This attribute could be useful to a Notification Recipient that 1827 receives an Event Notification generated from a Per-Job Subscription 1828 Object and caused by a Printer Event. The Event Notification gives 1829 access to the Printer and the Subscription Object. The Event 1830 Notification gives access to the associated Job only via this 1831 attribute. See discussion of the 'job-completed' event in section 1832 5.3.3.1.3 about retention of the Job object after completion so that 1833 a Notification Recipient can query the Job object after receiving the 1834 'job-completed' Event Notification. 1836 5.4.7 notify-subscriber-user-name (name(MAX)) 1838 This attribute contains the name of the user who performed the 1839 Subscription Creation Operation. 1841 A Printer MUST support this attribute. 1843 The Printer MUST populates this attribute with the most authenticated 1844 printable name that it can obtain from the authentication service 1845 over which the Subscription Creation Operation was received. The 1846 Printer uses the same mechanism for determining the value of this 1847 attribute as it does for a Job's "job-originating-user-name" (see 1848 [RFC2911] section 4.3.6). 1850 Note: To help with authentication, a Subscription Object may have 1851 additional private attributes about the user, e.g., a credential of a 1852 principal. Such private attributes are implementation-dependent and 1853 not defined in this document. 1855 6 Printer Description Attributes Related to Notification 1857 This section defines the Printer Description attributes that are 1858 related to Notification. Table 3 lists the Printer Description 1859 attributes, indicates the Printer support required for conformance, 1860 and whether or not the attribute is READ-ONLY (see section 3.1): 1862 Table 3 - Printer Description Attributes Associated with Notification 1864 Printer object attributes: REQUIRED READ-ONLY 1866 printer-state-change-time (integer(1:MAX)) No Yes 1868 printer-state-change-date-time (dateTime) No Yes 1870 6.1 printer-state-change-time (integer(1:MAX)) 1872 This OPTIONAL attribute records the most recent time at which the 1873 'printer-state-changed' Printer Event occurred whether or not any 1874 Subscription objects were listening for this event. This attribute 1875 helps a client or operator to determine how long the Printer has been 1876 in its current state. 1878 A Printer MAY support this attribute and if so, the attribute MUST be 1879 READ-ONLY. 1881 On power-up, the Printer MUST populate this attribute with the value 1882 of its "printer-up-time" attribute, so that it always has a value. 1883 Whenever the 'printer-state-changed' Printer Event occurs, the 1884 Printer MUST update this attribute with the value of the Printer's 1885 "printer-up-time" attribute. 1887 6.2 printer-state-change-date-time (dateTime) 1889 This OPTIONAL attribute records the most recent time at which the 1890 'printer-state-changed' Printer Event occurred whether or not there 1891 were any Subscription Objects listening for this event. This 1892 attribute helps a client or operator to determine how long the 1893 Printer has been in its current state. 1895 A Printer MAY support this attribute and if so, the attribute MUST be 1896 READ-ONLY. 1898 On power-up, the Printer MUST populate this attribute with the value 1899 of its "printer-current-time" attribute, so that it always has a 1900 value (see [RFC2911] section 4.4.30 on "printer-current-time"). 1901 Whenever the 'printer-state-changed' Printer Event occurs, the 1902 Printer MUST update this attribute with the value of the Printer's 1903 "printer-current-time" attribute. 1905 7 New Values for Existing Printer Description Attributes 1907 This section contains those attributes for which additional values 1908 are added. 1910 7.1 operations-supported (1setOf type2 enum) 1912 The following "operation-id" values are added in order to support the 1913 new operations defined in this document: 1915 Table 4 - Operation-id assignments 1917 Value Operation Name 1919 0x0016 Create-Printer-Subscriptions 1921 0x0017 Create-Job-Subscriptions 1923 0x0018 Get-Subscription-Attributes 1925 0x0019 Get-Subscriptions 1927 0x001A Renew-Subscription 1929 0x001B Cancel-Subscription 1931 8 Attributes Only in Event Notifications 1933 This section contains those attributes that exist only in Event 1934 Notifications and do not exist in any objects. 1936 8.1 notify-subscribed-event (type2 keyword) 1938 This attribute indicates the Subscribed Event that caused the Printer 1939 to send this Event Notification. This attribute exists only in Event 1940 Notifications. 1942 This attribute MUST contain one of the values of the "notify-events" 1943 attribute in the Subscription Object, i.e., one of the Subscribed 1944 Event values. Its value is the Subscribed Event that "matches" the 1945 Event that caused the Printer to send this Event Notification. This 1946 Subscribed Event value may be identical to the Event or the Event may 1947 be a sub-value of the Subscribed Event. For example, the 'job- 1948 completed' Event (which is a sub-event of the 'job-state-changed' 1949 event) would cause the Printer to send an Event Notification for 1950 either the 'job-completed' or 'job-state-changed' Subscribed Events 1951 and to send the 'job-completed' or 'job-state-changed' value for this 1952 attribute, respectively,. See section 5.3.3.2 for the "matching" 1953 rules of Subscribed Events and for additional examples. 1955 The Delivery Method Document specifies whether the Printer includes 1956 the value of this attribute in an Event Notification. 1958 8.2 notify-text (text(MAX)) 1960 This attribute contains a Human Consumable text message (see section 1961 9.2). This message describes the Event and is encoded as plain text, 1962 i.e., 'text/plain' with the charset specified by Subscription 1963 Object's "notify-charset" attribute. 1965 The Delivery Method Document specifies whether the Printer includes 1966 this attribute in an Event Notification. 1968 9 Event Notification Content 1970 This section defines the Event Notification content that the Printer 1971 sends when an Event occurs. 1973 When an Event occurs, the Printer MUST find each Subscription object 1974 whose "notify-events" attribute "matches" the Event. See section 1975 5.3.3.2 for details on "matching". For each matched Subscription 1976 Object, the Printer MUST create an Event Notification with the 1977 content and format that the Delivery Method Document specifies. The 1978 content contains the value of attributes specified by the Delivery 1979 Method Document. The Printer obtains the values immediately after 1980 the Event occurs. For example, if the "printer-state" attribute 1981 changes from 'idle' to 'processing', the Event 'printer-state- 1982 changed' occurs and the Printer puts various attributes into the 1983 Event Notification, including "printer-up-time" and "printer-state" 1984 with the values that they have immediately after the Event occurs, 1985 i.e., the value of "printer-state" is 'processing'. 1987 Event Notification Ordering: 1989 When a Printer sends Event Notifications, the Event Notifications 1990 from any given Subscription Object MUST be in time stamp order, i.e., 1991 in order of increasing "printer-up-time" attribute value in the Event 1992 Notification (see Table 5). These Event Notifications MAY be 1993 interleaved with those from other Subscription Objects, as long as 1994 those others are also in time stamp order. The Printer MUST observe 1995 these ordering requirements whether sending multiple pending Events 1996 as multiple separate Event Notifications or together in a single 1997 Compound Event Notification. 1999 If a Subscribing Client wants the Printer to send certain Event 2000 Notifications in time stamp order, the Subscribing Client uses a 2001 single Subscription Object. Even so, depending on the underlying 2002 transport, the actual order that a Notification Recipient receives 2003 separate Event Notifications may differ from the order sent by the 2004 Printer (e.g., email). 2006 Example: Consider two Per-Printer Subscription Objects: SO1 and SO2. 2007 SO1 requests 'job-state-changed' events and SO2 requests 'printer- 2008 state-changed' events. The number in parens is the time stamp. The 2009 following Event Notification sequences are the only ones that conform 2010 to the ordering requirements for the Printer to send the Event 2011 Notifications: 2013 (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 'job- 2014 completed' (1009), SO2: 'printer-stopped' (1005) 2016 (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2: 2017 'printer-stopped' (1005), SO1: 'job-completed' (1009) 2019 (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1: 2020 'job-stopped' (1005), SO1: 'job-completed' (1009) 2022 (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1: 2023 'job-stopped' (1005), SO1: 'job-completed' (1009) 2025 Examples (b) and (c) are interleaved; examples (a) and (d) are not 2026 interleaved and are not appropriate for some Delivery Methods. 2028 If two different Events occur simultaneously, or nearly so (e.g., 2029 "printer-up-time" has the same value for both), the Printer MUST 2030 create a separate Event Notification for each Event, even if the 2031 associated Subscription Object is the same for both Events. However, 2032 the Printer MAY combine these distinct Event Notifications into a 2033 single Compound Event Notification if the Delivery Method supports 2034 Compound Event Notifications. For example, suppose that two nearly- 2035 simultaneously Events represent two successive 'printer-state- 2036 changed' Events, one from 'idle' to 'processing' and another from 2037 'processing' to 'stopped'. These two Events have the same name but 2038 are different instances of the Event. Then the Printer MUST create a 2039 separate Event Notification for each Event and SHOULD accurately 2040 report the "printer-state" of the first Event as 'processing' and the 2041 second Event as 'stopped'. 2043 If a Subscription Object contains more than one Subscribed Event, and 2044 several Events occur in quick succession each matching a different 2045 Subscribed Event in the Subscription Object, the Printer MUST NOT 2046 generate a single Event Notification from several of these Events, 2047 but MAY combine distinct Event Notifications into a single Compound 2048 Event Notification if the Delivery Method supports Compound Event 2049 Notifications. 2051 After the Printer has created the Event Notification, the Printer 2052 delivers it via either a: 2054 Push Delivery Method: The Printer sends the Event Notification 2055 shortly after an Event occurs. For some Push Delivery Methods, 2056 the Notification Recipient MUST send a response; for others it 2057 MUST NOT send a response. 2059 Pull Delivery Method: The Printer saves Event Notifications for 2060 some Event Life and expects the Notification Recipient to 2061 request Event Notifications. The Printer returns the Event 2062 Notifications in a response to such a request. 2064 If an error that meets the following conditions occurs, the Printer 2065 MUST cancel the Subscription Object. 2067 a)the error occurs during the sending of an Event Notification 2068 generated from Subscription Object S AND 2070 b)the error would continue to occur every time the Printer sends an 2071 Event Notification generated from Subscription Object S in the 2072 future. 2074 For example, if the address of the "notify-recipient-uri" of 2075 Subscription Object A references a non-existent target and the 2076 Printer determines this fact, it MUST delete Subscription Object A. 2078 The next two sections describe the values that a Printer sends in the 2079 content of Machine Consumable and Human Consumable Event 2080 Notifications, respectively. 2082 The tables in the sub-sections of this section contain the following 2083 columns: 2085 a)Source Value: the name of the attribute that supplies the value 2086 for the Event Notification. Asterisks in this field refer to a 2087 note below the table. 2089 b)Sends: if the Printer supports the value (column 1) on the 2090 Source Object (column 3) the Delivery Method MUST specify: 2092 MUST: that the Printer MUST send the value. 2094 SHOULD: either that the Printer MUST send the value or that 2095 the value is incompatible with the Delivery Method. 2097 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 2098 or NEED NOT send the value. The Delivery Method specifies the 2099 level of conformance for the Printer. 2101 c)Source Object: the object from which the source value comes. If 2102 the object is "Event Notification", the Printer fabricates the 2103 value when it sends the Event Notification. See section 8. 2105 9.1 Content of Machine Consumable Event Notifications 2107 This section defines the attributes that a Delivery Method MUST 2108 mention in a Delivery Method Document when specifying the Machine 2109 Consumable Event Notification's contents. 2111 This document does not define the order of attributes in Event 2112 Notifications. However, Delivery Method Documents MAY define the 2113 order of some or all of the attributes. 2115 A Delivery Method Document MUST specify additional attributes (if 2116 any) that a Printer implementation sends in a Machine Consumable 2117 Event Notification. 2119 Notification Recipients MUST be able to accept Event Notifications 2120 containing attributes they do not recognize. What a Notification 2121 Recipient does with an unrecognized attribute is implementation- 2122 dependent. Notification Recipients MAY attempt to display 2123 unrecognized attributes anyway or MAY ignore them. 2125 The next three sections define the attributes in Event Notification 2126 Contents that are: 2128 1.for all Events 2129 2.for Job Events only 2131 3.for Printer Events only 2133 9.1.1 Event Notification Content Common to All Events 2135 This section lists the attributes that a Delivery Method Document 2136 MUST specify for all Events. 2138 Table 5 lists potential values in each Event Notification. 2140 Table 5 - Attributes in Event Notification Content 2142 Source Value Sends Source Object 2144 notify-subscription-id (integer(1:MAX)) MUST Subscription 2146 notify-printer-uri (uri) MUST Subscription 2148 notify-subscribed-event (type2 keyword) MUST Event 2149 Notification 2151 printer-up-time (integer(MIN:MAX)) MUST Printer 2153 printer-current-time (dateTime) * MUST Printer 2155 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 2157 notify-charset (charset) SHOULD Subscription 2159 notify-natural-language (naturalLanguage) SHOULD Subscription 2161 notify-user-data (octetString(63)) ** SHOULD Subscription 2163 notify-text (text) SHOULD Event 2164 Notification 2166 attributes from the "notify-attributes" MAY Printer 2167 attribute *** 2169 attributes from the "notify-attributes" MAY Job 2170 attribute *** 2172 attributes from the "notify-attributes" MAY Subscription 2173 attribute *** 2175 *A Printer MUST send this value only if and only if it supports the 2176 Printer's "printer-current-time" attribute. 2178 ** If the Subscription Object does not contain a "notify-user-data" 2179 attribute and the Delivery Method Document REQUIRES the Printer to 2180 send the "notify-user-data" source value in the Event Notification, 2181 the Printer MUST send an octet-string of length 0. 2183 *** The last three rows represent additional attributes that a client 2184 MAY request via the "notify-attributes" attribute. A Printer MAY 2185 support the "notify-attributes" attribute. The Delivery Method MUST 2186 say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED 2187 NOT support the "notify-attributes" attribute and specific values of 2188 this attribute. The Delivery Method MAY say that support for the 2189 "notify-attributes" is conditioned on support of the attribute by the 2190 Printer or it MAY say that Printer MUST support the "notify- 2191 attributes" attribute if the Printer supports the Delivery Method. 2193 9.1.2 Additional Event Notification Content for Job Events 2195 This section lists the additional attributes that a Delivery Method 2196 Document MUST specify for Job Events. See Table 6. 2198 Table 6 - Additional Event Notification Content for Job Events 2200 Source Value Sends Source Object 2202 job-id (integer(1:MAX)) MUST Job 2204 job-state (type1 enum) MUST Job 2206 job-state-reasons (1setOf type2 keyword) MUST Job 2208 job-impressions-completed (integer(0:MAX)) * MUST Job 2210 * The Printer MUST send the "job-impressions-completed" attribute in 2211 an Event Notification only for the combinations of Events and 2212 Subscribed Events shown in Table 7. 2214 Table 7 - Combinations of Events and Subscribed Events for "job- 2215 impressions-completed" 2217 Job Event Subscribed Job Event 2219 'job-progress' 'job-progress' 2221 'job-completed' 'job-completed' 2223 'job-completed' 'job-state-changed' 2225 9.1.3 Additional Event Notification Content for Printer Events 2227 This section lists the additional attributes that a Delivery Method 2228 Document MUST specify for Printer Events. See Table 8. 2230 Table 8 - Additional Event Notification Content for Printer Events 2232 Source Value Sends Source Object 2234 printer-state (type1 enum) MUST Printer 2236 printer-state-reasons (1setOf type2 keyword) MUST Printer 2238 printer-is-accepting-jobs (boolean) MUST Printer 2240 9.2 Content of Human Consumable Event Notification 2242 This section defines the information that a Delivery Method MUST 2243 mention in a Delivery Method Document when specifying the Human 2244 Consumable Event Notifications contents or the value of the "notify- 2245 text" attribute. 2247 Such a Delivery Method MUST specify the following information and a 2248 Printer SHOULD send it: 2250 a)the Printer name (see Table 9) 2252 b)the time of the Event (see Table 11) 2253 c)for Printer Events only: 2254 i) the Event (see Table 10) and/or Printer state information 2255 (see Table 14) 2256 d)for Job Events only: 2257 i) the job identity (see Table 12) 2258 ii) the Event (see Table 10) and/or Job state information (see 2259 Table 13) 2261 The subsections of this section specify the attributes that a Printer 2262 MUST use to obtain this information. 2264 A Delivery Method Document MUST specify additional information (if 2265 any) that a Printer implementation sends in a Human Consumable Event 2266 Notification or in the "notify-text" attribute. 2268 A client MUST NOT request additional attributes via the "notify- 2269 attributes" attribute because this attribute works only for Machine 2270 Consumable Event Notifications. 2272 Notification Recipients MUST NOT expect to be able to parse the Human 2273 Consumable Event Notification contents or the value of the "notify- 2274 text" attribute. 2276 The next three sections define the attributes in Event Notification 2277 Contents that are: 2279 a) for all Events 2280 b) for Job Events only 2281 c) for Printer Events only 2283 9.2.1 Event Notification Content Common to All Events 2285 This section lists the source of the information that a Delivery 2286 Method MUST specify for all Events. 2288 There is a separate table for each piece of information. Each row in 2289 the table represents a source value for the information and the 2290 values are listed in order of preference, with the first one being 2291 the preferred one. An implementation SHOULD use the source value 2292 from the earliest row in each table. It MAY use the source value 2293 from another row instead, or it MAY combine the source values from 2294 several rows. An implementation is free to determine the best way to 2295 present this information. 2297 In all tables of this section, all rows contain a "MAY" in order to 2298 state that the Delivery Method specifies the conformance. 2300 Table 9 lists the source of the information for the Printer Name. 2301 The "printer-name" is more user-friendly unless the Notification 2302 Recipient is in a place where the Printer name is not meaningful. 2303 For example, an implementation could have the intelligence to send 2304 the value of the "printer-name" attribute to a Notification Recipient 2305 that can access the Printer via value of the "printer-name" attribute 2306 and otherwise send the value of the "notify-printer-uri" attribute. 2308 Table 9 - Printer Name in Event Notification Content 2310 Source Value Sends Source Object 2312 printer-name (name(127)) MAY Printer 2314 notify-printer-uri (uri) MAY Subscription 2316 Table 10 lists the source of the information for the Event name. A 2317 Printer MAY combine this information with state information described 2318 for Jobs in Table 13 or for Printers in Table 14. 2320 Table 10 - Event Name in Event Notification Content 2322 Source Value Sends Source Object 2324 notify-subscribed-event (type2 keyword) MAY Subscription 2326 Table 11 lists the source of the information for the time that the 2327 Event occurred. A Printer can send this value only if it supports 2328 the Printer's "printer-current-time" attribute. If a Printer does 2329 not support the "printer-current-time" attribute, it MUST NOT send 2330 the "printer-up-time" value instead, since it is not an allowed 2331 option for human consumable information. 2333 Table 11 - Event Time in Event Notification Content 2335 Source Value Sends Source Object 2337 printer-current-time (dateTime) MAY Printer 2339 9.2.2 Additional Event Notification Content for Job Events 2341 This section lists the source of the additional information that a 2342 Delivery Method MUST specify for Job Events. 2344 Table 12 lists the source of the information for the job name. The 2345 "job-name" is likely more meaningful to a user than "job-id". 2347 Table 12 - Job Name in Event Notification Content 2349 Source Value Sends Source Object 2351 job-name (name(MAX)) MAY Job 2353 job-id (integer(1:MAX)) MAY Job 2355 Table 13 lists the source of the information for the job state. If a 2356 Printer supports the "job-state-message" and "job-detailed-state- 2357 message" attributes, it SHOULD use those attributes for the job state 2358 information, otherwise, it should fabricate such information from the 2359 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2360 combine this information with Event information. 2362 Table 13 - Job State in Event Notification Content 2364 Source Value Sends Source 2365 Object 2367 job-state-message (text(MAX)) MAY Job 2369 job-detailed-status-messages (1setOf text(MAX)) MAY Job 2371 job-state (type1 enum) MAY Job 2373 job-state-reasons (1setOf type2 keyword) MAY Job 2375 9.2.3 Additional Event Notification Content for Printer Events 2377 This section lists the source of the additional information that a 2378 Delivery Method MUST specify for Printer Events. 2380 Table 14 lists the source of the information for the printer state. 2381 If a Printer supports the "printer-state-message", it SHOULD use that 2382 attribute for the job state information, otherwise it SHOULD 2383 fabricate such information from the "printer-state" and "printer- 2384 state-reasons". For some Events, a Printer MAY combine this 2385 information with Event information. 2387 Table 14 - Printer State in Event Notification Content 2389 Source Value Sends Source 2390 Object 2392 printer-state-message (text(MAX)) MAY Printer 2394 printer-state (type1 enum) MAY Printer 2396 printer-state-reasons (1setOf type2 keyword) MAY Printer 2398 printer-is-accepting-jobs (boolean) MAY Printer 2400 10 Delivery Methods 2402 A Delivery Method is the mechanism, i.e., protocol, by which the 2403 Printer delivers an Event Notification to a Notification Recipient. 2404 There are several potential Delivery Methods for Event Notifications, 2405 standardized, as well as proprietary. This specification REQUIRES 2406 that the 'ippget' Pull Delivery Method [ipp-get-method] be supported. 2407 Conforming implementations MAY support additional Push or Pull 2408 Delivery Methods as well. This document does not define any of these 2409 delivery mechanisms. Each Delivery Method MUST be defined in a 2410 Delivery Method Document that is separate from this document. New 2411 Delivery Methods will be created as needed using an extension to the 2412 registration procedures defined in [RFC2911]. Such documents are 2413 registered with IANA (see section 19.7.3). 2415 The following sorts of Delivery Methods are possible: 2417 - The Notification Recipient polls for Event Notifications at 2418 intervals directed by the Printer 2419 - The Printer sends Event Notifications to the Notification 2420 Recipient using http as the transport. 2422 - The Printer sends an email message. 2424 This section specifies how to define a Delivery Method Document and 2425 what to put in such a document. 2427 A Delivery Method Document MUST contain an exact copy of the 2428 following paragraph, caption and table. In addition, column 2 of the 2429 table in the Delivery Method Document MUST contain answers to 2430 questions in column 1 for the Delivery Method. Also, the Delivery 2431 Method document MUST contain a reference to this document and call 2432 that reference [ipp-ntfy] because the table contains an [ipp-ntfy] 2433 reference. 2435 If a Printer supports this Delivery Method, the following are its 2436 characteristics. 2438 Table 15 - Information about the Delivery Method 2440 Document Method Conformance Requirement Delivery Method 2441 Realization 2443 1.What is the URL scheme name for the Push 2444 Delivery Method or the keyword method 2445 name for the Pull Delivery Method? 2447 2.Is the Delivery Method REQUIRED, 2448 RECOMMENDED, or OPTIONAL for an IPP 2449 Printer to support? 2451 3.What transport and delivery protocols 2452 does the Printer use to deliver the 2453 Event Notification Content, i.e., what 2454 is the entire network stack? 2456 4.Can several Event Notifications be 2457 combined into a Compound Event 2458 Notification? 2460 5.Is the Delivery Method initiated by the 2461 Notification Recipient (pull), or by the 2462 Printer (push)? 2464 6.Is the Event Notification content 2465 Machine Consumable or Human Consumable? 2467 7.What section in this document answers 2468 the following question? For a Machine 2469 Consumable Event Notification, what is 2470 the representation and encoding of 2471 values defined in section 9.1 of [ipp- 2472 ntfy] and the conformance requirements 2473 thereof? For a Human Consumable Event 2474 Notification, what is the representation 2475 and encoding of pieces of information 2476 defined in section 9.2 of [ipp-ntfy] and 2477 the conformance requirements thereof? 2479 8.What are the latency and reliability of 2480 the transport and delivery protocol? 2482 9.What are the security aspects of the 2483 transport and delivery protocol, e.g., 2484 how it is handled in firewalls? 2486 10. What are the content length 2487 restrictions? 2489 11. What are the additional values or 2490 pieces of information that a Printer 2491 sends in an Event Notification content 2492 and the conformance requirements 2493 thereof? 2495 12. What are the additional Subscription 2496 Template and/or Subscription Description 2497 attributes and the conformance 2498 requirements thereof? 2500 13. What are the additional Printer 2501 Description attributes and the 2502 conformance requirements thereof? 2504 11 Operations for Notification 2506 This section defines all of the operations for Notification. Section 2507 7.1 assigns the "operation-id" for each operation. The following two 2508 sub-sections define Subscription Creation Operations, and other 2509 operations. 2511 11.1 Subscription Creation Operations 2513 This section defines the Subscription Creation Operations. The first 2514 section on Create-Job-Subscriptions gives most of the information. 2515 The other Subscription Creation Operations refer to the section on 2516 Create-Job-Subscriptions, even though the Create-Job-Subscriptions 2517 operation is the only OPTIONAL operation in this document (see 2518 section 12). 2520 A Printer MUST support Create-Printer-Subscriptions and the 2521 Subscription Template Attributes Group in Job Creation operations. 2522 It MAY support Create-Job-Subscriptions operations. 2524 11.1.1 Create-Job-Subscriptions Operation 2526 The operation creates one or more Per-Job Subscription Objects. The 2527 client supplies one or more Subscription Template Attributes Groups 2528 each containing one or more of Subscription Template Attributes 2529 (defined in section 5.3). 2531 Except for errors, the Printer MUST create exactly one Per-Job 2532 Subscription Object from each Subscription Template Attributes Group 2533 in the request, even if the newly created Subscription Object would 2534 have identical behavior to some existing Subscription Object. The 2535 Printer MUST associate each newly created Per-Job Subscription Object 2536 with the target Job, which is specified by the "notify-job-id" 2537 operation attribute. 2539 The Printer MUST accept the request in any of the target job's 'not- 2540 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2541 'processing-stopped'. The Printer MUST NOT change the job's "job- 2542 state" attribute because of this operation. If the target job is in 2543 any of the 'completed' states, i.e., 'completed', 'canceled', or 2544 'aborted, then the Printer MUST reject the request and return the 2545 'client-error-not-possible' status code; the response MUST NOT 2546 contain any Subscription Attribute Groups. 2548 Access Rights: To create Per-Job Subscription Objects, the 2549 authenticated user (see [RFC2911] section 8.3) performing this 2550 operation MUST (1) be the job owner, (2) have Operator or 2551 Administrator access rights for this Printer (see [RFC2911] sections 2552 1 and 8.5), or (3) be otherwise authorized by the Printer's 2553 administrator-configured security policy to create Per-Job 2554 Subscription Objects for the target job. Otherwise the Printer MUST 2555 reject the operation and return: the 'client-error-forbidden', 2556 'client-error-not-authenticated', or 'client-error-not-authorized' 2557 status code as appropriate. 2559 11.1.1.1 Create-Job-Subscriptions Request 2561 The following groups of attributes are part of the Create-Job- 2562 Subscriptions Request: 2564 Group 1: Operation Attributes 2566 Natural Language and Character Set: 2567 The "attributes-charset" and "attributes-natural-language" 2568 attributes as described in [RFC2911] section 3.1.4.1. 2570 Target: 2571 The "printer-uri" attribute which defines the target for this 2572 operation as described in [RFC2911] section 3.1.5. 2574 Requesting User Name: 2575 The "requesting-user-name" attribute SHOULD be supplied by the 2576 client as described in [RFC2911] section 8.3. 2578 11.1.1.1.1 notify-job-id (integer(1:MAX)) 2580 The client MUST supply this attribute and it MUST specify the 2581 Job object to associate the Per-Job Subscription with. The 2582 value of "notify-job-id" MUST be the value of the "job-id" of 2583 the associated Job object. If the client does not supply this 2584 attribute, the Printer MUST reject this request with a 'client- 2585 error-bad-request' status code. 2587 Group 2-N: Subscription Template Attributes 2589 For each occurrence of this group: 2591 The client MUST supply one or more Subscription Template 2592 Attributes in any order. See section 5.3 for a description of 2593 each such attribute. See section 5.2 for details on 2594 processing these attributes. 2596 11.1.1.2 Create-Job-Subscriptions Response 2598 The Printer MUST return to the client the following sets of 2599 attributes as part of a Create-Job-Subscriptions response: 2601 Group 1: Operation Attributes 2603 Status Message: 2604 In addition to the REQUIRED status code returned in every 2605 response, the response OPTIONALLY includes a "status-message" 2606 (text(255)) and/or a "detailed-status-message" (text(MAX)) 2607 operation attribute as described in [RFC2911] sections 13 and 2608 3.1.6. 2610 In this group, the Printer can return any status codes defined 2611 in [RFC2911] and section 12. The following is a description of 2612 the important status codes: 2614 successful-ok: the Printer created all Subscription Objects 2615 requested (see [RFC2911]). 2616 successful-ok-ignored-subscriptions: the Printer created 2617 some Subscription Objects requested but some failed. The 2618 Subscription Attributes Groups with a "notify-status- 2619 code" attribute are the ones that failed (see section 2620 12.1). 2621 client-error-ignored-all-subscriptions: the Printer created 2622 no Subscription Objects requested and all failed. The 2623 Subscription Attributes Groups with a "notify-status- 2624 code" attribute are the ones that failed (see section 2625 12.2). 2626 client-error-not-possible: For this operation and other 2627 Per-Job Subscription operations, this error can occur 2628 because the specified Job has already completed (see 2629 [RFC2911], whether or not the Job is retained in the Job 2630 Retention and/or Job History phases (see [RFC2911] 2631 section 4.3.7.1). 2633 Natural Language and Character Set: 2634 The "attributes-charset" and "attributes-natural-language" 2635 attributes as described in [RFC2911] section 3.1.4.2. 2637 Group 2: Unsupported Attributes 2639 See [RFC2911] section 3.1.7 for details on returning 2640 Unsupported Attributes. This group does not contain any 2641 unsupported Subscription Template Attributes; they are returned 2642 in the Subscription Attributes Group (see below). 2644 Group 3-N: Subscription Attributes 2646 These groups MUST be returned unless the Printer is unable to 2647 interpret the entire request, e.g., the "status-code" parameter 2648 returned in Group 1 has the value: 'client-error-bad-request'. 2650 "notify-status-code" (type2 enum): 2651 Indicates the status of this subscription (see section 13 2652 for the status code definitions). Section 5.2 defines when 2653 this attribute MUST be present in this group. 2655 See section 5.2 for details on the contents of each occurrence 2656 of this group. 2658 11.1.2 Create-Printer-Subscriptions operation 2660 The operation is identical to Create-Job-Subscriptions with 2661 exceptions noted in this section. 2663 The operation creates Per-Printer Subscription Objects instead of 2664 Per-Job Subscription Objects, and associates each newly created Per- 2665 Printer Subscription Object with the Printer specified by the 2666 operation target rather than with a specific Job. 2668 The Printer MUST accept the request in any of its states, i.e., 2669 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its 2670 "printer-state" attribute because of this operation. 2672 Access Rights: To create Per-Printer Subscription Objects, the 2673 authenticated user (see [RFC2911] section 8.3) performing this 2674 operation MUST have (1) Operator or Administrator access rights for 2675 this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise 2676 authorized by the Printer's administrator-configured security policy 2677 to create Per-Printer Subscription Objects for this Printer. 2678 Otherwise, the Printer MUST reject the operation and return: the 2679 'client-error-forbidden', 'client-error-not-authenticated', or 2680 'client-error-not-authorized' status code as appropriate. 2682 11.1.2.1 Create-Printer-Subscriptions Request 2684 The groups are identical to the Create-Job-Subscriptions (see section 2685 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2686 the "notify-job-id" attribute. If the client does supply the 2687 "notify-job-id" attribute, then the Printer MUST treat it as any 2688 other unsupported Operation attribute and MUST return it in the 2689 Unsupported Attributes group. 2691 11.1.2.2 Create-Printer-Subscriptions Response 2693 The groups are identical to the Create-Job-Subscriptions (see section 2694 11.1.1.2). 2696 11.1.3 Job Creation Operations - Extensions for Notification 2698 This document extends the Job Creation operations (see section 3.2) 2699 to create Subscription Objects as a part of the operation. 2701 The Job Creation operations are identical to Create-Job-Subscriptions 2702 operation with exceptions noted in this section. 2704 Unlike the Create-Job-Subscriptions operation, a Job Creation 2705 operation associates the newly created Subscription Objects with the 2706 Job object created by this operation. The operation succeeds if and 2707 only if the Job creation succeeds. If the Printer does not create 2708 some or all of the requested Subscription Objects, the Printer MUST 2709 return a 'successful-ok-ignored-subscriptions' status-code instead 2710 of a 'successful-ok' status-code, but the Printer MUST NOT reject the 2711 operation because of a failure to create Subscription Objects. 2713 If the Job Creation operation includes a Job Template group, the 2714 client MUST supply it after the Operation Attributes group and before 2715 the first Subscription Template Attributes Group. 2717 If a Printer does not support this Notification specification, then 2718 it MUST treat the Subscription Attributes Group like an unknown group 2719 and ignore it (see [RFC2911] section 5.2.2). Because the Printer 2720 ignores the Subscription Attributes Group, it doesn't return them in 2721 the response either, thus indicating to the client that the Printer 2722 doesn't support Notification. 2724 After completion of a successful Job Creation operation, the Printer 2725 generates a 'job-created' event (see section 5.3.3.1.3). 2727 Access Rights: To create Per-Job Subscription Objects, the 2728 authenticated user (see [RFC2911] section 8.3) performing this 2729 operation MUST either have permission to create Jobs on the Printer 2730 or have Operator or Administrator access rights for this Printer (see 2731 [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the 2732 operation and return: the 'client-error-forbidden', 'client-error- 2733 not-authenticated', or 'client-error-not-authorized' status code as 2734 appropriate. 2736 11.1.3.1 Job Creation Request 2738 The groups for this operation are sufficiently different from the 2739 Create-Job-Subscriptions operation that they are all presented here. 2740 The following groups of attributes are supplied as part of a Job 2741 Creation Request: 2743 Group 1: Operation Attributes 2745 Same as defined in [RFC2911] for Print-Job, Print-URI, and 2746 Create-Job requests. 2748 Group 2: Job Template Attributes 2749 The client OPTIONALLY supplies a set of Job Template attributes 2750 as defined in [RFC2911] section 4.2. 2752 Group 3 to N: Subscription Template Attributes 2754 The same as Group 2-N in Create-Job-Subscriptions. See section 2755 11.1.1.1. 2756 Group N+1: Document Content (Print-Job only) 2758 The client MUST supply the document data to be processed. 2760 11.1.3.2 Job Creation Response 2762 The Printer MUST return to the client the following sets of 2763 attributes as part of a Print-Job, Print-URI, and Create-Job 2764 Response: 2766 Group 1: Operation Attributes 2768 Status Message: 2770 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2771 Job requests. 2773 In this group, the Printer can return any status codes defined 2774 in [RFC2911] and section 12. The following is a description of 2775 the important status codes: 2777 successful-ok: the Printer created the Job and all 2778 Subscription Objects requested (see [RFC2911]. 2779 successful-ok-ignored-subscriptions: the Printer created 2780 the Job and not all of the Subscription Objects requested 2781 (see section 12.1). This status-code hides 'successful- 2782 ok-xxx' status-codes that could reveal problems in Job 2783 creation. The Printer MUST NOT return the 'client-error- 2784 ignored-all-subscriptions' status code for Job Creation 2785 operations because the Printer returns an error status- 2786 code only when it fails to create a Job. 2788 Natural Language and Character Set: 2789 The "attributes-charset" and "attributes-natural-language" 2790 attributes as described in [RFC2911] section 3.1.4.2. 2792 Group 2: Unsupported Attributes 2794 See [RFC2911] section 3.1.7 for details on returning 2795 Unsupported Attributes. This group does not contain any 2796 unsupported Subscription Template Attributes; they are returned 2797 in the Subscription Attributes Group (see below). 2799 Group 3: Job Object Attributes 2801 The "job-id" of the Job Object just created, etc., as defined 2802 in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. 2804 Group 4 to N: Subscription Attributes 2806 These groups MUST be returned if and only if the client 2807 supplied Subscription Template Attributes and the operation was 2808 accepted. 2809 See section 5.2 for details on the contents of each occurrence 2810 of this group. 2812 11.2 Other Operations 2814 This section defines other operations on Subscription objects. 2816 11.2.1 Restart-Job Operation - Extensions for Notification 2818 The Restart-Job operation [RFC2911] is neither a Job Creation 2819 operation nor a Subscription Creation operation (see section 3.2). 2820 For the Restart-Job operation, the client MUST NOT supply any Job 2821 Subscription Attributes Groups. The Printer MUST treat any supplied 2822 Job Subscription Attributes as unsupported attributes. 2824 For this operation, the Printer does not return a job-id or any 2825 Subscription Attributes groups because the Printer reuses the 2826 existing Job object with the same job-id and the existing Per-Job 2827 Subscription Objects with the same subscription-ids. However, after 2828 successful completion of this operation, the Printer generates a 2829 'job-created' event (see section 5.3.3.1.3). 2831 11.2.2 Validate-Job Operation - Extensions for Notification 2833 A client can test whether one or more Subscription Objects could be 2834 created using the Validate-Job operation. The client supplies one or 2835 more Subscription Template Attributes Groups (defined in section 2836 5.3), just as in a Job Creation request. 2838 A Printer MUST support this extension to this operation. 2840 The Printer MUST accept requests that are identical to the Job 2841 Creation request defined in section 11.1.3.1, except that the request 2842 MUST NOT contain document data. 2844 The Printer MUST return the same groups and attributes as the Print- 2845 Job operation (section 11.1.3.1) with the following exceptions. The 2846 Printer MUST NOT return a Job Object Attributes Group because no Job 2847 is created. The Printer MUST NOT return the "notify-subscription-id" 2848 attribute in any Subscription Attribute Group because no Subscription 2849 Object is created. 2851 If the Printer would succeed in creating a Subscription Object, the 2852 corresponding Subscription Attributes Group either has no 'status- 2853 code' attribute or a 'status-code' attribute with a value of 2854 'successful-ok-too-many-events' or 'successful-ok-ignored-or- 2855 substituted-attributes' (see sections 5.2 and 13). The status-codes 2856 have the same meaning as in Job Creation except the results state 2857 what "would happen". 2859 The Printer MUST validate Subscription Template Attributes Groups in 2860 the same manner as the Job Creation operations. 2862 11.2.3 Get-Printer-Attributes - Extensions for Notification 2864 This operation is extended so that it returns Printer attributes 2865 defined in this document. 2867 A Printer MUST support this extension to this operation. 2869 In addition to the requirements of [RFC2911] section 3.2.5, a Printer 2870 MUST support the following additional values for the "requested- 2871 attributes" Operation attribute in this operation and return such 2872 attributes in the Printer Object Attributes group of its response. 2874 1.Subscription Template Attributes: Each supported attribute in 2875 column 2 of Table 1. 2877 2.New Printer Description Attributes: Each supported attribute in 2878 section 6. 2880 3.New Group Name: The 'subscription-template' group name, which 2881 names all supported Subscription Template Attribute in column 2 2882 of Table 1. This group name is also used in the Get- 2883 Subscription-Attributes and Get-Subscriptions operation with an 2884 analogous meaning. 2886 4.Extended Group Name: The 'all' group name, which names all 2887 Printer attributes according to [RFC2911] section 3.2.5. In 2888 this extension 'all' names all attributes specified in [RFC2911] 2889 plus those named in items 1 and 2 of this list. 2891 11.2.4 Get-Subscription-Attributes operation 2893 This operation allows a client to request the values of the 2894 attributes of a Subscription Object. 2896 A Printer MUST support this operation. 2898 This operation is almost identical to the Get-Job-Attributes 2899 operation (see [RFC2911] section 3.3.4). The only differences are 2900 that the operation is directed at a Subscription Object rather than a 2901 Job object, and the returned attribute group contains Subscription 2902 Object attributes rather than Job object attributes. 2904 Access Rights: The authenticated user (see [RFC2911] section 8.3) 2905 performing this operation MUST (1) be the Subscription Object owner, 2906 (2) have Operator or Administrator access rights for this Printer 2907 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by 2908 the Printer's administrator-configured security policy to query the 2909 Subscription Object for the target job. Otherwise the Printer MUST 2910 reject the operation and return: the 'client-error-forbidden', 2911 'client-error-not-authenticated', or 'client-error-not-authorized' 2912 status code as appropriate. Furthermore, the Printer's security 2913 policy MAY limit which attributes are returned, in a manner similar 2914 to the Get-Job-Attributes operation (see [RFC2911] end of section 2915 3.3.4.2). 2917 11.2.4.1 Get-Subscription-Attributes Request 2919 The following groups of attributes are part of the Get-Subscription- 2920 Attributes request: 2922 Group 1: Operation Attributes 2924 Natural Language and Character Set: 2925 The "attributes-charset" and "attributes-natural-language" 2926 attributes as described in section [RFC2911] 3.1.4.1. 2928 Target: 2929 The "printer-uri" attribute which defines the target for this 2930 operation as described in [RFC2911] section 3.1.5. 2932 Requesting User Name: 2933 The "requesting-user-name" attribute SHOULD be supplied by the 2934 client as described in [RFC2911] section 8.3. 2936 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)) 2938 The client MUST supply this attribute. The Printer MUST 2939 support this attribute. This attribute specifies the 2940 Subscription Object from which the client is requesting 2941 attributes. If the client omits this attribute, the Printer 2942 MUST reject this request with the 'client-error-bad-request' 2943 status code. 2945 11.2.4.1.2 "requested-attributes" (1setOf keyword) 2947 The client OPTIONALLY supplies this attribute. The Printer 2948 MUST support this attribute. This attribute specifies the 2949 attributes of the specified Subscription Object that the 2950 Printer MUST return in the response. Each value of this 2951 attribute is either an attribute name (defined in sections 5.3 2952 and 5.4) or an attribute group name. The attribute group names 2953 are: 2955 - 'subscription-template': all attributes that are both 2956 defined in section 5.3 and present on the specified 2957 Subscription Object (column 1 of Table 1). 2958 - 'subscription-description': all attributes that are both 2959 defined in section 5.4 and present on the specified 2960 Subscription Object (Table 2). 2961 - 'all': all attributes that are present on the specified 2962 Subscription Object. 2964 A Printer MUST support all these group names. 2966 If the client omits this attribute, the Printer MUST respond as 2967 if this attribute had been supplied with a value of 'all'. 2969 11.2.4.2 Get-Subscription-Attributes Response 2971 The Printer returns the following sets of attributes as part of the 2972 Get-Subscription-Attributes Response: 2974 Group 1: Operation Attributes 2976 Status Message: 2977 Same as [RFC2911]. 2979 Natural Language and Character Set: 2980 The "attributes-charset" and "attributes-natural-language" 2981 attributes as described in [RFC2911] section 3.1.4.2. The 2982 "attributes-natural-language" MAY be the natural language of 2983 the Subscription Object, rather than the one requested. 2985 Group 2: Unsupported Attributes 2987 See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on 2988 returning Unsupported Attributes. 2990 The response NEED NOT contain the "requested-attributes" 2991 operation attribute with any supplied keyword values that were 2992 requested by the client but are not supported by the IPP 2993 object. If the Printer object does return unsupported 2994 attributes referenced in the "requested-attributes" operation 2995 attribute, the values of the "requested-attributes" attribute 2996 returned MUST include only the unsupported keywords that were 2997 requested by the client. If the client had requested a group 2998 name, such as 'all', the resulting unsupported attributes 2999 returned MUST NOT include attribute keyword names described in 3000 the standard but not supported by the implementation. 3002 Group 3: Subscription Attributes 3004 This group contains a set of attributes with their current 3005 values. Each attribute returned in this group: 3007 a)MUST be specified by the "requested-attributes" attribute 3008 in the request, AND 3010 b)MUST be present on the specified Subscription Object AND 3012 c)MUST NOT be restricted by the security policy in force. 3013 For example, a Printer MAY prohibit a client who is not the 3014 creator of a Subscription Object from seeing some or all of 3015 its attributes. See [RFC2911] end of section 3.3.4.2 and 3016 section 8. 3018 The Printer can return the attributes of the Subscription 3019 Object in any order. The client MUST accept the attributes in 3020 any order. 3022 11.2.5 Get-Subscriptions operation 3024 This operation allows a client to retrieve the values of attributes 3025 of all Subscription Objects belonging to a Job or Printer. 3027 A Printer MUST supported this operation. 3029 This operation is similar to the Get-Subscription-Attributes 3030 operation, except that this Get-Subscriptions operation returns 3031 attributes from possibly more than one object. 3033 This operation is similar to the Get-Jobs operation (see [RFC2911] 3034 section 3.2.6), except that the operation returns Subscription 3035 Objects rather than Job objects. 3037 Access Rights: To query Per-Job Subscription Objects of the 3038 specified job (client supplied the "notify-job-id" operation 3039 attribute - see section 11.2.5.1.1), the authenticated user (see 3040 [RFC2911] section 8.3) performing this operation MUST (1) be the 3041 Subscription Object owner, (2) have Operator or Administrator access 3042 rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3043 otherwise authorized by the Printer's administrator-configured 3044 security policy to query the Subscription Object for the target job. 3045 To query Per-Printer Subscription Objects of the Printer (client 3046 omits the "notify-job-id" operation attribute - see section 3047 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) 3048 performing this operation MUST (1) have Operator or Administrator 3049 access rights for this Printer (see [RFC2911] sections 1 and 8.5), or 3050 (2) be otherwise authorized by the Printer's administrator-configured 3051 security policy to query Per-Printer Subscription Objects for the 3052 target Printer. Otherwise the Printer MUST reject the operation and 3053 return: the 'client-error-forbidden', 'client-error-not- 3054 authenticated', or 'client-error-not-authorized' status code as 3055 appropriate. Furthermore, the Printer's security policy MAY limit 3056 which attributes are returned, in a manner similar to the Get-Jobs 3057 and Get-Printer-Attributes operations (see [RFC2911] end of sections 3058 3.2.6.2 and 3.2.5.2). 3060 11.2.5.1 Get-Subscriptions Request 3062 The following groups of attributes are part of the Get-Subscriptions 3063 request: 3065 Group 1: Operation Attributes 3067 Natural Language and Character Set: 3068 The "attributes-charset" and "attributes-natural-language" 3069 attributes as described in [RFC2911] section 3.1.4.1. 3071 Target: 3072 The "printer-uri" attribute which defines the target for this 3073 operation as described in [RFC2911] section 3.1.5. 3075 Requesting User Name: 3076 The "requesting-user-name" attribute SHOULD be supplied by the 3077 client as described in [RFC2911] section 8.3. 3079 11.2.5.1.1 "notify-job-id" (integer(1:MAX)) 3081 If the client specifies this attribute, the Printer returns the 3082 specified attributes of all Per-Job Subscription Objects 3083 associated with the Job whose "job-id" attribute value equals 3084 the value of this attribute. If the client does not specify 3085 this attribute, the Printer returns the specified attributes of 3086 all Per-Printer Subscription Objects. Note: there is no way to 3087 get all Per-Job Subscriptions known to the Printer in a single 3088 operation. A Get-Jobs operation followed by a Get- 3089 Subscriptions operation for each Job will return all Per-Job 3090 Subscriptions. 3092 11.2.5.1.2 "limit" (integer(1:MAX)) 3094 The client OPTIONALLY supplies this attribute. The Printer 3095 MUST support this attribute. It is an integer value that 3096 determines the maximum number of Subscription Objects that a 3097 client will receive from the Printer even if the "my- 3098 subscriptions" attribute constrains which Subscription Objects 3099 are returned. The limit is a "stateless limit" in that if the 3100 value supplied by the client is 'N', then only the first 'N' 3101 Subscription Objects are returned in the Get-Subscriptions 3102 Response. There is no mechanism to allow for the next 'M' 3103 Subscription Objects after the first 'N' Subscription Objects. 3104 If the client does not supply this attribute, the Printer 3105 responds with all applicable Subscription Objects. 3107 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword) 3109 The client OPTIONALLY supplies this attribute. The Printer 3110 MUST support this attribute. This attribute specifies the 3111 attributes of the specified Subscription Objects that the 3112 Printer MUST return in the response. Each value of this 3113 attribute is either an attribute name (defined in sections 5.3 3114 and 5.4) or an attribute group name (defined in section 3115 11.2.4.1). If the client omits this attribute, the Printer 3116 MUST respond as if the client had supplied this attribute with 3117 the one value: 'notify-subscription-id'. 3119 11.2.5.1.4 "my-subscriptions" (boolean) 3121 The client OPTIONALLY supplies this attribute. The Printer 3122 MUST support this attribute. If the value is 'false', the 3123 Printer MUST consider the Subscription Objects from all users 3124 as candidates. If the value is 'true', the Printer MUST return 3125 the Subscription Objects created by the requesting user of this 3126 request. If the client does not supply this attribute, the 3127 Printer MUST respond as if the client had supplied the 3128 attribute with a value of 'false'. The means for 3129 authenticating the requesting user and matching the 3130 Subscription Objects is similar to that for Jobs which is 3131 described in [RFC2911] section 8. 3133 11.2.5.2 Get-Subscriptions Response 3135 The Printer returns the following sets of attributes as part of the 3136 Get-Subscriptions Response: 3138 Group 1: Operation Attributes 3140 Status Message: 3141 Same as [RFC2911]. 3143 Natural Language and Character Set: 3144 The "attributes-charset" and "attributes-natural-language" 3145 attributes as described in [RFC2911] section 3.1.4.2. 3147 Group 2: Unsupported Attributes 3149 Same as for Get-Subscription-Attributes. 3151 Groups 3 to N: Subscription Attributes 3153 The Printer responds with one Subscription Attributes Group for 3154 each requested Subscription Object (see the "notify-job-id" 3155 attribute in the Operation Attributes Group of this operation). 3157 The Printer returns Subscription Objects in any order. 3159 If the "limit" attribute is present in the Operation Attributes 3160 group of the request, the number of Subscription Attributes 3161 Groups in the response MUST NOT exceed the value of the "limit" 3162 attribute. 3164 It there are no Subscription Objects associated with the 3165 specified Job or Printer, the Printer MUST return zero 3166 Subscription Attributes Groups and it MUST NOT treat this case 3167 as an error, i.e., the status-code MUST be 'successful-ok' 3168 unless something else causes the status code to have some other 3169 value. 3171 See the Group 3 response (Subscription Attributes Group) of the 3172 Get-Subscription-Attributes operation (section 11.2.4.2) for 3173 the attributes that a Printer returns in this group. 3175 11.2.6 Renew-Subscription operation 3177 This operation allows a client to request the Printer to extend the 3178 lease on a Per-Printer Subscription Object. 3180 The Printer MUST support this operation. 3182 The Printer MUST accept this request for a Per-Printer Subscription 3183 Object in any of the target Printer's states, i.e., 'idle', 3184 'processing', or 'stopped', but MUST NOT change the Printer's 3185 "printer-state" attribute. 3187 The Printer MUST reject this request for a Per-Job Subscription 3188 Object because it has no lease (see section 5.4.3). The status code 3189 returned MUST be 'client-error-not-possible'. 3191 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3192 performing this operation MUST (1) be the owner of the Per-Printer 3193 Subscription Object, (2) have Operator or Administrator access rights 3194 for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3195 otherwise authorized by the Printer's administrator-configured 3196 security policy to renew Per-Printer Subscription Objects for the 3197 target Printer. Otherwise, the Printer MUST reject the operation and 3198 return: the 'client-error-forbidden', 'client-error-not- 3199 authenticated', or 'client-error-not-authorized' status code as 3200 appropriate. 3202 11.2.6.1 Renew-Subscription Request 3204 The following groups of attributes are part of the Renew-Subscription 3205 Request: 3207 Group 1: Operation Attributes 3209 Natural Language and Character Set: 3210 The "attributes-charset" and "attributes-natural-language" 3211 attributes as described in [RFC2911] section 3.1.4.1. 3213 Target: 3214 The "printer-uri" attribute which defines the target for this 3215 operation as described in [RFC2911] section 3.1.5. 3217 Requesting User Name: 3218 The "requesting-user-name" (name(MAX)) attribute SHOULD be 3219 supplied by the client as described in [RFC2911] section 8.3. 3221 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)) 3223 The client MUST supply this attribute. The Printer MUST 3224 support this attribute. This attribute specifies the Per- 3225 Printer Subscription Object whose lease the Printer MUST renew. 3226 If the client omits this attribute, the Printer MUST reject 3227 this request with the 'client-error-bad-request' status code. 3229 Group 2: Subscription Template Attributes 3231 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX)) 3233 The client MAY supply this attribute. It indicates the number 3234 of seconds to renew the lease for the specified Subscription 3235 Object. A value of 0 requests an infinite lease (which MAY 3236 require Operator access rights). If the client omits this 3237 attribute, the Printer MUST use the value of the Printer's 3238 "notify-lease-duration-default" attribute. See section 5.3.8 3239 for more details. 3241 11.2.6.2 Renew-Subscription Response 3243 The Printer returns the following sets of attributes as part of the 3244 Renew-Subscription Response: 3246 Group 1: Operation Attributes 3248 Status Message: 3249 Same as [RFC2911]. 3251 The following are some of the status codes returned (see 3252 [RFC2911]: 3254 successful-ok: The operation successfully renewed the lease 3255 on the Subscription Object for the requested duration. 3256 successful-ok-ignored-or-substituted-attributes: The 3257 operation successfully renewed the lease on the 3258 Subscription Object for some duration other than the 3259 amount requested. 3260 client-error-not-possible: The operation failed because the 3261 "notify-subscription-id" Operation attribute identified a 3262 Per-Job Subscription Object. 3263 client-error-not-found: The operation failed because the 3264 "notify-subscription-id" Operation attribute identified a 3265 non-existent Subscription Object. 3267 Natural Language and Character Set: 3268 The "attributes-charset" and "attributes-natural-language" 3269 attributes as described in [RFC2911] section 3.1.4.2. The 3270 "attributes-natural-language" MAY be the natural language of 3271 the Subscription Object, rather than the one requested. 3273 Group 2: Unsupported Attributes 3275 See [RFC2911] section 3.1.7 for details on returning 3276 Unsupported Attributes. 3278 Group 3: Subscription Attributes 3280 The Printer MUST return the following Subscription Attribute: 3282 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX)) 3284 The value of this attribute MUST be the number of seconds that 3285 the Printer has granted for the lease of the Subscription 3286 Object (see section 5.3.8 for details, such as the value of 3287 this attribute when the Printer doesn't support the requested 3288 value). 3290 11.2.7 Cancel-Subscription operation 3292 This operation allows a client to delete a Subscription Object and 3293 stop the Printer from sending more Event Notifications. Once 3294 performed, there is no way to reference the Subscription Object. 3296 A Printer MUST supported this operation. 3298 The Printer MUST accept this request in any of the target Printer's 3299 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 3300 the Printer's "printer-state" attribute. 3302 If the specified Subscription Object is a Per-Job Subscription 3303 Object, the Printer MUST accept this request in any of the target 3304 Job's states, but MUST NOT change the Job's "job-state" attribute or 3305 affect the Job. 3307 Note: There is no way to change any attributes on a Subscription 3308 Object, except the "notify-lease-duration" attribute (using the 3309 Renew-Subscription operation). In order to change other attributes, 3310 a client performs a Subscription Creation Operation and Cancel- 3311 Subscription operation on the old Subscription Object. If the client 3312 wants to avoid missing Event Notifications, it performs the 3313 Subscription Creation Operation first. If this order would create 3314 too many Subscription Objects on the Printer, the client reverses the 3315 order. 3317 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3318 performing this operation MUST (1) be the owner of the Subscription 3319 Object, (2) have Operator or Administrator access rights for the 3320 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 3321 authorized by the Printer's administrator-configured security policy 3322 to cancel the target Subscription Object. Otherwise, the Printer 3323 MUST reject the operation and return: the 'client-error-forbidden', 3324 'client-error-not-authenticated', or 'client-error-not-authorized' 3325 status code as appropriate. 3327 11.2.7.1 Cancel-Subscription Request 3329 The following groups of attributes are part of the Cancel- 3330 Subscription Request: 3332 Group 1: Operation Attributes 3334 Natural Language and Character Set: 3335 The "attributes-charset" and "attributes-natural-language" 3336 attributes as described in [RFC2911] section 3.1.4.1. 3338 Target: 3339 The "printer-uri" attribute which defines the target for this 3340 operation as described in [RFC2911] section 3.1.5. 3342 Requesting User Name: 3343 The "requesting-user-name" attribute SHOULD be supplied by the 3344 client as described in [RFC2911] section 8.3. 3346 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)) 3348 The client MUST supply this attribute. The Printer MUST 3349 support this attribute. This attribute specifies the 3350 Subscription Object that the Printer MUST cancel. If the 3351 client omits this attribute, the Printer MUST reject this 3352 request with the 'client-error-bad-request' status code. 3354 11.2.7.2 Cancel-Subscription Response 3356 The Printer returns the following sets of attributes as part of the 3357 Cancel-Subscription Response: 3359 Group 1: Operation Attributes 3360 Status Message: 3361 Same as [RFC2911]. 3363 The following are some of the status codes returned (see 3364 [RFC2911]: 3366 successful-ok: The operation successfully canceled 3367 (deleted) the Subscription Object. 3368 client-error-not-found: The operation failed because the 3369 "notify-subscription-id" Operation attribute identified a 3370 non-existent Subscription Object. 3372 Natural Language and Character Set: 3373 The "attributes-charset" and "attributes-natural-language" 3374 attributes as described in [RFC2911] section 3.1.4.2. The 3375 "attributes-natural-language" MAY be the natural language of 3376 the Subscription Object, rather than the one requested. 3378 Group 2: Unsupported Attributes 3380 See [RFC2911] section 3.1.7 for details on returning 3381 Unsupported Attributes. 3383 12 Status Codes 3385 The following status codes are defined as extensions for Notification 3386 and are returned as the value of the "status-code" parameter in the 3387 Operation Attributes Group of a response (see [RFC2911] section 3388 3.1.6.1). Operations in this document can also return the status 3389 codes defined in section 13 of [RFC2911]. The 'successful-ok' status 3390 code is an example of such a status code. 3392 12.1 successful-ok-ignored-subscriptions (0x0003) 3394 The Subscription Creation Operation was unable to create all 3395 requested Subscription Objects. 3397 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3398 operation, this status code means that the Printer created one or 3399 more Subscription Objects, but not all requested Subscription 3400 Objects. 3402 For a Job Creation operation, this status code means that the Printer 3403 created the Job along with zero or more Subscription Objects. The 3404 Printer returns this status code even if other job attributes are 3405 unsupported or in conflict. That is, if an IPP Printer finds a 3406 warning that would allow it to return 'successful-ok-ignored- 3407 subscriptions' and either 'successful-ok-ignored-or-substituted- 3408 attributes' and/or 'successful-ok-conflicting-attributes', it MUST 3409 return 'successful-ok-ignored-subscriptions'. 3411 12.2 client-error-ignored-all-subscriptions (0x0414) 3413 This status code is the same as 'successful-ok-ignored-subscriptions' 3414 except that only the Create-Job-Subscriptions and Create-Printer- 3415 Subscriptions operation return it. They return this status code only 3416 when the Printer creates zero Subscription Objects. 3418 13 Status Codes in Subscription Attributes Groups 3420 This section contains values of the "notify-status-code" (type2 enum) 3421 attribute that the Printer returns in a Subscription Attributes Group 3422 in a response when the corresponding Subscription Object: 3424 1.is not created or 3426 2.is created and some of the client-supplied attributes are not 3427 supported. 3429 The following sections are ordered in decreasing order of importance 3430 of the status-codes. 3432 13.1 client-error-uri-scheme-not-supported (0x040C) 3434 This status code is defined in [RFC2911]. This document extends its 3435 meaning and allows it to be in a Subscription Attributes Group of a 3436 response. 3438 The scheme of the client-supplied URI in a "notify-recipient-uri" 3439 Subscription Template Attribute in a Subscription Creation Operation 3440 is not supported. See section 5.3.1. 3442 13.2 client-error-attributes-or-values-not-supported (0x040B) 3444 This status code is defined in [RFC2911]. This document extends its 3445 meaning and allows it to be in a Subscription Attributes Group of a 3446 response. 3448 The method of the client-supplied keyword in a "notify-pull-method" 3449 Subscription Template Attribute in a Subscription Creation Operation 3450 is not supported. See section 5.3.2. 3452 13.3 client-error-too-many-subscriptions (0x0415) 3454 The number of Subscription Objects supported by the Printer would be 3455 exceeded if this Subscription Object were created (see section 5.2). 3457 13.4 successful-ok-too-many-events (0x0005) 3459 The client supplied more Events in the "notify-events" operation 3460 attribute of a Subscription Creation Operation than the Printer 3461 supports, as indicated in its "notify-max-events-supported" Printer 3462 attribute (see section 5.3.3). 3464 13.5 successful-ok-ignored-or-substituted-attributes (0x0001) 3466 This status code is defined in [RFC2911]. This document extends its 3467 meaning to include unsupported Subscription Template Attributes and 3468 it can appear in a Subscription Attributes Group. 3470 14 Encodings of Additional Attribute Tags 3472 This section assigns values to two attributes tags as extensions to 3473 the encoding defined in [RFC2910]). 3475 The "subscription-attributes-tag" delimits Subscription Template 3476 Attributes Groups in requests and Subscription Attributes Groups in 3477 responses. 3479 The "event-notification-attributes-tag" delimits Event Notifications 3480 in Delivery Methods that use an IPP-like encoding. 3482 The following table specifies the values for the delimiter tags: 3484 Tag Value (Hex) Meaning 3486 0x06 "subscription-attributes-tag" 3488 0x07 "event-notification-attributes-tag" 3490 15 Conformance Requirements 3492 It is OPTIONAL for IPP clients and Printers to implement this Event 3493 Notification specification. 3495 15.1 Conformance requirements for clients 3497 If this Event Notification specification is implemented by a client, 3498 the client MUST support the 'ippget' Pull Delivery Method and meet 3499 the conformance requirements as defined in [ipp-get-method] for 3500 clients. A client MAY support additional Delivery Methods. 3502 15.2 Conformance requirements for Printers 3504 If this Event Notification specification is implemented by a Printer, 3505 the Printer MUST: 3507 - meet the Conformance Requirements detailed in section 5 of 3508 [RFC2911]. 3510 - support the Subscription Template Attributes Group in requests 3511 and the Subscription Attributes Group in responses. 3513 - support all of the following attributes: 3515 a.REQUIRED Subscription Object attributes in section 5. 3516 b.REQUIRED Printer Description object attributes in section 6. 3517 c.REQUIRED attributes in Event Notification content in section 3518 8. 3520 - support the 'ippget' Pull Delivery Method and meet the 3521 conformance requirements as defined in [ipp-get-method] for 3522 Printers. The Printer MAY support additional Push and Pull 3523 Delivery Methods. 3525 - send Event Notifications that conform to the requirements of 3526 section 9 and the requirements of the Delivery Method Document 3527 for each supported Delivery Method (the conformance 3528 requirements for Delivery Method Documents is specified in 3529 section 10). 3531 - for all of the Job Creation Operations that the Printer 3532 supports, MUST support the REQUIRED extensions for notification 3533 defined in section 11.1.3. 3535 - meet the conformance requirements for operations as described 3536 in Table 16 and meet the requirements for Printers as specified 3537 in the indicated sub-sections of section 11: 3539 Table 16 - Printer Conformance Requirements for Operations 3541 Operation Printer 3542 Conformance 3543 Requirements 3545 Create-Printer-Subscriptions (section 11.1.2) REQUIRED 3547 Create-Job-Subscriptions (section 11.1.1) OPTIONAL 3549 Get-Subscription-Attributes (section 11.2.3) REQUIRED 3551 Get-Subscriptions (section 11.2.5) REQUIRED 3553 Renew-Subscription (section 11.2.6) REQUIRED 3555 Cancel-Subscription (section 11.2.7) REQUIRED 3557 16 Normative References 3559 [ipp-get-method] 3560 Herriot, R., and T. Hastings, "Internet Printing Protocol (IPP): 3561 The 'ippget' Delivery Method for Event Notifications", , June 27, 2002. 3564 [ipp-prog] 3565 Hastings, T., Bergman, R., and H. Lewis, "IPP: Job Progress 3566 Attributes", work in progress, 3567 July 17, 2001. 3569 [RFC2119] 3570 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3571 Levels", RFC 2119 , March 1997 3573 [RFC2396] 3574 Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource 3575 Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 3577 [RFC2717] 3578 R. Petke and I. King, "Registration Procedures for URL Scheme 3579 Names", RFC 2717, November 1999. 3581 [RFC2910] 3582 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3583 Printing Protocol/1.1: Encoding and Transport", RFC 2910, September 3584 2000. 3586 [RFC2911] 3587 deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, 3588 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 3589 September 2000. 3591 17 Informative References 3593 [IANA-CON] 3594 Narte, T. and H. Alvestrand, "Guidelines for Writing an IANA 3595 Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 3597 [ipp-not-req] 3598 deBry, R., Lewis, H., and T. Hastings, "Internet Printing 3599 Protocol/1.1: Requirements for IPP Notifications", , work in progress, July 17, 2001. 3602 [RFC2565] 3603 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3604 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 3605 1999. 3607 [RFC2566] 3608 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., and P. 3609 Powell, "Internet Printing Protocol/1.0: Model and Semantics", RFC 3610 2566, April 1999. 3612 [RFC2567] 3613 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3614 2567, April 1999. 3616 [RFC2568] 3617 Zilles, S., "Rationale for the Structure and Model and Protocol for 3618 the Internet Printing Protocol", RFC 2568, April 1999. 3620 [RFC2569] 3621 Herriot, R., Hastings, T., Jacobs, N., and J. Martin, "Mapping 3622 between LPD and IPP Protocols", RFC 2569, April 1999. 3624 [RFC2616] 3625 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 3626 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol - 3627 HTTP/1.1", RFC 2616, June 1999. 3629 [RFC3196] 3630 Hastings, T., Manros, C., Zehler, P., Kugler, C., and H. Holst, 3631 "Internet Printing Protocol/1.1: Implementer's Guide", RFC3196, 3632 November 2001. 3634 18 Security Considerations 3636 Clients submitting Notification requests to the IPP Printer have the 3637 same security issues as submitting an IPP/1.1 print job request (see 3638 [RFC2911] section 3.2.1 and section 8). The same mechanisms used by 3639 IPP/1.1 can therefore be used by the client Notification submission. 3640 Operations that require authentication can use the HTTP 3641 authentication. Operations that require privacy can use the HTTP/TLS 3642 privacy. As with IPP/1.1 Print Job Objects, if there is no security 3643 on Subscription Objects, sequential assignment of subscription-ids 3644 exposes the system to a passive traffic monitoring threat. 3646 18.1 Client access rights 3648 The Subscription Object access control model is the same as the 3649 access control model for Job objects. The client MUST have the 3650 following access rights for the indicated Subscription operations: 3652 1. Create-Job-Subscriptions (see section 11.1.1): A Per-Job 3653 Subscription object is associated with a Job. To create Per-Job 3654 Subscription Objects, the authenticated user (see [RFC2911] 3655 section 8.3) performing this operation MUST (1) be the job 3656 owner, (2) have Operator or Administrator access rights for this 3657 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 3658 authorized by the Printer's administrator-configured security 3659 policy to create Per-Job Subscription Objects for the target 3660 job. 3662 2. Create-Printer-Subscriptions (see section 11.1.2): A Per- 3663 Printer Subscription object is associated with the Printer. To 3664 create Per-Printer Subscription Objects, the authenticated user 3665 (see [RFC2911] section 8.3) performing this operation MUST (1) 3666 have Operator or Administrator access rights for this Printer 3667 (see [RFC2911] sections 1 and 8.5) or (2) be otherwise 3668 authorized by the Printer's administrator-configured security 3669 policy to create Per-Printer Subscription Objects for this 3670 Printer. 3672 3. Get-Subscription-Attributes (see section 11.2.4): The access 3673 control model for this operation is the same as that of the Get- 3674 Job-Attributes operation (see [RFC2911] section 3.3.4). The 3675 primary difference is that a Get-Subscription-Attributes 3676 operation is directed at a Subscription Object rather than at a 3677 Job object, and a returned attribute group contains Subscription 3678 Object attributes rather than Job object attributes. To query 3679 the specified Subscription Object, the authenticated user (see 3680 [RFC2911] section 8.3) performing this operation MUST (1) be the 3681 Subscription Object owner, (2) have Operator or Administrator 3682 access rights for this Printer (see [RFC2911] sections 1 and 3683 8.5), or (3) be otherwise authorized by the Printer's 3684 administrator-configured security policy to query the 3685 Subscription Object for the target job. Furthermore, the 3686 Printer's security policy MAY limit which attributes are 3687 returned, in a manner similar to the Get-Job-Attributes 3688 operation (see [RFC2911] end of section 3.3.4.2). 3690 4. Get-Subscriptions (see section 11.2.5): The access control 3691 model for this operation is the same as that of the Get-Jobs 3692 operation (see [RFC2911] section 3.2.6). The primary difference 3693 is that the operation is directed at Subscription Objects rather 3694 than at Job objects, and the returned attribute groups contain 3695 Subscription Object attributes rather than Job object 3696 attributes. To query Per-Job Subscription Objects of the 3697 specified job (client supplied the "notify-job-id" operation 3698 attribute - see section 11.2.5.1.1), the authenticated user (see 3699 [RFC2911] section 8.3) performing this operation MUST (1) be the 3700 Subscription Object owner, (2) have Operator or Administrator 3701 access rights for this Printer (see [RFC2911] sections 1 and 3702 8.5), or (3) be otherwise authorized by the Printer's 3703 administrator-configured security policy to query the 3704 Subscription Object for the target job. To query Per-Printer 3705 Subscription Objects of the Printer (client omits the "notify- 3706 job-id" operation attribute - see section 11.2.5.1.1), the 3707 authenticated user (see [RFC2911] section 8.3) performing this 3708 operation MUST (1) have Operator or Administrator access rights 3709 for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be 3710 otherwise authorized by the Printer's administrator-configured 3711 security policy to query Per-Printer Subscription Objects for 3712 the target Printer. Furthermore, the Printer's security policy 3713 MAY limit which attributes are returned, in a manner similar to 3714 the Get-Job-Attributes operation (see [RFC2911] end of section 3715 3.2.6.2). 3717 5. Renew-Subscriptions (see section 11.2.6): The authenticated 3718 user (see [RFC2911] section 8.3) performing this operation MUST 3719 (1) be the owner of the Per-Printer Subscription Object, (2) 3720 have Operator or Administrator access rights for the Printer 3721 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 3722 authorized by the Printer's administrator-configured security 3723 policy to renew Per-Printer Subscription Objects for the target 3724 Printer 3726 6. Cancel-Subscription (see section 11.2.7): The authenticated 3727 user (see [RFC2911] section 8.3) performing this operation MUST 3728 (1) be the owner of the Subscription Object, (2) have Operator 3729 or Administrator access rights for the Printer (see [RFC2911] 3730 sections 1 and 8.5), or (3) be otherwise authorized by the 3731 Printer's administrator-configured security policy to cancel the 3732 target Subscription Object. 3734 The standard security concerns (delivery to the right user, privacy 3735 of content, tamper proof content) apply to each Delivery Method. 3736 Some Delivery Methods are more secure than others. Each Delivery 3737 Method Document MUST discuss its Security Considerations. 3739 18.2 Printer security threats 3741 Notification trap door: If a Printer supports the OPTIONAL "notify- 3742 attributes" Subscription Template attribute (see section 5.3.4) where 3743 the client can request that the Printer return any specified Job, 3744 Printer, and Subscription object attributes, the Printer MUST apply 3745 the same security policy to these requested attributes in the Get- 3746 Notifications request as it does for the Get-Jobs, Get-Job- 3747 Attributes, Get-Printer-Attributes, and Get-Subscription-Attributes 3748 requests. 3750 18.3 Notification Recipient security threats 3752 Unwanted Events Notifications (spam): For any Push Delivery Method, 3753 by far the biggest security concern is the abuse of notification: 3754 sending unwanted Event Notifications to third parties (i.e., spam). 3755 The problem is made worse by notification addresses that may be 3756 redistributed to multiple parties. There exist scenarios where third 3757 party notification is used (see Scenario #2 and #3 in [ipp-not-req]). 3758 Any fully secure solution would require active agreement of all 3759 recipients before sending out anything. 3761 19 IANA Considerations 3763 This section contains the registration information for IANA to add to 3764 the various IPP Registries according to the procedures defined in RFC 3765 2911 [RFC2911] section 6 to cover the definitions in this document. 3766 In addition, this section defines how Events and Delivery Methods 3767 will be registered when they are defined in other documents. 3769 Note to RFC Editors: Replace RFC NNNN below with the RFC number 3770 for this document, so that it accurately reflects the content of 3771 the information for the IANA Registry. 3773 19.1 Attribute Registrations 3775 The following table lists all the attributes defined in this 3776 document. These are to be registered according to the procedures in 3777 RFC 2911 [RFC2911] section 6.2. 3779 Subscription Template attributes: Ref. Section: 3780 notify-recipient-uri (uri) RFC NNNN 5.3.1 3781 notify-schemes-supported (1setOf uriScheme) RFC NNNN 5.3.1 3782 notify-pull-method (type2 keyword) RFC NNNN 5.3.2 3783 notify-pull-method-supported (1setOf type2 keyword) 3784 RFC NNNN 5.3.2 3785 notify-events (1setOf type2 keyword) RFC NNNN 5.3.3 3786 notify-events-default (1setOf type2 keyword) RFC NNNN 5.3.3 3787 notify-events-supported (1setOf type2 keyword) RFC NNNN 5.3.3 3788 notify-max-events-supported (integer(2:MAX)) RFC NNNN 5.3.3 3789 notify-attributes (1setOf type2 keyword) RFC NNNN 5.3.4 3790 notify-attributes-supported (1setOf type2 keyword) 3791 RFC NNNN 5.3.4 3792 notify-user-data (octetString(63)) RFC NNNN 5.3.5 3793 notify-charset (charset) RFC NNNN 5.3.6 3794 notify-natural-language (naturalLanguage) RFC NNNN 5.3.7 3795 notify-lease-duration (integer(0:67108863)) RFC NNNN 5.3.8 3796 notify-lease-duration-default (integer(0:67108863)) 3797 RFC NNNN 5.3.8 3798 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 3799 rangeOfInteger(0:67108863))) RFC NNNN 5.3.8 3800 notify-time-interval (integer(0:MAX)) RFC NNNN 5.3.9 3802 Subscription Description Attributes: 3803 notify-subscription-id (integer (1:MAX))) RFC NNNN 5.4.1 3804 notify-sequence-number (integer (0:MAX))) RFC NNNN 5.4.2 3805 notify-lease-expiration-time (integer(0:MAX))) RFC NNNN 5.4.3 3806 notify-printer-up-time (integer(1:MAX))) RFC NNNN 5.4.4 3807 notify-printer-uri (uri)) RFC NNNN 5.4.5 3808 notify-job-id (integer(1:MAX))) RFC NNNN 5.4.6 3809 notify-subscriber-user-name (name(MAX))) RFC NNNN 5.4.7 3811 Printer Description Attributes: 3812 printer-state-change-time (integer(1:MAX))) RFC NNNN 6.1 3813 printer-state-change-date-time (dateTime)) RFC NNNN 6.2 3815 Attributes Only in Event Notifications 3816 notify-subscribed-event (type2 keyword) RFC NNNN 8.1 3817 notify-text (text(MAX)) RFC NNNN 8.2 3819 The resulting attribute registrations will be published in the 3820 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attributes/ 3821 area. 3823 19.2 Additional Enum Attribute Value Registrations for the "operations- 3824 supported" Printer Attribute 3826 The following table lists all the new enum attribute values defined 3827 in this document as additional type2 enum values for use with the 3828 "operations-supported" Printer Description attribute. These are to 3829 be registered according to the procedures in RFC 2911 [RFC2911] 3830 section 6.1. 3832 type2 enum Attribute Values: Value Ref. Section: 3833 Create-Printer-Subscriptions 0x0016 RFC NNNN 7.1 3834 Create-Job-Subscriptions 0x0017 RFC NNNN 7.1 3835 Get-Subscription-Attributes 0x0018 RFC NNNN 7.1 3836 Get-Subscriptions 0x0019 RFC NNNN 7.1 3837 Renew-Subscription 0x001A RFC NNNN 7.1 3838 Cancel-Subscription 0x001B RFC NNNN 7.1 3840 The resulting enum attribute value registrations will be published in 3841 the 3842 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 3843 values/operations-supported/ 3844 area. 3846 19.3 Operation Registrations 3848 The following table lists all of the operations defined in this 3849 document. These are to be registered according to the procedures in 3850 RFC 2911 [RFC2911] section 6.4. 3852 Operations: Ref. Section: 3853 Create-Job-Subscriptions Operation RFC NNNN 11.1.1 3854 Create-Printer-Subscriptions Operation RFC NNNN 11.1.2 3855 Job Creation Operations - Extensions RFC NNNN 11.1.3 3856 Validate-Job Operation - Extensions RFC NNNN 11.2.2 3857 Get-Printer-Attributes - Extensions RFC NNNN 11.2.3 3858 Get-Subscription-Attributes Operation RFC NNNN 11.2.4 3859 Get-Subscriptions Operation RFC NNNN 11.2.5 3860 Renew-Subscription Operation RFC NNNN 11.2.6 3861 Cancel-Subscription Operation RFC NNNN 11.2.7 3863 The resulting operation registrations will be published in the 3864 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/operations/ 3865 area. 3867 19.4 Status code Registrations 3869 The following table lists all the status codes defined in this 3870 document. These are to be registered according to the procedures in 3871 RFC 2911 [RFC2911] section 6.6. 3873 Status codes: Ref. Section: 3874 successful-ok-ignored-subscriptions (0x0003) RFC NNNN 12.1 3875 client-error-ignored-all-subscriptions (0x0414) RFC NNNN 12.2 3877 Status Codes in Subscription Attributes Groups: 3878 client-error-uri-scheme-not-supported (0x040C) RFC NNNN 13.1 3879 client-error-attributes-or-values-not-supported (0x040B) 3880 RFC NNNN 13.2 3881 client-error-too-many-subscriptions (0x0415) RFC NNNN 13.3 3882 successful-ok-too-many-events (0x0005) RFC NNNN 13.4 3883 successful-ok-ignored-or-substituted-attributes (0x0001) 3884 RFC NNNN 13.5 3886 The resulting status code registrations will be published in the 3887 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/status-codes/ 3888 area. 3890 19.5 Attribute Group tag Registrations 3892 The following table lists all the attribute group tags defined in 3893 this document. These are to be registered according to the 3894 procedures in RFC 2911 [RFC2911] section 6.5. 3896 Attribute Group Tags: Tag Value: Ref. Section: 3897 subscription-attributes-tag 0x06 RFC NNNN 14 3898 event-notification-attributes-tag 0x07 RFC NNNN 14 3900 The resulting attribute group tag registrations will be published in 3901 the 3902 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-group- 3903 tags/ 3904 area. 3906 19.6 Registration of Events 3908 When other document define additional type2 keywords to be used with 3909 the "notify-events" Subscription Template attribute (see section 3910 5.3.3)), these event keywords will be registered according to the 3911 procedures of [RFC2911] section 7.1 as additional attribute values 3912 for use with the "notify-events" Subscription Template attribute, 3913 i.e., the "notify-events", "notify-events-default", and "notify- 3914 events-supported" attributes. 3916 Therefore, the IPP Registry entry for an Event will be of the form: 3918 type2 enum Attribute Values: Ref. Section: 3919 RFC xxxx m.n 3921 The resulting type2 keyword attribute values will be published in the 3922 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 3923 values/notify-events/ 3924 area. 3926 19.7 Registration of Event Notification Delivery Methods 3928 This section describes the requirements and procedures for 3929 registration and publication of Event Notification Delivery Methods 3930 and for the submission of such proposals. 3932 19.7.1 Requirements for Registration of Event Notification Delivery 3933 Methods 3935 Registered IPP Event Notification Delivery Methods are expected to 3936 follow a number of requirements described below. 3938 19.7.1.1 Required Characteristics 3940 A Delivery Method Document MUST either (1) contain all of the 3941 semantics of the Delivery Method or (2) contain the IPP Delivery 3942 Method registration requirements and a profile of some other protocol 3943 that in combination is the Delivery Method (e.g., mailto). The 3944 Delivery Method Document (and any documents it requires) MUST define 3945 either (1) a URL for a Push Delivery Method that the meets the 3946 requirements of [RFC2717]. or (2) a keyword for a Pull Delivery 3947 method. 3949 IPP Event Notification Delivery Method Documents MUST meet the 3950 requirements of this document (see sections 9 and 10). 3952 In addition, a Delivery Method Document MUST contain the following 3953 information: 3955 Type of registration: IPP Event Notification Delivery Method 3956 Name of this delivery method: 3957 Proposed URL scheme name of this Push Delivery Method or the 3958 keyword name of this Pull Delivery Method: 3960 Name of proposer: 3961 Address of proposer: 3962 Email address of proposer: 3963 Is this delivery method REQUIRED or OPTIONAL for conformance to the 3964 IPP Event Notification and Subscriptions document: 3965 Is this delivery method defining Machine Consumable and/or Human 3966 Consumable content: 3968 19.7.1.2 Naming Requirements 3970 Exactly one (URL scheme or keyword) name MUST be assigned to each 3971 Delivery Method. 3973 Each assigned name MUST uniquely identify a single Delivery Method. 3974 All Push Delivery Method names MUST conform to the rules for URL 3975 scheme names, according to [RFC2396] and [RFC2717] for schemes in the 3976 IETF tree. All Pull Delivery Method names MUST conform to the rules 3977 for keywords according to [RFC2911]. 3979 19.7.1.3 Functionality Requirements 3981 Delivery Methods MUST function as a protocol that is capable of 3982 delivering (push or pull) IPP Event Notifications to Notification 3983 Recipients. 3985 19.7.1.4 Usage and Implementation Requirements 3987 Use of a large number of Delivery Methods may hamper 3988 interoperability. However, the use of a large number of undocumented 3989 and/or unlabelled Delivery Methods hampers interoperability even 3990 more. 3992 A Delivery Method should therefore be registered ONLY if it adds 3993 significant functionality that is valuable to a large community, OR 3994 if it documents existing practice in a large community. Note that 3995 Delivery Methods registered for the second reason should be 3996 explicitly marked as being of limited or specialized use and should 3997 only be used with prior bilateral agreement. 3999 19.7.1.5 Publication Requirements 4001 Delivery Method Documents MUST be published in a standards track, 4002 informational, or experimental RFCs. 4004 19.7.2 Registration Procedure 4006 The IPP WG is developing a small number of Delivery Methods which are 4007 intended to be published as standards track RFCs. However, some 4008 parties may wish to register additional Delivery Methods in the 4009 future. This section describes the procedures for these additional 4010 Delivery Methods. 4012 19.7.2.1 Present the proposal to the Community 4014 First the Delivery Method Document MUST be an Internet-Draft with a 4015 target category of standards track, informational, or experimental. 4016 The same MUST be true for any documents that it references. 4018 Send the proposed Delivery Method Document proposal to the 4019 "ipp@pwg.org" mailing list. This mailing list has been established 4020 by [RFC2911] for reviewing proposed registrations and discussing 4021 other IPP matters. Proposed Delivery Method Documents are not 4022 formally registered and MUST NOT be used until approved. 4024 The intent of the public posting is to solicit comments and feedback 4025 on the definition and suitability of the Delivery Method and the name 4026 chosen for it over a four week period. 4028 19.7.2.2 Delivery Method Reviewer 4030 The Delivery Method Reviewer is the same person who has been 4031 appointed by the IETF Application Area Director(s) as the IPP 4032 Designated Expert according to [RFC2911] and [IANA-CON]. When the 4033 four week period is over and the IPP Designated Expert is convinced 4034 that consensus has been achieved, the IPP Designated Expert either 4035 approves the request for registration or rejects it. Rejection may 4036 occur because of significant objections raised on the list or 4037 objections raised externally. 4039 Decisions made by the Reviewer must be posted to the ipp@pwg.org 4040 mailing list within 14 days. Decisions made by the Reviewer may be 4041 appealed to the IESG. 4043 19.7.2.3 IANA Registration 4045 Provided that the Delivery Method registration proposal has either 4046 passed review or has been successfully appealed to the IESG, the IANA 4047 will register the Delivery Method and make it available to the 4048 community. 4050 19.7.3 Delivery Method Document Registrations 4052 Each Push Delivery Method Document defines a URI scheme which is 4053 registered as an additional value of the "notify-schemes-supported" 4054 Printer attribute. These uriScheme values will be registered 4055 according to the procedures of [RFC2911] section 7.1 for additional 4056 attribute values. Therefore, the IPP Registry entry for a Push 4057 Delivery Method will be of the form: 4059 uriScheme Attribute Values: Ref. Section: 4060 RFC xxxx m.n 4062 The resulting Delivery Method URI schemes will be published in the 4063 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 4064 values/notify-schemes-supported/ 4065 area. 4067 Each Pull Delivery Method Document defines a keyword method which is 4068 registered as an additional value of the "notify-pull-method- 4069 supported" Printer attribute. These keyword values will be 4070 registered according to the procedures of [RFC2911] section 7.1 for 4071 additional attribute values. Therefore, the IPP Registry entry for a 4072 Pull Delivery Method will be of the form: 4074 keyword Attribute Values: Ref. Section: 4075 RFC xxxx m.n 4077 The resulting Delivery Method URI schemes will be published in the 4078 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 4079 values/notify-pull-method-supported/ 4080 area. 4082 19.7.4 Registration Template 4084 To: ipp@pwg.org 4085 Subject: Registration of a new Delivery Method 4087 Delivery Method name: 4089 (All Push Delivery Method names must be suitable for use as the value 4090 of a URL scheme in the IETF tree and all Pull Delivery Method names 4091 must be suitable IPP keywords according to [RFC2911]) 4093 Published specification(s): 4095 (A specification for the Delivery Method must be openly available 4096 that accurately describes what is being registered.) 4097 Person & email address to contact for further information: 4099 20 Internationalization Considerations 4101 This IPP Notification specification continues support for the 4102 internationalization of [RFC2911] of attributes containing text 4103 strings and names. Allowing a Subscribing Client to specify a 4104 different natural language and charset for each Subscription Object 4105 increases the internationalization support. 4107 The Printer MUST be able to localize the content of Human Consumable 4108 Event Notifications and to localize the value of "notify-text" 4109 attribute in Machine Consumable Event Notifications that it sends to 4110 Notification Recipients. For localization, the Printer MUST use the 4111 value of the "notify-charset" attribute and the "notify-natural- 4112 language" attribute in the Subscription Object supplied by the 4113 Subscribing Client. 4115 21 Contributors 4117 The following people made significant contributions to the design and 4118 review of this specification: 4120 Scott A. Isaacson 4121 Novell, Inc. 4122 122 E 1700 S 4123 Provo, UT 84606 4125 Phone: 801-861-7366 4126 Fax: 801-861-2517 4127 e-mail: sisaacson@novell.com 4129 Roger deBry 4130 Utah Valley State College 4131 Orem, UT 84058 4133 Phone: (801) 222-8000 4134 EMail: debryro@uvsc.edu 4136 Jay Martin 4137 Underscore Inc. 4138 9 Jacqueline St. 4139 Hudson, NH 03051-5308 4140 603-889-7000 4141 fax: 775-414-0245 4142 e-mail: jkm@underscore.com 4143 Michael Shepherd 4144 Xerox Corporation 4145 800 Phillips Road MS 128-51E 4146 Webster, NY 14450 4148 Phone: 716-422-2338 4149 Fax: 716-265-8871 4150 e-mail: mshepherd@crt.xerox.com 4152 Ron Bergman 4153 Hitachi Koki Imaging Solutions 4154 1757 Tapo Canyon Road 4155 Simi Valley, CA 93063-3394 4157 Phone: 805-578-4421 4158 Fax: 805-578-4001 4159 Email: rbergma@hitachi-hkis.com 4161 22 Author's Addresses 4163 Robert Herriot 4164 706 Colorado Ave. 4165 Palo Alto, CA 94303 4167 Phone: 650-327-4466 4168 Fax: 650-327-4466 4169 Email: bob@herriot.com 4171 Tom Hastings 4172 Xerox Corporation 4173 737 Hawaii St. ESAE 231 4174 El Segundo, CA 90245 4176 Phone: 310-333-6413 4177 Fax: 310-333-5514 4178 e-mail: hastings@cp10.es.xerox.com 4180 IPP Web Page: http://www.pwg.org/ipp/ 4181 IPP Mailing List: ipp@pwg.org 4183 To subscribe to the ipp mailing list, send the following email: 4184 1) send it to majordomo@pwg.org 4185 2) leave the subject line blank 4186 3) put the following two lines in the message body: 4187 subscribe ipp 4188 end 4190 Implementers of this specification document are encouraged to join 4191 the IPP Mailing List in order to participate in any discussions of 4192 clarification issues and review of registration proposals for 4193 additional attributes and values. In order to reduce spam the 4194 mailing list rejects mail from non-subscribers, so you must subscribe 4195 to the mailing list in order to send a question or comment to the 4196 mailing list. 4198 A. Appendix - Model for Notification with Cascading Printers 4200 With this model (see Figure 2), there is an intervening Print server 4201 between the human user and the output-device. So the system 4202 effectively has two Printers. There are two cases to consider. 4204 1.When the Printer 1 (in the server) generates Events, the system 4205 behaves like the client and Printer in Figure 1. In this case, 4206 Printer 1 sends Event Notifications that are shown as Event 4207 Notifications (A) of Figure 2,. 4209 2.When the Printer 2 (in the output-device) generates Events, there 4210 are two possible system configurations: 4212 a)Printer 1 forwards the client-supplied Subscription Creation 4213 Operations to the downstream Printer 2 and lets Printer 2 send 4214 the Event Notifications directly to the Notification Recipients 4215 supplied by the Client (Event Notifications(C) in the diagram). 4217 b)Printer 1 performs the client-supplied Subscription Creation 4218 Operations and also forwards the Subscription Creation 4219 Operations to Printer 2 with the Notification Recipient changed 4220 to be the Printer 1. When an Event occurs in Printer 2, Printer 4221 2 sends the Event Notification (B) to Notification Recipient of 4222 Printer 1, which relays the received Event Notification (B) to 4223 the client-supplied Notification Recipient (as Event 4224 Notifications(A) in the diagram). Note, when a client performs 4225 a Subscription Creation Operation, Printer 1 need not forward 4226 the Subscription Creation Operation to Printer 2 if it would 4227 create a duplicate Subscription Object on Printer 2. 4229 Note: when Printer 1 is forwarding Subscription Creation Operations 4230 to Printer 2, it may request Printer 2 to create additional 4231 Subscription Objects (called "piggy-backing"). Piggy-backing is 4232 useful when: 4234 - Device A is configured to accept (IPP or non-IPP) requests from 4235 other servers. 4237 - Server S wants to receive Job Events that the client didn't 4238 request and Server S wants these Events for jobs it submits and 4239 not for other jobs. 4241 server S device A 4242 +------------+ +------------+ 4243 | | | | 4244 +--------+ Subscription | ###########| | ###########| 4245 | client |--Creation ----># Printer #| Subscription | # Printer #| 4246 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 4247 | ###|#######| Operation | ####|#|####| 4248 +----|---^---+ +-----|-|----+ 4249 +--------+ Event | | | | 4250 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 4251 |ation Re|<-------------Event Notifications(C)-----------------+ 4252 |cipient | 4253 +--------+ 4255 Figure 2 - Model for Notification with Cascading Printers 4257 B. Appendix - Distributed Model for Notification 4259 A Printer implementation could use some other remote notification 4260 service to provide some or most of the service. For example, the 4261 remote notification service could send Event Notifications using 4262 Delivery Methods that are not directly supported by the output device 4263 or server. Or, the remote notification service could store 4264 Subscription Objects (passed to it from the output device in response 4265 to Subscription Creation requests), accept Events, format the Event 4266 Notification in the natural language of the Notification Recipient, 4267 and send the Event Notifications to the Notification Recipient(s). 4269 Figure 3 shows this partitioning. The interface between the output 4270 device (or server) and the remote notification service is outside the 4271 scope of this document and is intended to be transparent to the 4272 client and this document. The combination of the output device (or 4273 server) and the notification service together constitute an IPP 4274 Printer conforming to this Notification document. 4276 *********************** 4277 * 4278 * Printer (including 4279 * the distributed 4280 * Notification Service) 4281 * 4282 * output device or server 4283 * +---------------+ 4284 PDA, desktop, or server * + ########### + 4285 +--------+ * | # partial # | 4286 | client |---IPP Subscription--------># Printer # | 4287 +--------+ Creation operation * | # Object # | 4288 * | #####|##### | 4289 * +-------|-------+ 4290 * | Subscriptions 4291 * | OR Event 4292 +------------+ * | Notifications 4293 |Notification| IPP-defined * +------v--------+ 4294 |Recipient |<--Event Notifications---| Notification | 4295 +------------+ * | Service | 4296 * +---------------+ 4297 * 4298 ************************* 4299 *** = Implementation configuration opaque boundary 4301 Figure 3 - Opaque Use of a Notification Service Transparent to the 4302 Client 4304 C. Appendix - Extended Notification Recipient 4306 The model allows for an extended Notification Recipient that is 4307 itself a notification service that forwards each Event Notification 4308 to another recipient (called the Ultimate Notification Recipient in 4309 this section). The Delivery Method to the Ultimate Recipient is 4310 probably different from the Delivery Method used by the Printer to 4311 the extended Notification Recipient. 4313 This extended Notification Recipient is transparent to the Printer 4314 but not to the client. 4316 When a client performs a Subscription Creation Operation, it 4317 specifies the extended Notification Recipient as it would any 4318 Notification Recipient. In addition, the client specifies the 4319 Ultimate Notification Recipient in the Subscription Creation 4320 Operation in a manner specified by the extended Notification 4321 Recipient. Typically, it is either some bytes in the value of 4322 "notify-user-data" or some additional parameter in the value of 4323 "notify-recipient-uri". The client also subscribes directly with the 4324 extended Notification Recipient (by means outside this document), 4325 since it is a notification service in its own right. 4327 The IPP Printer treats the extended Notification Recipient like any 4328 other Notification Recipient and the IPP Printer is not aware of the 4329 forwarding. The Delivery Method that the extended Notification 4330 Recipient uses for delivering the Event Notification to the Ultimate 4331 Notification Recipient is beyond the scope of this document and is 4332 transparent to the IPP Printer. 4334 Examples of this extended Notification Recipient are paging, 4335 immediate messaging services, general notification services, and NOS 4336 vendors' infrastructure. Figure 4 shows this approach. 4338 PDA, desktop, or server server or output device 4339 +---------------+ 4340 +--------+ | ########### | 4341 | client |---Subscription Creation -----------># Printer # | 4342 +--------+ Operation | # Object # | 4343 | #####|##### | 4344 +------------+ +------------+ IPP-defined +-------|-------+ 4345 |Ultimate | any |Notification|<--Event Notifications----+ 4346 |Notification|<----|Recipient | 4347 |Recipient | +------------+ 4348 +------------+ (Notification Service) 4350 Figure 4 - Use of an Extended Notification Recipient transparent to 4351 the Printer 4353 D. Appendix - Details about Conformance Terminology 4355 The following paragraphs provide more details about conformance 4356 terminology. 4358 REQUIRED - an adjective used to indicate that a conforming IPP 4359 Printer implementation MUST support the indicated operation, 4360 object, attribute, attribute value, status code, or out-of-band 4361 value in requests and responses. See [RFC2911] "Appendix A - 4362 Terminology for a definition of "support". Since support of this 4363 entire Notification specification is OPTIONAL for conformance to 4364 IPP/1.1, the use of the term REQUIRED in this document means 4365 "REQUIRED if this OPTIONAL Notification specification is 4366 implemented". 4368 RECOMMENDED - an adjective used to indicate that a conforming IPP 4369 Printer implementation is recommended to support the indicated 4370 operation, object, attribute, attribute value, status code, or 4371 out-of-band value in requests and responses. Since support of 4372 this entire Notification specification is OPTIONAL for conformance 4373 to IPP/1.1, the use of the term RECOMMENDED in this document means 4374 "RECOMMENDED if this OPTIONAL Notification specification is 4375 implemented". 4377 OPTIONAL - an adjective used to indicate that a conforming IPP 4378 Printer implementation MAY, but is NOT REQUIRED to, support the 4379 indicated operation, object, attribute, attribute value, status 4380 code, or out-of-band value in requests and responses. 4382 E. Appendix - Object Model for Notification 4384 This section describes the Notification object model that adds a 4385 Subscription Object which together with the Job and Printer object 4386 provide the complete Notification semantics. 4388 The object relationships can be seen pictorially as: 4390 Subscription Objects (Per-Printer Subscriptions) Printer object 4391 +----+ +------------+ 4392 | s1 |<--------------------------------------------->| | 4393 +----++ | | 4394 | s2 |<-------------------------------------------->| p1 | 4395 +----++ | | 4396 | s3 |<------------------------------------------->| | 4397 +----+ +------------+ 4398 Job objects 4399 +---------+ 4400 | | 4401 +----+ | j1 | 4402 | s4 |<------->| | 4403 +----+ | | 4404 | | s4 is a Per-Job Subscription Object 4405 ++--------++ 4406 | | 4407 +----+ | j2 | 4408 | s5 |<------>| | 4409 +----++ | | 4410 | s6 |<----->| | s5 and s6 are Per-Job Subscription 4411 +----+ ++--------++ Objects 4412 | | 4413 | j3 | 4414 | | 4415 | | <----> indicates association 4416 +---------+ 4418 Figure 5 - Object Model for Notification 4420 s1, s2, and s3 are Per-Printer Subscription Objects and can 4421 identify Printer and/or Job Events. 4422 s4, s5, and s6 are Per-Job Subscription Objects and can identify 4423 Printer and/or Job Events. 4425 E.1 Appendix - Object relationships 4427 This sub-section defines the object relationships between the 4428 Printer, Job, and Subscription Objects by example. Whether Per- 4429 Printer Subscription Objects are actually contained in a Printer 4430 object or are just bi-directionally associated with them in some way 4431 is IMPLEMENTATION DEPENDENT and is transparent to the client. 4432 Similarly, whether Per-Job Subscription Objects are actually 4433 contained in a Job object or are just bi-directionally associated 4434 with them in some way is IMPLEMENTATION DEPENDENT and is transparent 4435 to the client. The object relationships are defined as follows: 4437 E.2 Printer Object and Per-Printer Subscription Objects 4439 1.The Printer object contains (is associated with) zero or more 4440 Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer 4441 Subscription Objects). 4443 2.Each Per-Printer Subscription Object (s1, s2, and s3) is 4444 contained in (or is associated with) exactly one Printer object 4445 (p1). 4447 E.3 Job Object and Per-Job Subscription Objects 4449 1.A Job object (j1, j2, j3) is associated with zero or more Per- 4450 Job Subscription Objects (s4-s6). Job j1 is associated with 4451 Per-Job Subscription Object s4, Job j2 is associated with Per- 4452 Job Subscription Objects s5 and s6, and Job j3 is not associated 4453 with any Per-Job Subscription Object. 4455 2.Each Per-Job Subscription Object is associated with exactly one 4456 Job object. 4458 F. Appendix - Per-Job versus Per-Printer Subscription Objects 4460 Per-Job and Per-Printer Subscription Objects are quite similar. 4461 Either type of Subscription Object can subscribe to Job Events, 4462 Printer Events, or both. Both types of Subscription Objects can be 4463 queried using the Get-Subscriptions and Get-Subscription-Attributes 4464 operations and canceled using the Cancel-Subscription operation. 4465 Both types of Subscription Objects create Subscription Objects which 4466 have the same Subscription Object attributes defined. However, there 4467 are some semantic differences between Per-Job Subscription Objects 4468 and Per-Printer Subscription Objects. A Per-Job Subscription Object 4469 is established by the client when submitting a job and after creating 4470 the job using the Create-Job-Subscriptions operation by specifying 4471 the "job-id" of the Job with the "notify-job-id" attribute. A Per- 4472 Printer Subscription Object is established between a client and a 4473 Printer using the Create-Printer-Subscriptions operation. Some 4474 specific differences are: 4476 1.A client usually creates one or more Per-Job Subscription 4477 Objects as part of the Job Creation operations (Create-Job, 4478 Print-Job, and Print-URI), rather than using the OPTIONAL 4479 Create-Job-Subscriptions operation, especially since Printer 4480 implementations NEED NOT support the Create-Job-Subscriptions 4481 operation, since it is OPTIONAL. 4483 2.For Per-Job Subscription Objects, the Subscription Object is 4484 only valid while the job is "not-complete" (see sections 5.4.3) 4485 while for the Per-Printer Subscription Objects, the Subscription 4486 Object is valid until the time (in seconds) that the Printer 4487 returned in the "notify-lease-expiration-time" operation 4488 attribute. 4490 3.Job Events in a Per-Job Subscription Object apply only to "one 4491 job" (the Job created by the Job Creation operation or 4492 references by the Create-Job-Subscriptions operation) while Job 4493 Events in a Per-Printer Subscription Object apply to ALL jobs 4494 contained in the IPP Printer. 4496 G. Appendix - Description of the base IPP documents 4498 The base set of IPP documents includes: 4500 Design Goals for an Internet Printing Protocol [RFC2567] 4501 Rationale for the Structure and Model and Protocol for the Internet 4502 Printing Protocol [RFC2568] 4503 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 4504 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 4505 Internet Printing Protocol/1.1: Implementer's Guide [RFC3196] 4506 Mapping between LPD and IPP Protocols [RFC2569] 4508 The "Design Goals for an Internet Printing Protocol" document takes a 4509 broad look at distributed printing functionality, and it enumerates 4510 real-life scenarios that help to clarify the features that need to be 4511 included in a printing protocol for the Internet. It identifies 4512 requirements for three types of users: end users, operators, and 4513 administrators. It calls out a subset of end user requirements that 4514 are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator 4515 operations have been added to IPP/1.1 [RFC2911, RFC2910]. 4517 The "Rationale for the Structure and Model and Protocol for the 4518 Internet Printing Protocol" document describes IPP from a high level 4519 view, defines a roadmap for the various documents that form the suite 4520 of IPP specification documents, and gives background and rationale 4521 for the IETF IPP working group's major decisions. 4523 The "Internet Printing Protocol/1.1: Model and Semantics" document 4524 describes a simplified model with abstract objects, their attributes, 4525 and their operations. The model introduces a Printer and a Job. The 4526 Job supports multiple documents per Job. The model document also 4527 addresses how security, internationalization, and directory issues 4528 are addressed. 4530 The "Internet Printing Protocol/1.1: Encoding and Transport" document 4531 is a formal mapping of the abstract operations and attributes defined 4532 in the model document onto HTTP/1.1 [RFC2616]. It also defines the 4533 encoding rules for a new Internet MIME media type called 4534 "application/ipp". This document also defines the rules for 4535 transporting over HTTP a message body whose Content-Type is 4536 "application/ipp". This document defines the 'ipp' scheme for 4537 identifying IPP printers and jobs. 4539 The "Internet Printing Protocol/1.1: Implementer's Guide" document 4540 gives insight and advice to implementers of IPP clients and IPP 4541 objects. It is intended to help them understand IPP/1.1 and some of 4542 the considerations that may assist them in the design of their client 4543 and/or IPP object implementations. For example, a typical order of 4544 processing requests is given, including error checking. Motivation 4545 for some of the specification decisions is also included. 4547 The "Mapping between LPD and IPP Protocols" document gives some 4548 advice to implementers of gateways between IPP and LPD (Line Printer 4549 Daemon) implementations. 4551 H. Appendix - Full Copyright Statement 4553 Copyright (C) The Internet Society (1998,1999,2000,2001,2002). All 4554 Rights Reserved 4556 This document and translations of it may be copied and furnished to 4557 others, and derivative works that comment on or otherwise explain it 4558 or assist in its implementation may be prepared, copied, published 4559 and distributed, in whole or in part, without restriction of any 4560 kind, provided that the above copyright notice and this paragraph are 4561 included on all such copies and derivative works. However, this 4562 document itself may not be modified in any way, such as by removing 4563 the copyright notice or references to the Internet Society or other 4564 Internet organizations, except as needed for the purpose of 4565 developing Internet standards in which case the procedures for 4566 copyrights defined in the Internet Standards process must be 4567 followed, or as required to translate it into languages other than 4568 English. 4570 The limited permissions granted above are perpetual and will not be 4571 revoked by the Internet Society or its successors or assigns. 4573 This document and the information contained herein is provided on an 4574 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4575 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4576 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4577 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4578 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4580 Acknowledgement 4582 Funding for the RFC Editor function is currently provided by the 4583 Internet Society.