idnits 2.17.1 draft-ietf-ipp-not-spec-06.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 -- however, there's a paragraph with a matching beginning. Boilerplate error? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC2568], [RFC2569], [IPP-IIG], [RFC2910], [RFC2911], [RFC2567]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 5 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 19 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 1161 has weird spacing: '...ccepted a Job...' == Line 1496 has weird spacing: '...ipients do no...' == Line 3899 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. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If the client supplies an unsupported scheme in the value of this attribute, then the Printer MUST not create the Subscription Object and MUST return the "notify-status-code" attribute with the 'client-error-uri-scheme-not-supported' value in the Subscription Attributes Group in the response. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute, the Printer MUST not populate this attribute on the Subscription Object. There is no "notify-time-interval-default" attribute. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: successful-ok: the Printer created the Job and all Subscription Objects requested. successful-ok-ignored-subscriptions: the Printer created the Job and not all of the Subscription Objects requested. This status-code hides 'successful-ok-xxx' status-codes that could reveal problems in Job creation. The Printer MUST not return the 'client-error-ignored-all-subscriptions' status code for Job Creation operations because the Printer returns an error status-code only when it fails to create a Job. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The Printer MUST accept requests that are identical to the Job Creation request defined in section 11.1.3.1, except that the request MUST not contain document data. == 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 (January 24, 2000) is 8852 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) == Missing Reference: 'IPP-IIG' is mentioned on line 64, but not defined == Missing Reference: 'RFC1738' is mentioned on line 1007, but not defined ** Obsolete undefined reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) == Unused Reference: 'IANA-CON' is defined on line 3486, but no explicit reference was found in the text == Unused Reference: 'RFC2566' is defined on line 3514, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-iesg-iana-considerations-04 ** Obsolete normative reference: RFC 2566 (Obsoleted by RFC 2911) ** Downref: Normative reference to an Experimental RFC: RFC 2567 ** Downref: Normative reference to an Experimental RFC: RFC 2568 ** Downref: Normative reference to an Experimental RFC: RFC 2569 ** 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) Summary: 13 errors (**), 0 flaws (~~), 17 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT R. Herriot (editor) 3 Xerox Corporation 4 [Target Category: standards track] T. Hastings 5 Xerox Corporation 6 R. deBry 7 Utah Valley State College 8 S. Isaacson 9 Novell, Inc. 10 J. Martin 11 Underscore 12 M. Shepherd 13 Xerox Corporation 14 R. Bergman 15 Hitachi Koki Imaging Solutions 16 January 24, 2000 17 Internet Printing Protocol (IPP): 18 IPP Event Notification Specification 19 Copyright (C) The Internet Society (2001). All Rights Reserved. 21 Status of this Memo 23 This document is an Internet-Draft and is in full conformance with 24 all provisions of Section 10 of [RFC2026]. Internet-Drafts are 25 working documents of the Internet Engineering Task Force (IETF), its 26 areas, and its working groups. Note that other groups may also 27 distribute working documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress". 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 37 The list of Internet-Draft Shadow Directories can be accessed as 38 http://www.ietf.org/shadow.html. 40 Abstract 42 This document describes an extension to the IPP/1.0, IPP/1.1, and 43 future versions. This extension allows a client to subscribe to 44 printing related Events. Subscriptions are modeled as Subscription 45 Objects. The Subscription Object specifies that when one of the 46 specified Event occurs, the Printer sends an asynchronous Event 47 Notification to the specified Notification Recipient via the 48 specified Delivery Method (i.e., protocol). A client associates 49 Subscription Objects with a particular Job by performing the Create- 50 Job-Subscriptions operation or by submitting a Job with subscription 51 information. A client associates Subscription Objects with the 52 Printer by performing a Create-Printer-Subscriptions operation. Four 53 other operations are defined for Subscription Objects: Get- 54 Subscriptions-Attributes, Get-Subscriptions, Renew-Subscription, and 55 Cancel-Subscription. 57 The basic set of IPP documents includes: 59 Design Goals for an Internet Printing Protocol [RFC2567] 60 Rationale for the Structure and Model and Protocol for the Internet 61 Printing Protocol [RFC2568] 62 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 63 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 64 Internet Printing Protocol/1.1: Implementer's Guide [IPP-IIG] 65 Mapping between LPD and IPP Protocols [RFC2569] 67 The "Design Goals for an Internet Printing Protocol" document takes a 68 broad look at distributed printing functionality, and it enumerates 69 real-life scenarios that help to clarify the features that need to be 70 included in a printing protocol for the Internet. It identifies 71 requirements for three types of users: end users, Operators, and 72 Administrators. It calls out a subset of end user requirements that 73 are satisfied in IPP/1.0. Operator and Administrator requirements 74 are out of scope for version 1.0. A few OPTIONAL Operator operations 75 have been added to IPP/1.1. 77 The "Rationale for the Structure and Model and Protocol for the 78 Internet Printing Protocol" document describes IPP from a high level 79 view, defines a roadmap for the various documents that form the suite 80 of IPP specifications, and gives background and rationale for the 81 IETF working group's major decisions. 83 The "Internet Printing Protocol/1.1: Model and Semantics", describes 84 a simplified model with abstract objects, their attributes, and their 85 operations that are independent of encoding and transport. It 86 introduces a Printer object and a Job object. The Job object 87 optionally supports multiple documents per Job. It also addresses 88 security, internationalization, and directory issues. 90 The "Internet Printing Protocol/1.1: Encoding and Transport" document 91 is a formal mapping of the abstract operations and attributes defined 92 in the model document onto HTTP/1.1. It defines the encoding rules 93 for a new Internet MIME media type called "application/ipp". This 94 document also defines the rules for transporting over HTTP a message 95 body whose Content-Type is "application/ipp". This document defines 96 a new scheme named 'ipp' for identifying IPP printers and jobs. 97 Finally, this document defines interoperability rules for supporting 98 IPP/1.0 clients. 100 The "Internet Printing Protocol/1.1: Implementer's Guide" document 101 gives insight and advice to implementers of IPP clients and IPP 102 objects. It is intended to help them understand IPP/1.0 and some of 103 the considerations that may assist them in the design of their client 104 and/or IPP object implementations. For example, a typical order of 105 processing requests is given, including error checking. Motivation 106 for some of the specification decisions is also included. 108 The "Mapping between LPD and IPP Protocols" document gives some 109 advice to implementers of gateways between IPP and LPD (Line Printer 110 Daemon) implementations. 112 Table of Contents 114 1 Introduction....................................................9 115 1.1 Notification Overview........................................9 117 2 Models for Notification........................................12 118 2.1 Model for Notification (Simple Case)........................12 119 2.2 Model for Notification with Cascading Printers..............12 120 2.3 Distributed Model for Notification..........................12 121 2.4 Extended Notification Recipient.............................13 123 3 Terminology....................................................13 124 3.1 Conformance Terminology.....................................13 125 3.2 Other Terminology...........................................14 127 4 Object Relationships...........................................16 128 4.1 Printer and Per-Printer Subscription Objects................16 129 4.2 Printer, Job and Per-Job Subscription Objects...............16 131 5 Subscription Object............................................17 132 5.1 Rules for Support of Subscription Template Attributes.......17 133 5.2 Rules for Processing Subscription Template Attributes.......18 134 5.3 Subscription Template Attributes............................22 135 5.3.1 notify-recipient-uri (uri)..................................23 136 5.3.2 notify-events (1setOf type2 keyword)........................24 137 5.3.2.1 Standard Values for Subscribed Events ...................24 138 5.3.2.1.1 No Events.............................................25 139 5.3.2.1.2 Subscribed Printer Events.............................25 140 5.3.2.1.3 Subscribed Job Events.................................26 141 5.3.2.2 Rules for Matching of Subscribed Events .................28 142 5.3.2.2.1 Rules for Matching of Printer Events..................28 143 5.3.2.2.2 Rules for Matching of Job Events......................28 144 5.3.2.2.3 Special Cases for Matching Rules......................29 145 5.3.3 notify-attributes (1setOf type2 keyword)....................30 146 5.3.4 notify-user-data (octetString(63))..........................31 147 5.3.5 notify-charset (charset)....................................31 148 5.3.6 notify-natural-language (naturalLanguage)...................32 149 5.3.7 notify-lease-duration (integer(0:67108863)).................32 150 5.3.8 notify-time-interval (integer(0:MAX)).......................33 151 5.4 Subscription Description Attributes.........................35 152 5.4.1 notify-subscription-id (integer (1:MAX))...................35 153 5.4.2 notify-sequence-number (integer (0:MAX))....................36 154 5.4.3 notify-lease-expiration-time (integer(0:MAX))...............36 155 5.4.4 notify-printer-up-time (integer(1:MAX)).....................37 156 5.4.5 notify-printer-uri (uri)....................................37 157 5.4.6 notify-job-id (integer(1:MAX))..............................38 158 5.4.7 notify-subscriber-user-name (name(MAX)).....................38 160 6 Printer Description Attributes Related to Notification.........38 161 6.1 printer-state-change-time (integer(1:MAX))..................39 162 6.2 printer-state-change-date-time (dateTime)...................39 164 7 New Values for Existing Printer Description Attributes.........40 165 7.1 operations-supported (1setOf type2 enum)....................40 167 8 Attributes Only in Event Notifications.........................40 168 8.1 notify-subscribed-event (type2 keyword).....................40 169 8.2 notify-text (text(MAX)).....................................41 171 9 Event Notification Content.....................................41 172 9.1 Content of Machine Consumable Event Notifications...........43 173 9.1.1 Event Notification Content Common to All Events.............44 174 9.1.2 Additional Event Notification Content for Job Events........45 175 9.1.3 Additional Event Notification Content for Printer Events....46 176 9.2 Content of Human Consumable Event Notification..............46 177 9.2.1 Event Notification Content Common to All Events.............47 178 9.2.2 Additional Event Notification Content for Job Events........49 179 9.2.3 Additional Event Notification Content for Printer Events....50 181 10 Delivery Methods...............................................51 183 11 Operations for Notification....................................53 184 11.1 Subscription Creation Operations............................53 185 11.1.1 Create-Job-Subscriptions Operation .......................54 186 11.1.1.1 Create-Job-Subscriptions Request ........................54 187 11.1.1.2 Create-Job-Subscriptions Response .......................55 188 11.1.2 Create-Printer-Subscriptions operation ...................56 189 11.1.2.1 Create-Printer-Subscriptions Request ....................57 190 11.1.2.2 Create-Printer-Subscriptions Response ...................57 191 11.1.3 Job Creation Operation - Extensions for Notification .....57 192 11.1.3.1 Job Creation Request ....................................58 193 11.1.3.2 Job Creation Response ...................................58 194 11.2 Other Operations............................................59 195 11.2.1 Validate-Job Operation - Extensions for Notification .....59 196 11.2.2 Get-Printer-Attributes - Extensions for Notification .....60 197 11.2.3 Get-Subscription-Attributes operation ....................60 198 11.2.3.1 Get-Subscription-Attributes Request .....................61 199 11.2.3.2 Get-Subscription-Attributes Response ....................62 200 11.2.4 Get-Subscriptions operation ..............................63 201 11.2.4.1 Get-Subscriptions Request ...............................63 202 11.2.4.2 Get-Subscriptions Response ..............................64 203 11.2.5 Renew-Subscription operation .............................65 204 11.2.5.1 Renew-Subscription Request ..............................66 205 11.2.5.2 Renew-Subscription Response .............................66 206 11.2.6 Cancel-Subscription operation ............................67 207 11.2.6.1 Cancel-Subscription Request .............................68 208 11.2.6.2 Cancel-Subscription Response ............................69 210 12 Conformance Requirements.......................................69 211 13 IANA Considerations............................................70 212 13.1 Attribute Registrations.....................................70 213 13.2 Keyword Attribute Value Registrations.......................71 214 13.3 Operation Registrations.....................................71 215 13.4 Status code Registrations...................................72 216 13.5 Attribute Group tag Registrations...........................72 217 13.6 Format for Event Notification Delivery Method Registration 218 proposals.........................................................73 219 13.7 Format and Requirements for IPP Delivery Method Registration 220 Proposals.........................................................73 222 14 Internationalization Considerations............................73 224 15 Security Considerations........................................74 226 16 Status Codes...................................................74 227 16.1 successful-ok-ignored-subscriptions (0x0003)................75 228 16.2 client-error-ignored-all-subscriptions (0x0414).............75 230 17 Status Codes in Subscription Attributes Groups.................75 231 17.1 client-error-uri-scheme-not-supported (0x040C)..............75 232 17.2 client-error-too-many-subscriptions (0x0415)................76 233 17.3 successful-ok-too-many-events (0x0005)......................76 234 17.4 successful-ok-ignored-or-substituted-attributes (0x0001)....76 236 18 Encodings of Additional Attribute Tags.........................76 238 19 References.....................................................76 240 20 Author's Addresses.............................................78 242 A. Appendix - Model for Notification with Cascading Printers......79 244 B. Appendix - Distributed Model for Notification..................80 246 C. Appendix - Extended Notification Recipient.....................81 248 D. Appendix - Details about Conformance Terminology...............82 250 E. Appendix - Object Model for Notification.......................83 251 E.1 Appendix - Object relationships.............................84 252 E.2 Printer Object and Per-Printer Subscription Objects.........85 253 E.3 Job Object and Per-Job Subscription Objects.................85 255 F. Appendix - Per-Job versus Per-Printer Subscription Objects.....85 257 G. Appendix: Full Copyright Statement.............................86 259 Tables 260 Table 1 - Subscription Template Attributes........................23 261 Table 2 - Subscription Description Attributes.....................35 262 Table 3 - Printer Description Attributes Associated with Notification 263 ..............................................................39 264 Table 4 - Operation-id assignments................................40 265 Table 5 - Attributes in Event Notification Content................44 266 Table 6 - Additional Event Notification Content for Job Events....45 267 Table 7 - Combinations of Events and Subscribed Events for "job- 268 impressions-completed" ........................................46 269 Table 8 - Additional Event Notification Content for Printer Events46 270 Table 9 - Printer Name in Event Notification Content..............48 271 Table 10 - Event Name in Event Notification Content...............48 272 Table 11 - Event Time in Event Notification Content...............49 273 Table 12 - Job Name in Event Notification Content.................49 274 Table 13 - Job State in Event Notification Content................50 275 Table 14 - Printer State in Event Notification Content............51 276 Table 15 - Information about the Delivery Method..................52 277 Table 16 - Conformance Requirements for Operations................70 278 Figures 279 Figure 1 - Model for Notification.................................12 280 Figure 2 - Model for Notification with Cascading Printers.........80 281 Figure 3 - Opaque Use of a Notification Service Transparent to the 282 Client ........................................................81 283 Figure 4 - Use of an Extended Notification Recipient transparent to 284 the Printer ...................................................82 285 Figure 5 - Object Model for Notification..........................84 287 1 Introduction 289 This IPP notification specification is an extension to IPP/1.0 290 [RFC2568, RFC2569] and IPP/1.1 [RFC2911, RFC2910]. This document in 291 combination with the following documents is intended to meet the 292 notification requirements described in [ipp-not-req]: 294 Internet Printing Protocol (IPP): "Job Progress Attributes" 295 [ipp-prog] 296 One or more Delivery Method Documents registered with IANA (see 297 section 13). 299 Note: this document does not define any Delivery Methods, but it does 300 define the rules for conformance for Delivery Method Documents. 302 Refer to the Table of Contents for the layout of this document. 304 1.1 Notification Overview 306 This document defines operations that a client can perform in order 307 to create Subscription Objects in a Printer and carry out other 308 operations on them. A Subscription Object represents a Subscription 309 abstraction. The Subscription Object specifies that when one of the 310 specified Events occurs, the Printer sends an asynchronous Event 311 Notification to the specified Notification Recipient via the 312 specified Delivery Method (i.e., protocol). 314 When a client (called a Subscribing Client) performs an operation 315 that creates a Subscription Object, the operation contains one or 316 more Subscription Template Attributes Groups. Each such group holds 317 information used by the Printer to initialize a newly created 318 Subscription Object. The Printer creates one Subscription Object for 319 each Subscription Template Attributes Group in the operation. This 320 group is like the Job Template Attributes group defined in [RFC2911]. 321 The following is an example of the information included in a 322 Subscription Template Attributes Group (see section 5 for details on 323 the Subscription Object attributes): 325 1.The names of Subscribed Events that are of interest to the 326 Notification Recipient. 327 2.The address (URL) of one Notification Recipient. 328 3.The Delivery Method (i.e., the protocol) which the Printer uses 329 to send the Event Notification. 330 4.Some opaque data that the Printer sends to the Notification 331 Recipient in the Event Notification. The Notification Recipient 332 might use this opaque data as a forwarding address for the Event 333 Notification. 334 5.The charset to use in text fields within an Event Notification 335 6.The natural language to use in the text fields of the Event 336 Notification 338 7.The requested lease time in seconds for the Subscription Object 339 An operation that creates a Subscription Object is called a 340 Subscription Creation Operation. These operations include the 341 following operations (see section 11.1 for further details): 343 . Job Creation operation: When a client performs such an operation 344 (Print-Job, Print-URI, and Create-Job), a client can include 345 zero or more Subscription Template Attributes Groups in the 346 request. The Printer creates one Subscription Object for each 347 Subscription Template Attributes Group in the request, and the 348 Printer associates each such Subscription Object with the newly 349 created Job. This document extends these operations' definitions 350 in [RFC2911] by adding Subscription Template Attributes Groups 351 in the request and Subscription Attributes Groups in the 352 response. 354 . Create-Job-Subscriptions operation: A client can include one or 355 more Subscription Template Attributes Groups in the request. 356 The Printer creates one Subscription Object for each 357 Subscription Template Attributes Group and associates each with 358 the job that is the target of this operation. 360 . Create-Printer-Subscriptions operation: A client can include one 361 or more Subscription Template Attributes Groups in the request. 362 The Printer creates one Subscription Object for each 363 Subscription Template Attributes Group and associates each with 364 the Printer that is the target of this operation. 366 For each of the above operations: 368 . the Printer associates a Subscription Object with the Printer or 369 a specific Job. When a Subscription Object is associated with a 370 Job Object, it is called a Per-Job Subscription Object. When a 371 Subscription Object is associated with a Printer Object, it is 372 called a Per-Printer Subscription Object. 374 . the response contains one Subscription Attributes Group for each 375 Subscription Template Attributes Group in the request and in the 376 same order. When the Printer successfully creates a Subscription 377 Object, its corresponding Subscription Attributes Group contains 378 the "notify-subscription-id" attribute. This attribute uniquely 379 identifies the Subscription Object and is analogous to a "job- 380 id" for a Job object. Some operations described below use the 381 "notify-subscription-id" to identify the target Subscription 382 Object. 384 This document defines the following additional operations (see 385 section 11.2 for further details): 387 . Validate-Job operation: When a client performs this operation, a 388 client can include zero or more Subscription Template Attributes 389 Groups in the request. The Printer determines if it could 390 create one Subscription Object for each Subscription Template 391 Attributes Group in the request. This document extends this 392 operation's definition in [RFC2911] by adding Subscription 393 Template Attributes Groups in the request and Subscription 394 Attributes Groups in the response. 396 . Get-Subscription-Attributes operation: This operation allows a 397 client to obtain the specified attributes of a target 398 Subscription Object. 400 . Get-Subscriptions operation: This operation allows a client to 401 obtain the specified attributes of all Subscription Objects 402 associated with the Printer or a specified Job. 404 . Renew-Subscription operation: This operation renews the lease on 405 the target Per-Printer Subscription Object before it expires. A 406 newly created Per-Printer Subscription Object receives an 407 initial lease. It is the duty of the client to use this 408 operation frequently enough to preserve a Per-Printer 409 Subscription Object. The Printer deletes a Per-Printer 410 Subscription Object when its lease expires. A Per-Job 411 Subscription Object last exactly as long as its associated Job 412 Object and thus doesn't have a lease. 414 . Cancel-Subscription operation: This operation cancels the lease 415 on the specified Per-Printer Subscription Object and thereby 416 deletes the Subscription Object. 418 When an Event occurs, the Printer finds all Subscription Objects 419 listening for the Event (see section 9 for details on finding such 420 Subscription Objects). For each such Subscription Object, the 421 Printer: 423 a)generates an Event Notification with information specified in 424 section 9, AND 426 b)either: 428 i) delivers the Event Notification using the Delivery Method 429 and target address identified in the Subscription Object's 430 "notify-recipient-uri" attribute if the Delivery Method is a 431 "push", OR 433 ii) saves Event Notification for a time period defined by the 434 Delivery Method if the Delivery Method is a "pull", i.e., the 435 Notification Recipient is expected to fetch the Event 436 Notifications. 438 2 Models for Notification 440 2.1 Model for Notification (Simple Case) 442 As part of a Subscription Creation Operation, an IPP Printer (i.e., 443 located in an output device or a server) creates one or more 444 Subscription Objects. In a Subscription Creation Operation, the 445 client specifies the Notification Recipient to which the Printer is 446 to deliver Event Notifications. A Notification Recipient can be the 447 Subscribing Client or a third party. 449 Figure 1 shows the Notification model for a simple Client-Printer 450 relationship. 452 embedded printer: 453 output device or server 454 PDA, desktop, or server +---------------+ 455 +--------+ | ########### | 456 | client |-----Subscription ---------># Printer # | 457 +--------+ Creation Operation | # Object # | 458 +------------+ | #####|##### | 459 |Notification| +-------|-------+ 460 |Recipient |<----IPP Event Notifications----+ 461 +------------+ (Job and/or Printer Events) 463 Figure 1 - Model for Notification 465 2.2 Model for Notification with Cascading Printers 467 With this model, there is an intervening Print server between the 468 human user and the Printer in the output device. If the Printer in 469 the output device generates an Event, the system can be configured to 470 send Event Notification either 472 . directly to the Notification Recipient specified by the 473 Subscribing Client or 475 . via the Print Server to the Notification Recipient specified by 476 the Subscribing Client. 478 See Appendix A for more details. 480 2.3 Distributed Model for Notification 482 The preceding sections (2.1 and 2.2) assume that the Notification 483 software resides in the same device or Server box as the rest of the 484 Printer software. In many implementations, the assumption is correct. 485 However, the Notification model also permits a distributed 486 implementation. 488 For example, the software that supports both Subscription Creation 489 Operations and sending of Event Notifications could be on hardware 490 that is separate from the output device. To make this work, there 491 must be a symbiotic relationship between the output device software 492 and the remote Notification software. Without the remote Notification 493 software, the output device software is not a complete Printer. 495 The term "Printer" in this document includes the software on the 496 output device or server box as well as Notification software that is 497 local to or remote from the output device. 499 Appendix B describes this example in detail. 501 2.4 Extended Notification Recipient 503 The model allows for an extended Notification Recipient that is 504 itself a Notification service that forwards each Event Notification 505 to another recipient. The client contacts this Notification Recipient 506 to arrange for forwarding by means outside the scope of this 507 document. The Printer need not be aware that the Notification 508 Recipient forwards Event Notifications. 510 Appendix C describes this example in detail. 512 3 Terminology 514 This section defines terminology used throughout this document. Other 515 terminology is defined in [RFC2911]. 517 3.1 Conformance Terminology 519 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 520 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 521 conformance to this specification. These terms are defined in 522 [RFC2911 section 13.1 on conformance terminology, most of which is 523 taken from RFC 2119 [RFC2119]. See Appendix D for complete details. 525 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 526 the Printer implements a Delivery Method that REQUIRES the feature 528 READ-ONLY - an adjective used in an attribute definition to indicate 529 that an IPP Printer MUST NOT allow the attribute's value to be 530 modified with the Set-Job-Attributes or Set-Printer-Attributes 531 operations (see [ipp-set]). Note: there is no Set-Subscription 532 operation so this term is not used for Subscription object 533 attributes. 535 3.2 Other Terminology 537 Administrator - A human user who establishes policy for and 538 configures the print system. 540 Operator - A human user who carries out the policy established by the 541 Administrator and controls the day to day running of the print 542 system. 544 IPP Client (or client) - The software component (PDA, desktop, or 545 server) that performs an IPP operation directed at an IPP Printer 546 (located in a server or output device). 548 Job Creation operation - One of the operations that creates a Job 549 object: Print-Job, Print-URI and Create-Job. The Validate-Job 550 operation is not a Job Creation operation because no Job object is 551 created. Therefore, when a statement also applies to the 552 Validate-Job operation, it is mentioned explicitly. 554 Event - some occurrence (either expected or unexpected) within the 555 printing system of a change of state, condition, or configuration 556 of a Job or Printer object. An Event occurs only at one instant in 557 time and does not span the time the physical Event takes place. 558 For example, jam-occurred and jam-cleared are two distinct, 559 instantaneous Events, even though the jam may last for a while. 561 Job Event - an Event caused by some change in a particular job on the 562 Printer, e.g., job-completed. 564 Printer Event - an Event caused by some change in the Printer that is 565 not specific to a job, e.g., printer-state-changed. 567 Subscribed Event - an Event that the Subscribing Client expresses 568 interest in by making it a value of the "notify-events" attribute 569 on a Subscription Object. 571 Subscribed Job Event - a Subscribed Event that is a Job Event. 573 Subscribed Printer Event - a Subscribed Event that is a Printer 574 Event. 576 Event Notification - the information about an Event that the Printer 577 sends when an Event occurs. 579 Notification Recipient - the entity to which the Printer sends an 580 Event Notification. 582 Delivery Method - the mechanism by which the Printer delivers the 583 Event Notification, e.g., via email or via SNMP. 585 Delivery Method Document - a document, separate from this document, 586 that defines a Delivery Method. 588 Compound Event Notification - two or more Event Notifications that a 589 Printer sends together as a single entity. The Delivery Method 590 Document specifies whether the Delivery Method supports Compound 591 Event Notifications. 593 Subscription Object - An object containing a set of attributes that 594 indicate: the Notification Recipient, the Delivery Method, the 595 Subscribed Events that cause the Printer to send an Event 596 Notification, and the information to send in an Event 597 Notification. 599 Per-Job Subscription Object - A Subscription Object that is 600 associated with a single Job. The Create-Job-Subscriptions 601 operation and Job Creation operations create such an object. 603 Per-Printer Subscription Object - A Subscription Object that is 604 associated with the Printer as a whole. The Create-Printer- 605 Subscriptions operation creates such an object. 607 Subscribing Client - The client that creates the Subscription Object. 609 Subscription Creation Operation - An operation that creates a 610 Subscription Object: Job Creation operations, Create-Job- 611 Subscriptions operation, and Create-Printer-Subscriptions 612 operation. In the context of a Job Creation operation, a 613 Subscription Creation Operation is the part of the Job Creation 614 operation that creates a Subscription object. 616 Subscription Creation Request - The request portion of a 617 Subscription Creation Operation. 619 Subscription Template Attributes - Subscription Object attributes 620 that a client can supply in a Subscription Creation Operation and 621 associated Printer Object attributes that specify supported and 622 default values for the Subscription Object attributes. 624 Subscription Description Attributes - Subscription Object attributes 625 that a Printer supplies during a Subscription Creation Operation. 627 Subscription Template Attributes Group - The attributes group in a 628 request that contains Subscription Object attributes that are 629 Subscription Template Attributes. 631 Subscription Attributes Group - The attributes group in a response 632 that contains Subscription Object attributes. 634 Human Consumable Event Notification - localized text for human 635 consumption only. There is no standardized format and thus 636 programs should not try to parse this text. 638 Machine Consumable Event Notification - bytes for program 639 consumption. The bytes are formatted according to the Delivery 640 Method document. 642 Printer - the software that supports an output device or print server 643 (see IPP/1.1 [RFC2911] which uses the terms Printer and Printer 644 object interchangeably). This document extends the IPP/1.1 Printer 645 definition to include the software that implements Subscription 646 Creation Operations and the sending of Event Notifications, even 647 if the software for such a Printer would be distributed across a 648 network (see section 2.3). 650 Notification - when not in the phrases 'Event Notification' and 651 'Notification Recipient' - the concepts of this specification, 652 i.e., Events, Subscription Objects, and Event Notifications. 654 4 Object Relationships 656 This section defines the object relationships between the Printer, 657 Job, and Subscription Objects. It does not define the 658 implementation. For an illustration of these relationships, see 659 Appendix E. 661 4.1 Printer and Per-Printer Subscription Objects 663 1.A Printer object can be associated with zero or more Per-Printer 664 Subscription Objects. 666 2.Each Per-Printer Subscription Object is associated with exactly 667 one Printer object. 669 4.2 Printer, Job and Per-Job Subscription Objects 671 1.A Printer object is associated with zero or more Job objects. 673 2.Each Job object is associated with exactly one Printer object. 675 3.A Job object is associated with zero or more Per-Job Subscription 676 Objects. 678 4.Each Per-Job Subscription Object is associated with exactly one 679 Job object. 681 5 Subscription Object 683 A Subscribing Client creates a Subscription Object with a 684 Subscription Creation Operation in order to indicate its interest in 685 certain Events. See section 11 for a description of these operations. 686 When an Event occurs, the Subscription Object specifies to the 687 Printer where to send Event Notifications, how to send them and what 688 to put in them. See section 9 for details on the contents of an Event 689 Notification. 691 Using the IPP Job Template attributes as a model (see [RFC2911] 692 section 4.2), the attributes of a Subscription Object are divided 693 into two categories: Subscription Template Attributes and 694 Subscription Description Attributes. 696 Subscription Template attributes are, in turn, like the Job Template 697 attributes, divided into 699 1.Subscription Object attributes that a client can supply in a 700 Subscription Creation Request and 702 2.their associated Printer Object attributes that specify 703 supported and default values for the Subscription Object 704 attributes 706 The remainder of this section specifies general rules for 707 Subscription Template Attributes and describes each attribute in a 708 Subscription Object. 710 5.1 Rules for Support of Subscription Template Attributes 712 Subscription Template Attributes are fundamental to the Notification 713 model described in this specification. The client supplies these 714 attributes in Subscription Creation Operations and the Printer uses 715 these attributes to populate a newly created Subscription Object. 717 Subscription Objects attributes that are Subscription Template 718 Attributes conform to the following rules: 720 1.Each attribute's name starts with the prefix string "notify-" 721 and this document calls such attributes "notify-xxx". 723 2.For each "notify-xxx" Subscription Object attribute defined in 724 column 1 of Table 1 in section 5.3, Table 1 specifies 725 corresponding Printer attributes: "notify-xxx-default", "notify- 726 xxx-supported", "yyy-supported" and "notify-max-xxx-supported" 727 defined in column 2 of Table 1. Note "xxx" stands for the same 728 string in each case and "yyy" stands for some other string. 730 3.If a Printer supports "notify-xxx" in column 1 of Table 1, then 731 the Printer MUST support all associated attributes specified in 732 column 2 of Table 1. For example, Table 1 shows that if the 733 Printer supports "notify-events", it MUST support "notify- 734 events-default", "notify-events-supported" and "notify-max- 735 events-supported". 737 4.If a Printer does not support "notify-xxx" in column 1 of Table 738 1, then the Printer MUST NOT support any associated "notify-yyy" 739 attributes specified in column 2 of Table 1. For example, Table 740 1 shows that if the Printer doesn't support "notify-events", it 741 MUST NOT support "notify-events-default", "notify-events- 742 supported" and "notify-max-events-supported". Note this rule 743 does not apply to attributes whose names do not start with the 744 string "notify-" and are thus defined in another object and used 745 by other attributes. 747 5.Most "notify-xxx" attributes have a corresponding "yyy- 748 supported" attribute that specifies the supported values for 749 "notify-xxx". Column 2 of Table 1 specifies the name of each 750 "yyy-supported" attribute. The naming rules of IPP/1.1 (see 751 [RFC2911]) are used when "yyy-supported" is "notify-xxx- 752 supported". 754 6.Some "notify-xxx" attributes have a corresponding "notify-xxx- 755 default" attribute that specifies the value for "notify-xxx" if 756 the client does not supply it. Column 2 of Table 1 specifies the 757 name of each "notify-xxx-default" attribute. The naming rules of 758 IPP/1.1 (see [RFC2911]) are used. 760 If a client wishes to present an end user with a list of supported 761 values from which to choose, the client SHOULD query the Printer for 762 its supported value attributes. The client SHOULD also query the 763 default value attributes. If the client then limits selectable 764 values to only those values that are supported, the client can 765 guarantee that the values supplied by the client in the create 766 request all fall within the set of supported values at the Printer. 767 When querying the Printer, the client MAY enumerate each attribute by 768 name in the Get-Printer-Attributes Request, or the client MAY just 769 supply the 'subscription-template' group name in order to get the 770 complete set of supported attributes (both supported and default 771 attributes). 773 5.2 Rules for Processing Subscription Template Attributes 775 This section defines a detailed set of rules that a Printer follows 776 when it processes Subscription Template Attributes in a Subscription 777 Creation Request. These rules for are similar to the rules for 778 processing Operation attributes in [RFC2911]. That is, the Printer 779 may or may not support an attribute and a client may or may not 780 supply the attribute. Some combinations of these cases are OK. Others 781 return warnings or errors, and perhaps a list of unsupported 782 attributes. 784 A Printer MUST implement the following behavior for processing 785 Subscription Template Attributes in a Subscription Creation Request: 787 1.If a client supplies a "notify-xxx" attribute from column 1 of 788 Table 1 and the Printer supports it and its value, the Printer 789 MUST populate the attribute on the created Subscription Object. 791 2.If a client supplies a "notify-xxx" attribute from column 1 of 792 Table 1 and the Printer doesn't support it or its value, the 793 Printer MUST NOT populate the attribute on the created 794 Subscription Object with it. The Printer MUST do one of the 795 following: 797 a) If the value of the "notify-xxx" attribute is unsupported, the 798 Printer MUST return the attribute with its value in the 799 Subscription Attributes Group of the response. 801 b) If "notify-xxx" is an unsupported attribute, the Printer MUST 802 return the attribute in the Subscription Attributes Group of the 803 response with the 'unsupported' out-of-band value. 805 Note: The rules of this step are the same as for Unsupported 806 Attributes [RFC2911] section 3.1.7. except that the unsupported 807 attributes are returned in the Subscription Attributes Group 808 rather than the Unsupported Attributes Group because Subscription 809 Creation Operations can create more than one Subscription Object). 811 3.If a client is REQUIRED to supply a "notify-xxx" attribute from 812 column 1 of Table 1 and the Printer doesn't support the supplied 813 value, the Printer MUST NOT create a Subscription Object. The 814 rules for Unsupported Attributes in step #2 still apply. 816 4.If a client does not supply a "notify-xxx" attribute from column 1 817 of Table 1 and the attribute is REQUIRED for the client to supply, 818 the Printer MUST reject the Subscription Creation Operation 819 (including Job Creation operations) without creating a 820 Subscription Object, and MUST return in the response: 822 c) the status code 'client-error-bad-request' AND 824 d) no Subscription Attribute Groups. 826 5.If a client does not supply a "notify-xxx" attribute from column 1 827 of Table 1 that is OPTIONAL for the client to supply, and column 2 828 of Table 1 either: 830 a) specifies a "notify-xxx-default" attribute, the Printer MUST 831 behave as if the client had supplied the "notify-xxx-default" 832 attribute (see step #1) and populate the Subscription object 833 with the value of the "notify-xxx-default" attribute as part of 834 the Subscription Creation operation (unlike Job Template 835 attributes where the Printer does not populate the Job object 836 with defaults - see [RFC2911]) OR 838 b) does not specify a "notify-xxx-default" attribute, the Printer 839 MUST populate the "notify-xxx" attribute on the Subscription 840 Object according to the definition of the "notify-xxx" attribute 841 in a section 5.3. For some attributes, the "notify-xxx" is 842 populated with the value of some other attribute, and for 843 others, the "notify-xxx" is NOT populated on the Subscription 844 object at all. 846 6.A Printer MUST create a Subscription Object for each Subscription 847 Template Attributes group in a request unless the Printer: 849 a) encounters some attributes in a Subscription Template Attributes 850 Group that require the Printer not to create the Subscription 851 Object OR 853 b) would create a Per-Job Subscription Object when it doesn't have 854 space for another Per-Job Subscription Object OR 856 c) would create a Per-Printer Subscription Object when it doesn't 857 have space for another Per-Printer Subscription Object. 859 7.A response MUST contain one Subscription Attributes Group for each 860 Subscription Template Attributes Group in the request (and in the 861 same order) whether the Printer creates a Subscription Object from 862 the Subscription Template Attributes Group or not. However, the 863 attributes in each Subscription Attributes Group can be in any 864 order. 866 8.The Printer MUST populate each Subscription Attributes Group of 867 the response such that each contains: 869 a) the "notify-subscription-id" attribute (see section 0), if and 870 only if the Printer creates a Subscription Object. 872 b) the "notify-lease-duration" attribute (see section 5.3.7), if 873 and only if the Printer creates a Per-Printer Subscription 874 Object. The value of this attribute is the value of the 875 Subscription Object's "notify-lease-duration" attribute. This 876 value MAY be different from the client-supplied value (see 877 section 5.3.7). If a client supplies this attribute in the 878 creation of a Per-Job Subscription Object, it MUST appear in 879 this group with the out-of-band value 'unsupported' to indicate 880 that the Printer doesn't support it in this context. 882 c) all of the unsupported Subscription Template Attributes from 883 step #2. Note, they are not returned in the Unsupported 884 Attributes Group in order to separate the unsupported attributes 885 for each Subscription Object. 887 d) the "notify-status-code" attribute if the Printer does not 888 create the Subscription Object or if there are unsupported 889 attributes from step #2. The possible values of the "notify- 890 status-code" attribute are shown below (see section 17 for more 891 details). The Printer returns the first value in the list below 892 that describes the status. 894 'client-error-uri-scheme-not-supported': the Subscription 895 Object was not created because the scheme of the "notify- 896 recipient-uri" attribute is not supported. See section 17.1 897 for more details about this status code. See step #3 in 898 this section for the case that causes this error, and the 899 resulting step #6a) that causes the Printer not to create 900 the Subscription Object. 902 'client-error-too-many-subscriptions': the Subscription 903 Object was not created because the Printer has no space for 904 additional Subscription Objects. The client SHOULD try 905 again later. See section 17.2 for more details about this 906 status code. See steps #6b) and #6c) in this section for 907 the cases that causes this error. 909 'successful-ok-too-many-events': the Subscription Object 910 was created without the "notify-events" values included in 911 this Subscription Attributes Group because the "notify- 912 events" attribute contains too many values. See section 913 17.3 for more details about this status code. See step #2 914 in this section and section 5.3.2 for the cases that cause 915 this status code. 917 'successful-ok-ignored-or-substituted-attributes' : the 918 Subscription Object was created but some supplied 919 Subscription Template Attributes are unsupported. These 920 unsupported attributes are also in the Subscription 921 Attributes Group. See section 17.4 for more details about 922 this status code. See step #2 in this section for the cases 923 that cause this status code. 925 9.The Printer MUST validate all Subscription Template Attributes and 926 MUST return all unsupported attributes and values in the 927 corresponding Subscription Attributes Group of the response (see 928 step #2) unless it determines that it could not create additional 929 Subscription Objects because of condition #6b) or condition #6c). 930 Then, the Printer NEED NOT validate these additional Subscription 931 Template Attributes and the client MUST NOT expect to find 932 unsupported attributes from step #2 in such additional 933 Subscription Attribute Groups. 935 5.3 Subscription Template Attributes 937 This section contains the Subscription Template Attributes defined 938 for the Subscription and Printer objects. 940 Table 1 below shows the Subscription Template Attributes and has two 941 columns: 943 . Attribute in Subscription Object: the name and attribute syntax 944 of each Subscription Object Attribute that is a Subscription 945 Template Attribute 947 . Default and Supported Printer Attributes: the default attribute 948 and supported Printer attributes that are associated with the 949 attribute in column 1. 951 A Printer MUST support all attributes in Table 1 below except for 952 "notify-attributes" (and "notify-attributes-supported"). A client 953 MUST supply "notify-recipient-uri" and MAY omit any of the rest of 954 the attributes in column 1 of Table 1 in a Subscription Creation 955 Request. 957 Table 1 - Subscription Template Attributes 959 Attribute in Subscription Default and Supported Printer 960 Object Attributes 962 notify-recipient-uri (uri) notify-schemes-supported (1setOf 963 uriScheme) 965 notify-events (1setOf type2 notify-events-default (1setOf type2 966 keyword) keyword) 967 notify-events-supported (1setOf type2 968 keyword) 969 notify-max-events-supported 970 (integer(2:MAX)) 972 notify-attributes (1setOf notify-attributes-supported (1setOf 973 type2 keyword) type2 keyword) 975 notify-user-data 976 (octetString(63)) 978 notify-charset (charset) charset-supported (1setOf charset) 980 notify-natural-languages generated-natural-language-supported 981 (naturalLanguage) (1setOf naturalLanguage) 983 notify-lease-duration notify-lease-duration-default 984 (integer(0:MAX)) (integer(0:67108863)) 985 notify-lease-duration-supported 986 (1setOf (integer(0: 67108863) | 987 rangeOfInteger(0:67108863))) 989 notify-time-interval 990 (integer(0:MAX)) 992 5.3.1 notify-recipient-uri (uri) 994 This attribute's value is a URL, which is a special case of a URI. 995 Its value consists of a scheme and an address. The address specifies 996 the Notification Recipient and the scheme specifies the Delivery 997 Method for each Event Notification associated with this Subscription 998 Object. 1000 A Printer MUST support this attribute. 1002 A client MUST supply this attribute in Subscription Creation 1003 Operation. Thus there is no need for a default attribute. 1005 The "notify-schemes-supported (1setOf uriScheme)" attribute MUST 1006 specify the schemes supported for this attribute. Note: According to 1007 [RFC1738] the ":" terminates the scheme and so is not part of the 1008 scheme. Therefore, values of this attribute do not include the ":". 1010 If the client supplies an unsupported scheme in the value of this 1011 attribute, then the Printer MUST not create the Subscription Object 1012 and MUST return the "notify-status-code" attribute with the 'client- 1013 error-uri-scheme-not-supported' value in the Subscription Attributes 1014 Group in the response. 1016 The Printer MUST treat the address part of this attribute as opaque. 1018 5.3.2 notify-events (1setOf type2 keyword) 1020 This attribute contains a set of Subscribed Events. When an Event 1021 occurs and it "matches" a value of this attribute, the Printer sends 1022 an Event Notification using information in the Subscription Object. 1023 The details of "matching" are described subsection 5.3.2.2. 1025 A Printer MUST support this attribute. 1027 A client MAY supply this attribute in a Subscription Creation 1028 Operation. If the client does not supply this attribute in 1029 Subscription Creation Operation, the Printer MUST populate this 1030 attribute on the Subscription Object with its "notify-events-default" 1031 attribute value. 1033 Each value of this attribute on a Subscription Object MUST be one of 1034 the values of the "notify-events-supported (1setOf type2 keyword)" 1035 attribute. 1037 The number of values of this attribute MUST NOT exceed the value of 1038 the "notify-max-events-supported" attribute. A Printer MUST support 1039 at least 2 values per Subscription Object. If the number of values 1040 supplied by a client in a Subscription Creation Operation exceeds the 1041 value of this attribute, the Printer MUST treat extra values as 1042 unsupported values and MUST use the value of 'successful-ok-too-many- 1043 events' for the "notify-status-code" attribute in the Subscription 1044 Attributes Group of the response. 1046 5.3.2.1 Standard Values for Subscribed Events 1048 Each value of this attribute is a keyword and it specifies a 1049 Subscribed Event that represents certain changes. Some keywords 1050 represent a subset of changes of another keyword, e.g., 'job- 1051 completed' is an Event value which is a sub-value of 'job-state- 1052 change'. See section 5.3.2.2 for the case where this attribute 1053 contains both a value and a sub-value. 1055 The values in this section are divided into three categories: No 1056 Events, Job Events and Printer Events. 1058 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1059 support the Events indicated as "OPTIONAL". 1061 5.3.2.1.1 No Events 1063 The standard and only keyword value for No Events is: 1065 'none': REQUIRED - no Event Notifications for any Events. As the 1066 sole value of "notify-events-supported", this value means that the 1067 Printer does not support the sending of Event Notifications. As 1068 the sole value of "notify-events-default", this value means that a 1069 client MUST specify the "notify-events" attribute in order for a 1070 Subscription Creation Operation to succeed. If the Printer 1071 receives this value as the sole value of a Subscription Creation 1072 Operation, it does not create a Subscription Object. If a Printer 1073 receives this value with other values of a Subscription Creation 1074 Operation, the Printer MUST treat this value as an unsupported 1075 value. 1077 5.3.2.1.2 Subscribed Printer Events 1079 The standard keyword values for Subscribed Printer Events are: 1081 'printer-state-changed': REQUIRED - the Printer changed state from 1082 any state to any other state. Specifically, the value of the 1083 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1084 accepting-jobs" attributes changed. 1086 This Subscribed Event value has the following sub-values: 1087 'printer-restarted' and 'printer-shutdown'. A client can listen 1088 for any of these sub-values if it doesn't want to listen to all 1089 printer-state changes: 1091 'printer-restarted': OPTIONAL - when the printer is powered 1092 up . 1094 'printer-shutdown': OPTIONAL - when the device is being 1095 powered down . 1097 'printer-stopped: REQUIRED - when the printer stops printing, 1098 i.e. the value of the "printer-state" Printer attribute 1099 becomes 'stopped'. 1101 'printer-config-changed': OPTIONAL - when the configuration of a 1102 Printer has changed, i.e., the value of the "printer-message-from- 1103 operator" or any "configuration" Printer attribute has changed. A 1104 "configuration" Printer attribute is an attribute which can change 1105 value because of some human interaction either direct or indirect, 1106 and which is not covered by one of the other Events in this 1107 section. Examples of "configuration" Printer attributes are any of 1108 the Job Template attributes, such as "xxx-supported", "xxx-ready" 1109 and "xxx-default". Often, such a change is the result of a client 1110 performing a Set-Printer-Attributes operation (see [ipp-set]) on 1111 the Printer. The client has to perform a Get-Printer-Attributes to 1112 find out the new values of these changed attributes. This Event 1113 is useful for GUI clients and drivers to update the available 1114 printer capabilities to the user. 1116 This Event value has the following sub-values: 'printer-media- 1117 changed' and 'printer-finishings-changed'. A client can listen for 1118 any of these sub-values if it doesn't want to listen to all 1119 printer-configuration changes: 1121 'printer-media-changed': OPTIONAL - when the media loaded on 1122 a printer has been changed, i.e., the "media-ready" 1123 attribute has changed. This Event includes two cases: an 1124 input tray that goes empty and an input tray that receives 1125 additional media of the same type or of a different type. 1126 The client must check the "media-ready" Printer attribute 1127 (see [RFC2911] section 4.2.11) separately to find out what 1128 changed. 1130 'printer-finishings-changed': OPTIONAL - when the finisher on 1131 a printer has been changed, i.e., the "finishings-ready" 1132 attribute has changed. This Event includes two cases: a 1133 finisher that goes empty and a finisher that is refilled 1134 (even if it is not full). The client must check the 1135 "finishings-ready" Printer attribute separately to find out 1136 what changed. 1138 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1139 Printer's queue has changed, so that an application that is 1140 monitoring the queue can perform a Get-Jobs operation to determine 1141 the new order. This Event does not include when a job enters the 1142 queue (the 'job-created' Event covers that) and does not include 1143 when a job leaves the queue (the 'job-completed' Event covers 1144 that). 1146 5.3.2.1.3 Subscribed Job Events 1148 The standard keyword values for Subscribed Job Events are: 1150 'job-state-changed': REQUIRED - the job has changed from any state 1151 to any other state. Specifically, the Printer sends this Event 1152 whenever the value of the "job-state" attribute or "job-state- 1153 reasons" attribute changes. When a Job is removed from the Job 1154 History (see [RFC2911] 4.3.7.1), no Event is generated. 1156 This Event value has the following sub-values: 'job-created', 1157 'job-completed' and 'job-stopped'. A client can listen for any of 1158 these sub-values if it doesn't want to listen to all 'job-state 1159 changes'. 1161 'job-created': REQUIRED - the Printer has accepted a Job 1162 Creation operation and the job's "time-at-creation" 1163 attribute value is set (see [RFC2911] section 4.3.14.1). 1164 The Printer puts the job in the 'pending', 'pending-held' 1165 or 'processing' states.. 1167 'job-completed': REQUIRED - the job has reached one of the 1168 completed states, i.e., the value of the job's "job-state" 1169 attribute has changed to: 'completed', 'aborted', or 1170 'canceled'. The Job's "time-at-completed" and "date-time- 1171 at-completed" (if supported) attributes are set (see 1172 [RFC2911] section 4.3.14).. The Printer also sends this 1173 Event when a Job is removed with the Purge-Job operation. 1174 In this case, the Event Notification MUST report the 'job- 1175 state' as 'canceled'. 1177 'job-stopped: OPTIONAL - when the job stops printing, i.e. 1178 the value of the "job-state" Job attribute becomes 1179 'processing-stopped'. 1181 'job-config-changed': OPTIONAL - when the configuration of a job has 1182 changed, i.e., the value of the "job-message-from-operator" or any 1183 of the "configuration" Job attributes have changed. A 1184 "configuration" Job attribute is an attribute that can change 1185 value because of some human interaction either direct or indirect. 1186 Examples of "configuration" Job attributes are any of the job 1187 template attributes and the "job-name" attribute. Often, such a 1188 change is the result of the user or the Operator performing a Set- 1189 Job-Attributes operation (see [ipp-set]) on the Job object. The 1190 client performs a Get-Job-Attributes to find out the new values of 1191 the changed attributes. This Event is useful for GUI clients and 1192 drivers to update the job information to the user. 1194 'job-progress': OPTIONAL - when the Printer has completed Printing a 1195 sheet. See the separate [ipp-prog] specification for additional 1196 attributes that a Printer MAY send in an Event Notification caused 1197 by this Event. The "notify-time-interval" attribute affects this 1198 Event by causing the Printer NOT to send an Event Notification 1199 every time a 'job-progress' Events occurs. See section 5.3.8 for 1200 full details. 1202 5.3.2.2 Rules for Matching of Subscribed Events 1204 When an Event occurs, the Printer MUST find each Subscription object 1205 whose "notify-events" attribute "matches" the Event. The rules for 1206 "matching" of Subscribed Events are described separately for Printer 1207 Events and for Job Events. This section also describes some special 1208 cases. 1210 5.3.2.2.1 Rules for Matching of Printer Events 1212 Suppose that the Printer causes Printer Event E to occur. For each 1213 Per-Job or Per-Printer Subscription S in the Printer, if E equals a 1214 value of this attribute in S or E is a sub-value of a value of this 1215 attribute in S, the Printer MUST generate an Event Notification. 1217 Consider the example. There are three Subscription Objects each with 1218 the Subscribed Printer Event 'printer-state-changed'. Subscription 1219 Object A is a Per-Printer Subscription Object. Subscription Object B 1220 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1221 is a Per-Job Subscription Object for Job 2. When the Printer enters 1222 the 'stopped' state, the Printer sends an Event Notification to the 1223 Notification Recipients of Subscription Objects A, B, and C because 1224 this is a Printer Event. Note if Job 1 has already completed, the 1225 Printer would not send an Event Notification for its Subscription 1226 Object. 1228 5.3.2.2.2 Rules for Matching of Job Events 1230 Suppose that Job J causes Job Event E to occur. 1232 1.For each Per-Printer Subscription S in the Printer, if E equals 1233 a value of this attribute in S or E is a sub-value of a value of 1234 this attribute in S, the Printer MUST generate an Event 1235 Notification. 1237 2.For each Per-Job Subscription S associated with Job J, if E 1238 equals a value of this attribute in S or E is a sub-value of a 1239 value of this attribute in S, the Printer MUST generate an Event 1240 Notification. 1242 3.For each Per-Job Subscription S that is NOT associated Job J, if 1243 E equals a value of this attribute in S or E is a sub-value of a 1244 value of this attribute in, the Printer MUST NOT generate an 1245 Event Notification from S. 1247 Consider the example: There are three Subscription Objects listening 1248 for the Job Event 'job-completed'. Subscription Object A is a Per- 1249 Printer Subscription Object. Subscription Object B is a Per-Job 1250 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1251 Subscription Object for Job 2. In addition, Per-Printer Subscription 1252 Object D is listening for the Job Event 'job-state-changed'. When Job 1253 1 completes, the Printer sends an Event Notification to the 1254 Notification Recipient of Subscription Object A (because it is Per- 1255 Printer) and Subscription Object B because it is a Per-Job 1256 Subscription Object associated with the Job generating the Event. 1257 The Printer also sends an Event Notification to the Notification 1258 Recipient of Subscription Object D because 'job-completed' is a sub- 1259 value of 'job-state-changed' - the value that Subscription Object D 1260 is listening for. The Printer does not send an Event Notification to 1261 the Notification Recipients of Subscription Object C because it is a 1262 Per-Job Subscription Object associated with some Job other than the 1263 Job generating the Event. 1265 5.3.2.2.3 Special Cases for Matching Rules 1267 This section contains rule for special cases. 1269 If an Event matches Subscribed Events in two different Subscription 1270 Objects and the Printer would send two identical Event Notifications 1271 (except for the "notify-subscription-id" attribute) to the same 1272 Notification Recipient using the same Delivery Method, the Printer 1273 MUST send both Event Notifications. That is, the Printer MUST NOT try 1274 to consolidate seemingly identical Event Notifications that occur in 1275 separate Subscription objects. Incidentally, the Printer MUST NOT 1276 reject Subscription Creation Operations that would create this 1277 scenario. 1279 If an Event matches two values of this "notify-events" attribute in a 1280 single Subscription object (e.g., a value and its sub-value), a 1281 Printer MAY send one Event Notification for each matched value in the 1282 Subscription Object or it MAY send only one Event Notification per 1283 Subscription Object. The rules in sections 5.3.2.2.1 and 5.3.2.2.2 1284 are purposefully ambiguous about the number of Event Notification 1285 sent when Event E matches two or more values in a Subscription 1286 Object. 1288 Consider the example: There are two Per-Printer Subscription Objects 1289 when a Job completes. Subscription Object A has the Subscribed Job 1290 Event 'job-state-changed'. Subscription Object B has the Subscribed 1291 Job Events 'job-state-changed' and 'job-completed'. The Printer sends 1292 an Event Notification to the Notification Recipient of Subscription 1293 Object A with the value of 'job-state-changed' for the "notify- 1294 subscribing-event" attribute. The Printer sends either one or two 1295 Event Notifications to the Notification Recipient of Subscription 1296 Object B, depending on implementation. If it sends two Event 1297 Notifications, one has the value of 'job-state-changed' for the 1298 "notify-subscribing-event" attribute, and the other has the value of 1299 'job-completed' for the "notify-subscribing-event" attribute. If it 1300 sends one Event Notification, it has the value of either 'job-state- 1301 changed' or 'job-completed' for the "notify-subscribing-event" 1302 attribute, depending on implementation. The algorithm for choosing 1303 such a value is implementation dependent. 1305 5.3.3 notify-attributes (1setOf type2 keyword) 1307 This attribute contains a set of attribute names. When a Printer 1308 sends a Machine Consumable Event Notification, it includes a fixed 1309 set of attributes (see section 9.1). If this attribute is present and 1310 the Event Notification is Machine Consumable, the Printer also 1311 includes the attributes specified by this attribute. 1313 A Printer MAY support this attribute. 1315 A client MAY supply this attribute in a Subscription Creation 1316 Operation. If the client does not supply this attribute in 1317 Subscription Creation Operation or the Printer does not support this 1318 attribute, the Subscription Object MUST NOT contain the "notify- 1319 attributes" attribute. There is no "notify-attributes-default" 1320 attribute. 1322 Each keyword value of this attribute on a Subscription Object MUST be 1323 a value of the "notify-attributes-supported (1setOf type2 keyword)" 1324 attribute. The "notify-attributes-supported" MAY contain any Printer 1325 attribute, Job attribute or Subscription Object attribute that the 1326 Printer supports in an Event Notification. It MUST NOT contain any 1327 of the attributes in Section 9.1 that a Printer automatically puts in 1328 an Event Notification; it would be redundant. If a client supplies an 1329 attribute in Section 9.1, the Printer MUST treat it as an unsupported 1330 attribute value of the "notify-attributes" attribute. 1332 The following rules apply to each keyword value N of the "notify- 1333 attributes" attribute: If the value N names: 1335 a)a Subscription attribute, the Printer MUST use the attribute N in 1336 the Subscription Object that is being used to generate the Event 1337 Notification. 1339 b)a Job attribute and the Printer is generating an Event 1340 Notification from a Per-Job Subscription Object S, the Printer 1341 MUST use the attribute N in the Job object associated with S. 1343 c)a Job attribute and the Printer is generating an Event 1344 Notification from a Per-Printer Subscription Object and the Event 1345 is: 1347 . a Job Event, the Printer MUST use the attribute N in the Job 1348 object that caused the Event. 1350 . a Printer Event, the Printer MUST use the attribute N in the 1351 active Job. 1353 If a Printer supports this attribute and a Subscription Object 1354 contains this attribute and the Delivery Method generates a Machine 1355 Consumable Event Notification, the Printer MUST include in each Event 1356 Notification: 1358 a)the attributes specified in section 9.1 and 1360 b)each attribute named by this attribute. 1362 The Printer MUST NOT use this attribute to generate a Human 1363 Consumable Event Notification. 1365 5.3.4 notify-user-data (octetString(63)) 1367 This attribute contains opaque data that some Delivery Methods 1368 include in each Machine Consumable Event Notification. The opaque 1369 data might contain, for example: 1371 . the identity of the Subscriber 1373 . a path or index to some Subscriber information 1375 . a key that identifies to the Notification Recipient the ultimate 1376 recipient of the Event Notification 1378 . the id for a Notification Recipient that had previously 1379 registered with an Instant Messaging Service 1381 A Printer MUST support this attribute. 1383 A client MAY supply this attribute in a Subscription Creation 1384 Operation. If the client does not supply this attribute in 1385 Subscription Creation Operation, the Subscription Object MUST NOT 1386 contain the "notify-user-data" attribute. There is no "notify-user- 1387 data-default" attribute. 1389 There is no "user-data-supported" attribute. Rather, any octetString 1390 whose length does not exceed 63 octets is a supported value. If the 1391 length exceeds 63 octets, the Printer MUST treat it as an unsupported 1392 value. 1394 5.3.5 notify-charset (charset) 1396 This attribute specifies the charset to be used in the Event 1397 Notification content sent to the Notification Recipient, whether the 1398 Event Notification content is Machine Consumable or Human Consumable. 1400 A Printer MUST support this attribute. 1402 A client MAY supply this attribute in a Subscription Creation 1403 Operation. If the client does not supply this attribute in 1404 Subscription Creation Operation or supplies an unsupported value, the 1405 Printer MUST populate this attribute in the Subscription Object with 1406 the value of the "attributes-charset" operation attribute, which is a 1407 REQUIRED attribute in all IPP requests (see [RFC2911]). If the value 1408 of the "attributes-charset" attribute is unsupported, the Printer 1409 MUST populate this attribute in the Subscription Object with the 1410 value of the Printer's "charset-configured" attribute. There is no 1411 "notify-charset-default" attribute. 1413 The value of this attribute on a Subscription Object MUST be a value 1414 of the "charset-supported (1setOf charset)" attribute. 1416 5.3.6 notify-natural-language (naturalLanguage) 1418 This attribute specifies the natural language to be used in any human 1419 consumable text in the Event Notification content sent to the 1420 Notification Recipient, whether the Event Notification content is 1421 Machine Consumable or Human Consumable. 1423 A Printer MUST support this attribute. 1425 A client MAY supply this attribute in a Subscription Creation 1426 Operation. If the client does not supply this attribute in 1427 Subscription Creation Operation or supplies an unsupported value, the 1428 Printer MUST populate this attribute in the Subscription Object with 1429 the value of the "attributes-natural-language" operation attribute, 1430 which is a REQUIRED attribute in all IPP requests (see [RFC2911]). If 1431 the value of the "attributes-natural-language" attribute is 1432 unsupported, the Printer MUST populate this attribute in the 1433 Subscription Object with the value of the Printer's "natural- 1434 language-configured" attribute. There is no "notify-natural-language- 1435 default" attribute. 1437 The value of this attribute on a Subscription Object MUST be a value 1438 of the "generated-natural-language-supported (1setOf type2 1439 naturalLanguage)" attribute. 1441 5.3.7 notify-lease-duration (integer(0:67108863)) 1443 This attribute specifies the duration of the lease (in seconds) 1444 associated with the Per-Printer Subscription Object at the time the 1445 Subscription Object was created or the lease was renewed. The 1446 duration of the lease is infinite if the value is 0, i.e., the lease 1447 never expires. 1449 This attribute is not present on a Per-Job Subscription Object 1450 because the Subscription Object lasts exactly as long as the 1451 associated Job object. See section 5.4.3 on "notify-lease-expiration- 1452 time (integer(0:MAX))" for more details. 1454 A Printer MUST support this attribute. 1456 For a Subscription Object Creation operation of a Per-Job 1457 Subscription Object, the client MUST NOT supply this attribute. If 1458 the client does supply this attribute, the Printer MUST treat it as 1459 an unsupported attribute. 1461 For a Subscription Creation Operation of a Per-Printer Subscription 1462 Object or a Renew-Subscription operation, a client MAY supply this 1463 attribute. If the client does not supply this attribute, the Printer 1464 MUST populate this attribute with its "notify-lease-duration-default" 1465 (0:67108863) attribute value. If the client supplies this attribute 1466 with an unsupported value, the Printer MUST populate this attribute 1467 with a supported value, and this value SHOULD be as close as possible 1468 to the value requested by the client. Note: this rule implies that a 1469 Printer doesn't assign the value of 0 (infinite) unless the client 1470 requests it. 1472 After the Printer has populated this attribute with a supported 1473 value, the value represents the "granted duration" of the lease in 1474 seconds and the Printer sets the value of the Subscription Object's 1475 "notify-lease-expiration-time" attribute as specified in section 1476 5.4.3. 1478 The value of this attribute on a Subscription Object MUST be a value 1479 of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) 1480 | rangeOfInteger(0:67108863))) attribute. 1482 A Printer MAY require authentication in order to return the value of 1483 0 (the lease never expires) as one of the values of "notify-lease- 1484 duration-supported", and to allow 0 as a value of the "notify-lease- 1485 duration" attribute. 1487 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1488 1 and is about 2 years in seconds. The value is considerably less 1489 than MAX so that there is virtually no chance of an overflow when it 1490 is added to "printer-up-time" to produce "notify-lease-expiration- 1491 time". 1493 5.3.8 notify-time-interval (integer(0:MAX)) 1495 The 'job-progress' Event occurs each time that a Printer completes a 1496 sheet. Some Notification Recipients do not want to receive an Event 1497 Notification every time this Event occurs. This attribute allows a 1498 Subscribing Client to request how often it wants to receive Event 1499 Notifications for 'job-progress' Events. The value of this attribute 1500 MAY be any nonnegative integer (0,MAX) indicating the minimum number 1501 of seconds between 'job-progress' Event Notifications. 1503 The Printer MUST support this attribute if and only if the Printer 1504 supports the 'job-progress' Event. 1506 A client MAY supply this attribute in a Subscription Creation 1507 Operation. If the client does not supply this attribute, the Printer 1508 MUST not populate this attribute on the Subscription Object. There is 1509 no "notify-time-interval-default" attribute. 1511 There is no "notify-time-interval-supported" attribute. 1513 If the 'job-progress' Event occurs and a Subscription Object contains 1514 the 'job-progress' Event as a value of the 'notify-events' attribute, 1515 there are two cases to consider: 1517 1.This attribute is not present on the Subscription Object or has 1518 the value of 0. The Printer MUST generate and send an Event 1519 Notification (as is the case with other Events). 1521 2.This attribute is present with a nonzero value of N: 1523 a)If the Printer has not sent an Event Notification for the 'job- 1524 progress' Event for the associated Subscription Object within 1525 the past N seconds, the Printer MUST send an Event Notification 1526 for the Event that just occurred. Note when the Printer 1527 completes the first page of a Job, this rule implies that the 1528 Printer sends an Event Notification for a Per-Job Subscription 1529 Objects. 1531 b)Otherwise, the Printer MUST NOT generate or send an Event 1532 Notification for the associated Subscription Object. The Printer 1533 MUST NOT increase the value of the "notify-sequence-number" 1534 Subscription Object attribute (i.e., the sequence of values of 1535 the "notify-sequence-number" attribute counts the Event 1536 Notifications that the Printer sent and not the Events that do 1537 not cause an Event Notification to be sent). 1539 It is RECOMMENDED that a Subscribing Client use this attribute when 1540 it subscribes to the 'job-progress' Event, and that the value be 1541 sufficiently large to limit the frequency with which the Printer 1542 sends Event Notifications requests. 1544 This attribute MUST NOT effect any Events other than 'job-progress'. 1546 5.4 Subscription Description Attributes 1548 Subscription Description Attributes are those attributes that a 1549 Printer adds to a Subscription Object at the time of its creation. 1551 A Printer MUST support all attributes in this Table 2. 1553 A client MUST NOT supply the attributes in Table 2 in a Subscription 1554 Template Attributes Group of a Subscription Creation Operation. If 1555 the client supplies them, the Printer MUST NOT set them and MUST 1556 treat them as unsupported attributes. There are no corresponding 1557 default or supported attributes. 1559 Table 2 - Subscription Description Attributes 1561 Subscription Object attributes: 1563 notify-subscription-id (integer(1:MAX)) 1565 notify-sequence-number (integer(0:MAX)) 1567 notify-lease-expiration-time (integer(0:MAX)) 1569 notify-printer-up-time (integer(1:MAX)) 1571 notify-printer-uri (uri) 1573 notify-job-id (integer(1:MAX)) 1575 notify-subscriber-user-name (name(MAX)) 1577 5.4.1 notify-subscription-id (integer (1:MAX)) 1579 This attribute identifies a Subscription Object instance with a 1580 number that is unique within the context of the Printer. The Printer 1581 generates this value at the time it creates the Subscription Object. 1583 A Printer MUST support this attribute. 1585 The Printer SHOULD NOT assign the value of this attribute 1586 sequentially as it creates Subscription Objects. Sequential 1587 assignment makes it easy for rogue clients to guess the value of this 1588 attribute on other Subscription Objects. 1590 The Printer SHOULD avoid re-using recent values of this attribute 1591 during continuous operation of the Printer as well as across power 1592 cycles. Then a Subscribing Client is unlikely to find that a stale 1593 reference accesses a new Subscription Object. 1595 The 0 value is not permitted in order to allow for compatibility with 1596 "job-id" and with SNMP index values, which also cannot be 0. 1598 5.4.2 notify-sequence-number (integer (0:MAX)) 1600 The value of this attribute indicates the number of times that the 1601 Printer has generated and attempted to send an Event Notification. 1602 When an Event Notification contains this attribute, the Notification 1603 Recipient can determine whether it missed some Event Notifications 1604 (i.e., numbers skipped) or received duplicates (i.e., same number 1605 twice). 1607 A Printer MUST support this attribute. 1609 When the Printer creates a Subscription Object, it MUST set the value 1610 of this attribute to 0. This value indicates that the Printer has not 1611 sent any Event Notifications for this Subscription Object. 1613 Each time the Printer sends a newly generated Event Notification, it 1614 MUST increase the value of this attribute by 1. For some Delivery 1615 Methods, the Printer MUST include this attribute in each Event 1616 Notification, and the value MUST be the value after it is increased 1617 by 1. That is, the value of this attribute in the first Event 1618 Notification after Subscription object creation MUST be 1, the second 1619 MUST be 2, etc. If a Delivery Method is defined such that the 1620 Notification Recipient returns a response, the Printer can re-try 1621 sending an Event Notification a certain number of times with the same 1622 sequence number when the Notification Recipient fails to return a 1623 response. 1625 If a Subscription Object lasts long enough to reach the value of MAX, 1626 its next value MUST be 0, i.e., it wraps. 1628 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1630 This attribute specifies the time in the future when the lease on the 1631 Per-Printer Subscription Object will expire, i.e. the "printer-up- 1632 time" value at which the lease will expire. If the value is 0, the 1633 lease never expires. 1635 A Printer MUST support this attribute. 1637 When the Printer creates a Per-Job Subscription Object, this 1638 attribute MUST NOT be present - the Subscription Object lasts exactly 1639 as long as the associated Job object. 1641 When the Printer creates a Per-Printer Subscription Object, it 1642 populates this attribute with a value that is the sum of the values 1643 of the Printer's "printer-up-time" attribute and the Subscription 1644 Object's "notify-lease-duration" attribute with the following 1645 exception. If the value of the Subscription Object's "notify-lease- 1646 duration" attribute is 0 (i.e., no expiration time), then the value 1647 of this attribute MUST be set to 0 (i.e., no expiration time). 1649 When the Printer powers up, it MUST set the value of this attribute 1650 in each persistent Subscription Object using the algorithm in the 1651 previous paragraph. 1653 When the "printer-up-time" equals the value of this attribute, the 1654 Printer MUST delete the Subscription Object. A client can extend a 1655 lease of a Per-Printer Subscription Object with the Renew- 1656 Subscription operation (see section 11.2.5). 1658 Note: In order to compute the number of seconds remaining in a lease 1659 for a Per-Printer Subscription Object, a client can subtract the 1660 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1661 from the Subscription's "notify-lease-expiration-time" attribute. 1663 5.4.4 notify-printer-up-time (integer(1:MAX)) 1665 This attribute is an alias for the Printer's "printer-up-time" 1666 attribute " (see [RFC2911] section 4.4.29). 1668 A Printer MUST support this attribute. 1670 When the Printer creates a Per-Job Subscription Object, this 1671 attribute MUST NOT be present. When the Printer creates a Per-Printer 1672 Subscription Object, this attribute MUST be present. 1674 Note: this attribute exists in a Per-Printer Subscription Object so 1675 that a client using the Get-Subscription-Attributes or Get- 1676 Subscription operations can convert the Per-Printer Subscription's 1677 "notify-lease-expiration-time" attribute to wall clock time with one 1678 request. If the value of the "notify-lease-expiration-time" attribute 1679 is not 0 (i.e., no expiration time), then the difference between the 1680 "notify-lease-expiration-time" attribute and the "notify-printer-up- 1681 time" is the remaining number of seconds on the lease from the 1682 current time. 1684 5.4.5 notify-printer-uri (uri) 1686 This attribute identifies the Printer object that created this 1687 Subscription Object. 1689 A Printer MUST support this attribute. 1691 During a Subscription Creation Operation, the Printer MUST populate 1692 this attribute with the value of the "printer-uri" operation 1693 attribute in the request. From the Printer URI, the client can, for 1694 example, determine what security scheme was used. 1696 5.4.6 notify-job-id (integer(1:MAX)) 1698 This attribute specifies whether the containing Subscription Object 1699 is a Per-Job or Per-Printer Subscription Object, and for Per-Job 1700 Subscription Objects, it specifies the associated Job. 1702 A Printer MUST support this attribute. 1704 If this attribute is not present, the Subscription Object MUST be a 1705 Per-Printer Subscription. If this attribute is present, the 1706 Subscription Object MUST be a Per-Job Subscription Object and this 1707 attribute MUST identify the Job with which the Subscription Object is 1708 associated. 1710 Note: This attribute could be useful to a Notification Recipient that 1711 receives an Event Notification generated from a Per-Job Subscription 1712 Object and caused by a Printer Event. The Event Notification gives 1713 access to the Printer and the Subscription Object. The Event 1714 Notification gives access to the associated Job only via this 1715 attribute. 1717 5.4.7 notify-subscriber-user-name (name(MAX)) 1719 This attribute contains the name of the user who performed the 1720 Subscription Creation Operation. 1722 A Printer MUST support this attribute. 1724 The Printer sets this attribute to the most authenticated printable 1725 name that it can obtain from the authentication service over which 1726 the Subscription Creation Operation was received. The Printer uses 1727 the same mechanism for determining the value of this attribute as it 1728 does for a Job's "job-originating-user-name" (see [RFC2911] section 1729 4.3.6). 1731 Note: To help with authentication, a Subscription Object may have 1732 additional private attributes about the user, e.g., a credential of a 1733 principal. Such private attributes are implementation-dependent and 1734 not defined in this document. 1736 6 Printer Description Attributes Related to Notification 1738 This section defines the Printer Description attributes that are 1739 related to Notification. Table 3 lists the Printer Description 1740 attributes, indicates the Printer support required for conformance, 1741 and whether or not the attribute is READ-ONLY (see section 3.1): 1743 Table 3 - Printer Description Attributes Associated with Notification 1745 Printer object attributes: REQUIRED READ-ONLY 1747 printer-state-change-time (integer(1:MAX)) No Yes 1749 printer-state-change-date-time (dateTime) No Yes 1751 6.1 printer-state-change-time (integer(1:MAX)) 1753 This attribute records the most recent time at which the 'printer- 1754 state-changed' Printer Event occurred whether or not any Subscription 1755 objects were listening for this event. This attribute helps a client 1756 or operator to determine how long the Printer has been in its current 1757 state. 1759 A Printer MAY support this attribute and if so, the attribute MUST be 1760 READ-ONLY. 1762 On power-up, the Printer MUST set the value of this attribute to be 1763 the value of its "printer-up-time" attribute, so that it always has a 1764 value. Whenever the 'printer-state-changed' Printer Event occurs, the 1765 Printer MUST set this attribute to the value of the Printer's 1766 "printer-up-time" attribute. 1768 6.2 printer-state-change-date-time (dateTime) 1770 This attribute records the most recent time at which the 'printer- 1771 state-changed' Printer Event occurred whether or not there were any 1772 Subscription Objects listening for this event. This attribute helps 1773 a client or operator to determine how long the Printer has been in 1774 its current state. 1776 A Printer MAY support this attribute and if so, the attribute MUST be 1777 READ-ONLY. 1779 On power-up, the Printer MUST set the value of this attribute to be 1780 the value of its "printer-current-time" attribute, so that it always 1781 has a value (see [RFC2911] section 4.4.30 on "printer-current-time"). 1782 Whenever the 'printer-state-changed' Printer Event occurs, the 1783 Printer MUST set this attribute to the value of the Printer's 1784 "printer-current-time" attribute. 1786 7 New Values for Existing Printer Description Attributes 1788 This section contains those attributes for which additional values 1789 are added. 1791 7.1 operations-supported (1setOf type2 enum) 1793 The following "operation-id" values are added in order to support the 1794 new operations defined in this document: 1796 Table 4 - Operation-id assignments 1798 Value Operation Name 1800 0x0016 Create-Printer-Subscriptions 1802 0x0017 Create-Job-Subscriptions 1804 0x0018 Get-Subscription-Attributes 1806 0x0019 Get-Subscriptions 1808 0x001A Renew-Subscription 1810 0x001B Cancel-Subscription 1812 8 Attributes Only in Event Notifications 1814 This section contains those attributes that exist only in Event 1815 Notifications and do not exist in any objects. 1817 8.1 notify-subscribed-event (type2 keyword) 1819 This attribute indicates the Subscribed Event that caused the Printer 1820 to send this Event Notification. This attribute exists only in Event 1821 Notifications. 1823 This attribute MUST contain one of the values of the "notify-events" 1824 attribute in the Subscription Object, i.e., one of the Subscribed 1825 Event values. Its value is the Subscribed Event that "matches" the 1826 Event that caused the Printer to send this Event Notification. This 1827 Subscribed Event value may be identical to the Event or the Event may 1828 be a sub-value of the Subscribed Event. For example, the 'job- 1829 completed' Event (which is a sub-event of the 'job-state-changed' 1830 event) would cause the Printer to send an Event Notification for 1831 either the 'job-completed' or 'job-state-changed' Subscribed Events 1832 and to send the 'job-completed' or 'job-state-changed' value for this 1833 attribute, respectively,. See section 5.3.2.2 for the "matching" 1834 rules of Subscribed Events and for additional examples. 1836 The Delivery Method Document specifies whether the Printer includes 1837 the value of this attribute in an Event Notification. 1839 8.2 notify-text (text(MAX)) 1841 This attribute contains a Human Consumable text message (see section 1842 0). This message describes the Event and is encoded as plain text, 1843 i.e., 'text/plain' with the charset specified by Subscription 1844 Object's "notify-charset" attribute. 1846 The Delivery Method Document specifies whether the Printer includes 1847 this attribute in an Event Notification. 1849 9 Event Notification Content 1851 This section defines the Event Notification content that the Printer 1852 sends when an Event occurs. 1854 When an Event occurs, the Printer MUST find each Subscription object 1855 whose "notify-events" attribute "matches" the Event. See section 1856 5.3.2.2 for details on "matching". For each matched Subscription 1857 Object, the Printer MUST create an Event Notification with the 1858 content and format that the Delivery Method Document specifies. The 1859 content contains the value of attributes specified by the Delivery 1860 Method Document. The Printer obtains the values immediately after the 1861 Event occurs. For example, if the "printer-state" attribute changes 1862 from 'idle' to 'processing', the Event 'printer-state-changed' occurs 1863 and the Printer puts various attributes into the Event Notification, 1864 including "printer-up-time" and "printer-state" with the values that 1865 they have immediately after the Event occurs, i.e., the value of 1866 "printer-state" is 'processing'. 1868 If two different Events occur simultaneously, or nearly so (e.g., 1869 "printer-up-time" has the same value for both), the Printer MUST 1870 create a separate Event Notification for each Event, even if the 1871 associated Subscription Object is the same for both Events. However, 1872 the Printer MAY combine these distinct Event Notifications into a 1873 single Compound Event Notification if the Delivery Method supports 1874 Compound Event Notifications For example, suppose that two nearly- 1875 simultaneously Events represent two successive 'printer-state- 1876 changed' Events, one from 'idle' to 'processing' and another from 1877 'processing' to 'stopped'. These two Events have the same name but 1878 are different instances of the Event. Then the Printer MUST create a 1879 separate Event Notification for each Event and SHOULD accurately 1880 report the "printer-state" of the first Event as 'processing' and the 1881 second Event as 'stopped'. 1883 If a Subscription Object contains more than one Subscribed Event, and 1884 several Events occur in quick succession each matching a different 1885 Subscribed Event in the Subscription Object, the Printer MUST NOT 1886 generate a single Event Notification from several of these Events, 1887 but MAY combine distinct Event Notifications into a single Compound 1888 Event Notification if the Delivery Method supports Compound Event 1889 Notifications. 1891 After the Printer has created the Event Notification, the Printer 1892 delivers it via either a: 1894 Push Delivery Method: The Printer sends the Event Notification 1895 shortly after an Event occurs. For some Push Delivery Methods, 1896 the Notification Recipient MUST send a response; for others it 1897 MUST NOT send a response. 1899 Pull Delivery Method: The Printer saves Event Notifications for 1900 some event-lease time and expects the Notification Recipient to 1901 request Event Notifications. The Printer returns the Event 1902 Notifications in a response to such a request. 1904 If an error that meets the following conditions occurs, the Printer 1905 MUST cancel the Subscription Object. 1907 a)the error occurs during the sending of an Event Notification 1908 generated from Subscription Object S AND 1910 b)the error would continue to occur every time the Printer sends an 1911 Event Notification generated from Subscription Object S in the 1912 future. 1914 From example, if the address of the "notify-recipient-uri" of 1915 Subscription Object A references a non-existent target and the 1916 Printer determines that this fact, it MUST delete Subscription Object 1917 A. 1919 The next two sections describe the values that a Printer sends in the 1920 content of Machine Consumable and Human Consumable Event 1921 Notifications, respectively. 1923 The tables in the sub-sections of this section contain the following 1924 columns: 1926 a)Source Value: the name of the attribute that supplies the value 1927 for the Event Notification. Asterisks in this field refer to a 1928 note below the table. 1930 b)Sends: if the Printer supports the value (column 1) on the 1931 Source Object (column 3) the Delivery Method MUST specify: 1933 MUST: that the Printer MUST send the value. 1935 SHOULD: either that the Printer MUST send the value or that 1936 the value is incompatible with the Delivery Method. 1938 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 1939 or NEED NOT send the value. The Delivery Method specifies the 1940 level of conformance for the Printer. 1942 c)Source Object: the object from which the source value comes. If 1943 the object is "Event Notification", the Printer fabricates the 1944 value when it sends the Event Notification. See section 8. 1946 9.1 Content of Machine Consumable Event Notifications 1948 This section defines the attributes that a Delivery Method MUST 1949 mention in a Delivery Method Document when specifying the Machine 1950 Consumable Event Notification's contents. 1952 This document does not define the order of attributes in Event 1953 Notifications. However, Delivery Method Documents MAY define the 1954 order of some or all of the attributes. 1956 A Delivery Method Document MUST specify additional attributes (if 1957 any) that a Printer implementation sends in a Machine Consumable 1958 Event Notification. 1960 Notification Recipients MUST be able to accept Event Notifications 1961 containing attributes they do not recognize. What a Notification 1962 Recipient does with an unrecognized attribute is implementation- 1963 dependent. Notification Recipients MAY attempt to display 1964 unrecognized attributes anyway or MAY ignore them. 1966 The next three sections define the attributes in Event Notification 1967 Contents that are: 1969 1.for all Events 1971 2.for Job Events only 1973 3.for Printer Events only 1975 9.1.1 Event Notification Content Common to All Events 1977 This section lists the attributes that a Delivery Method Document 1978 MUST specify for all Events. 1980 Table 5 lists potential values in each Event Notification. 1982 Table 5 - Attributes in Event Notification Content 1984 Source Value Sends Source Object 1986 notify-subscription-id (integer(1:MAX)) MUST Subscription 1988 notify-printer-uri (uri) MUST Subscription 1990 notify-subscribed-event (type2 keyword) MUST Event 1991 Notification 1993 printer-up-time (integer(MIN:MAX)) MUST Printer 1995 printer-current-time (dateTime) * MUST Printer 1997 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 1999 notify-charset (charset) SHOULD Subscription 2001 notify-natural-language (naturalLanguage) SHOULD Subscription 2003 notify-user-data (octetString(63)) ** SHOULD Subscription 2005 notify-text (text) SHOULD Event 2006 Notification 2008 attributes from the "notify-attributes" MAY Printer 2009 attribute *** 2011 attributes from the "notify-attributes" MAY Job 2012 attribute *** 2014 attributes from the "notify-attributes" MAY Subscription 2015 attribute *** 2017 *A Printer MUST send this value only if and only if it supports the 2018 Printer's "printer-current-time" attribute. 2020 ** If the Subscription Object does not contain a "notify-user-data" 2021 attribute and the Delivery Method document REQUIRES the Printer to 2022 send the "notify-user-data" source value in the Event Notification, 2023 the Printer MUST send an octet-string of length 0. 2025 *** The last three rows represent additional attributes that a client 2026 MAY request via the "notify-attributes" attribute. A Printer MAY 2027 support the "notify-attributes" attribute. The Delivery Method MUST 2028 say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED 2029 NOT support the "notify-attributes" attribute and specific values of 2030 this attribute. The Delivery Method MAY say that support for the 2031 "notify-attributes" is conditioned on support of the attribute by the 2032 Printer or it MAY say that Printer MUST support the "notify- 2033 attributes" attribute if the Printer supports the Delivery Method. 2035 9.1.2 Additional Event Notification Content for Job Events 2037 This section lists the additional attributes that a Delivery Method 2038 Document MUST specify for Job Events. See Table 6. 2040 Table 6 - Additional Event Notification Content for Job Events 2042 Source Value Sends Source Object 2044 job-id (integer(1:MAX)) MUST Job 2046 job-state (type1 enum) MUST Job 2048 job-state-reasons (1setOf type2 keyword) MUST Job 2050 job-impressions-completed (integer(0:MAX)) * MUST Job 2052 * The Printer MUST send the "job-impressions-completed" attribute in 2053 an Event Notification only for the combinations of Events and 2054 Subscribed Events shown in Table 7. 2056 Table 7 - Combinations of Events and Subscribed Events for "job- 2057 impressions-completed" 2059 Job Event Subscribed Job Event 2061 'job-progress' 'job-progress' 2063 'job-completed' 'job-completed' 2065 'job-completed' 'job-state-changed' 2067 9.1.3 Additional Event Notification Content for Printer Events 2069 This section lists the additional attributes that a Delivery Method 2070 Document MUST specify for Printer Events. See Table 8. 2072 Table 8 - Additional Event Notification Content for Printer Events 2074 Source Value Sends Source Object 2076 printer-state (type1 enum) MUST Printer 2078 printer-state-reasons (1setOf type2 keyword) MUST Printer 2080 printer-is-accepting-jobs (boolean) MUST Printer 2082 9.2 Content of Human Consumable Event Notification 2084 This section defines the information that a Delivery Method MUST 2085 mention in a Delivery Method Document when specifying the Human 2086 Consumable Event Notifications contents or the value of the "notify- 2087 text" attribute. 2089 Such a Delivery Method MUST specify the following information and a 2090 Printer SHOULD send it: 2092 a)the Printer name (see Table 9) 2093 b)the time of the Event (see Table 11) 2094 c)for Printer Events only: 2096 i) the Event (see Table 10) and/or Printer state information 2097 (see Table 14) 2098 d)for Job Events only: 2099 i) the job identity (see Table 12) 2100 ii) the Event (see Table 10) and/or Job state information (see 2101 Table 13) 2103 The subsections of this section specify the attributes that a Printer 2104 MUST use to obtain this information. 2106 A Delivery Method Document MUST specify additional information (if 2107 any) that a Printer implementation sends in a Human Consumable Event 2108 Notification or in the "notify-text" attribute. 2110 A client MUST NOT request additional attributes via the "notify- 2111 attributes" attribute because this attribute works only for Machine 2112 Consumable Event Notifications. 2114 Notification Recipients MUST NOT expect to be able to parse the Human 2115 Consumable Event Notification contents or the value of the "notify- 2116 text" attribute. 2118 The next three sections define the attributes in Event Notification 2119 Contents that are: 2121 a) for all Events 2122 b) for Job Events only 2123 c) for Printer Events only 2125 9.2.1 Event Notification Content Common to All Events 2127 This section lists the source of the information that a Delivery 2128 Method MUST specify for all Events. 2130 There is a separate table for each piece of information. Each row in 2131 the table represents a source value for the information and the 2132 values are listed in order of preference, with the first one being 2133 the preferred one. An implementation SHOULD use the source value from 2134 the earliest row in each table. It MAY use the source value from 2135 another row instead, or it MAY combine the source values from several 2136 rows. An implementation is free to determine the best way to present 2137 this information. 2139 In all tables of this section, all rows contain a "MAY" in order to 2140 state that the Delivery Method specifies the conformance. 2142 Table 9 lists the source of the information for the Printer Name. The 2143 "printer-name" is more user-friendly unless the Notification 2144 Recipient is in a place where the Printer name is not meaningful. For 2145 example, an implementation could have the intelligence to send the 2146 value of the "printer-name" attribute to a Notification Recipient 2147 that can access the Printer via value of the "printer-name" attribute 2148 and otherwise send the value of the "notify-printer-uri" attribute. 2150 Table 9 - Printer Name in Event Notification Content 2152 Source Value Sends Source Object 2154 printer-name (name(127)) MAY Printer 2156 notify-printer-uri (uri) MAY Subscription 2158 Table 10 lists the source of the information for the Event name. A 2159 Printer MAY combine this information with state information described 2160 for Jobs in Table 13 or for Printers in Table 14. 2162 Table 10 - Event Name in Event Notification Content 2164 Source Value Sends Source Object 2166 notify-subscribed-event (type2 keyword) MAY Subscription 2168 Table 11 lists the source of the information for the time that the 2169 Event occurred. A Printer can send this value only if it supports the 2170 Printer's "printer-current-time" attribute. If a Printer does not 2171 support the "printer-current-time" attribute, it MUST NOT send the 2172 "printer-up-time" value instead, since it is not an allowed option 2173 for human consumable information. 2175 Table 11 - Event Time in Event Notification Content 2177 Source Value Sends Source Object 2179 printer-current-time (dateTime) MAY Printer 2181 9.2.2 Additional Event Notification Content for Job Events 2183 This section lists the source of the additional information that a 2184 Delivery Method MUST specify for Job Events. 2186 Table 12 lists the source of the information for the job name. The 2187 "job-name" is likely more meaningful to a user than "job-id". 2189 Table 12 - Job Name in Event Notification Content 2191 Source Value Sends Source Object 2193 job-name (name(MAX)) MAY Job 2195 job-id (integer(1:MAX)) MAY Job 2197 Table 13 lists the source of the information for the job state. If a 2198 Printer supports the "job-state-message" and "job-detailed-state- 2199 message" attributes, it SHOULD use those attributes for the job state 2200 information, otherwise, it should fabricate such information from the 2201 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2202 combine this information with Event information. 2204 Table 13 - Job State in Event Notification Content 2206 Source Value Sends Source 2207 Object 2209 job-state-message (text(MAX)) MAY Job 2211 job-detailed-status-messages (1setOf text(MAX)) MAY Job 2213 job-state (type1 enum) MAY Job 2215 job-state-reasons (1setOf type2 keyword) MAY Job 2217 9.2.3 Additional Event Notification Content for Printer Events 2219 This section lists the source of the additional information that a 2220 Delivery Method MUST specify for Printer Events. 2222 Table 14 lists the source of the information for the printer state. 2223 If a Printer supports the "printer-state-message", it SHOULD use that 2224 attribute for the job state information, otherwise it SHOULD 2225 fabricate such information from the "printer-state" and "printer- 2226 state-reasons". For some Events, a Printer MAY combine this 2227 information with Event information. 2229 Table 14 - Printer State in Event Notification Content 2231 Source Value Sends Source 2232 Object 2234 printer-state-message (text(MAX)) MAY Printer 2236 printer-state (type1 enum) MAY Printer 2238 printer-state-reasons (1setOf type2 keyword) MAY Printer 2240 printer-is-accepting-jobs (boolean) MAY Printer 2242 10 Delivery Methods 2244 A Delivery Method is the mechanism, i.e., protocol, by which the 2245 Printer delivers an Event Notification to a Notification Recipient. 2246 There are several potential Delivery Methods for Event Notifications, 2247 standardized, as well as proprietary. This document does not define 2248 any of these delivery mechanisms. Each Delivery Method MUST be 2249 defined in a Delivery Method Document that is separate from this 2250 document. New Delivery Methods will be created as needed using an 2251 extension to the registration procedures defined in [RFC2911]. Such 2252 documents are registered with IANA (see section 13). 2254 The following sorts of Delivery Methods are expected: 2256 - The Notification Recipient polls for Event Notifications at 2257 intervals directed by the Printer 2259 - The Printer sends Event Notifications to the Notification 2260 Recipient using http as the transport. 2262 - The Printer sends an email message. 2264 This section specifies how to define a Delivery Method Document and 2265 what to put in such a document. 2267 A Delivery Method Document MUST contain an exact copy of the 2268 following paragraph, caption and table. In addition, column 2 of the 2269 table in the Delivery Method Document MUST contain answers to 2270 questions in column 1 for the Delivery Method. Also, the Delivery 2271 Method document MUST contain a reference to this document and call 2272 that reference [ipp-ntfy] because the table contains an [ipp-ntfy] 2273 reference. 2275 If a Printer supports this Delivery Method, the following are its 2276 characteristics. 2278 Table 15 - Information about the Delivery Method 2280 Document Method Conformance Delivery Method Realization 2281 Requirement 2283 1.What is the URL scheme name for the 2284 Delivery Method? 2286 2.Is the Delivery Method REQUIRED, 2287 RECOMMENDED, or OPTIONAL for an IPP 2288 Printer to support? 2290 3.What transport and delivery 2291 protocols does the Printer use to 2292 deliver the Event Notification 2293 Content, i.e., what is the entire 2294 network stack? 2296 4.Can several Event Notifications be 2297 combined into a Compound Event 2298 Notification? 2300 5.Is the Delivery Method initiated by 2301 the Notification Recipient (pull), 2302 or by the Printer (push)? 2304 6.Is the Event Notification content 2305 Machine Consumable or Human 2306 Consumable? 2308 7.What section in this document 2309 answers the following question? For 2310 a Machine Consumable Event 2311 Notification, what is the 2312 representation and encoding of 2313 values defined in section 9.1 of 2314 [ipp-ntfy] and the conformance 2315 requirements thereof? For a Human 2316 Consumable Event Notification, what 2317 is the representation and encoding 2318 of pieces of information defined in 2319 section 0 of [ipp-ntfy] and the 2320 conformance requirements thereof? 2322 8.What are the latency and 2323 reliability of the transport and 2324 delivery protocol? 2326 9.What are the security aspects of 2327 the transport and delivery 2328 protocol, e.g., how it is handled 2329 in firewalls? 2331 10. What are the content length 2332 restrictions? 2334 11. What are the additional values 2335 or pieces of information that a 2336 Printer sends in an Event 2337 Notification content and the 2338 conformance requirements thereof? 2340 12. What are the additional 2341 Subscription Template and/or 2342 Subscription Description attributes 2343 and the conformance requirements 2344 thereof? 2346 13. What are the additional Printer 2347 Description attributes and the 2348 conformance requirements thereof? 2350 11 Operations for Notification 2352 This section defines all of the operations for Notification. Section 2353 7.1 assigns the "operation-id" for each operation. The following two 2354 sub-sections define Subscription Creation Operations, and other 2355 operations. 2357 11.1 Subscription Creation Operations 2359 This section defines the Subscription Creation Operations. The first 2360 section on Create-Job-Subscriptions gives most of the information. 2361 The other Subscription Creation Operations refer to the section on 2362 Create-Job-Subscriptions, even though the Create-Job-Subscriptions 2363 operation is the only OPTIONAL operation in this document (see 2364 section 12). 2366 A Printer MUST support Create-Printer-Subscriptions and the 2367 Subscription Template Attributes Group in Job Creation operations. It 2368 MAY support Create-Job-Subscriptions operations. 2370 11.1.1 Create-Job-Subscriptions Operation 2372 The operation creates one or more Per-Job Subscription Objects. The 2373 client supplies one or more Subscription Template Attributes Groups 2374 each containing one or more of Subscription Template Attributes 2375 (defined in section 5.3). 2377 Except for errors, the Printer MUST create exactly one Per-Job 2378 Subscription Object from each Subscription Template Attributes Group 2379 in the request, even if the newly created Subscription Object would 2380 have identical behavior to some existing Subscription Object. The 2381 Printer MUST associate each newly created Per-Job Subscription Object 2382 with the target Job, which is specified by the "notify-job-id" 2383 operation attribute. 2385 The Printer MUST accept the request in any of the target job's 'not- 2386 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2387 'processing-stopped'. The Printer MUST NOT change the job's "job- 2388 state" attribute because of this operation. If the target job is in 2389 any of the 'completed' states, i.e., 'completed', 'canceled', or 2390 'aborted, then the Printer MUST reject the request and return the 2391 'client-error-not-possible' status code; the response MUST NOT 2392 contain any Subscription Attribute Groups. 2394 Access Rights: To create Per-Job Subscription Objects, the 2395 authenticated user (see [RFC2911] section 8.3) performing this 2396 operation MUST either be the job owner or have Operator or 2397 Administrator access rights for this Printer (see [RFC2911] sections 2398 1 and 8.5). Otherwise the Printer MUST reject the operation and 2399 return: the 'client-error-forbidden', 'client-error-not- 2400 authenticated', or 'client-error-not-authorized' status code as 2401 appropriate. 2403 11.1.1.1 Create-Job-Subscriptions Request 2405 The following groups of attributes are part of the Create-Job- 2406 Subscriptions Request: 2408 Group 1: Operation Attributes 2410 Natural Language and Character Set: 2411 The "attributes-charset" and "attributes-natural-language" 2412 attributes as described in [RFC2911] section 3.1.4.1. 2414 Target: 2415 The "printer-uri" attribute which defines the target for this 2416 operation as described in [RFC2911] section 3.1.5. 2418 Requesting User Name: 2419 The "requesting-user-name" attribute SHOULD be supplied by the 2420 client as described in [RFC2911] section 8.3. 2422 notify-job-id (integer(1:MAX)): 2423 The client MUST supply this attribute and it MUST specify the 2424 Job object to associate the Per-Job Subscription with. The 2425 value of "notify-job-id" MUST be the value of the "job-id" of 2426 the associated Job object. If the client does not supply this 2427 attribute, the Printer MUST reject this request with a 'client- 2428 error-bad-request' status code. 2430 Group 2-N: Subscription Template Attributes 2432 For each occurrence of this group: 2434 The client MUST supply one or more Subscription Template 2435 Attributes in any order. See section 5.3 for a description of 2436 each such attribute. See section 5.2 for details on processing 2437 these attributes. 2439 11.1.1.2 Create-Job-Subscriptions Response 2441 The Printer MUST return to the client the following sets of 2442 attributes as part of a Create-Job-Subscriptions response: 2444 Group 1: Operation Attributes 2446 Status Message: 2447 In addition to the REQUIRED status code returned in every 2448 response, the response OPTIONALLY includes a "status-message" 2449 (text(255)) and/or a "detailed-status-message" (text(MAX)) 2450 operation attribute as described in [RFC2911] sections 13 and 2451 31.6. 2453 In this group, the Printer can return any status codes defined 2454 in [RFC2911] and section 16. The following is a description of 2455 the important status codes: 2457 successful-ok: the Printer created all Subscription Objects 2458 requested. 2459 successful-ok-ignored-subscriptions: the Printer created some 2460 Subscription Objects requested but some failed. The 2461 Subscription Attributes Groups with a "notify-status-code" 2462 attribute are the ones that failed. 2464 client-error-ignored-all-subscriptions: the Printer created no 2465 Subscription Objects requested and all failed. The 2466 Subscription Attributes Groups with a "notify-status-code" 2467 attribute are the ones that failed 2468 client-error-not-possible: For this operation and other Per-Job 2469 Subscription operations, this error can occur because the 2470 specified Job has already completed. 2472 Natural Language and Character Set: 2473 The "attributes-charset" and "attributes-natural-language" 2474 attributes as described in [RFC2911] section 3.1.4.2. 2476 Group 2: Unsupported Attributes 2478 See [RFC2911] section 3.1.7 for details on returning 2479 Unsupported Attributes. This group does not contain any 2480 unsupported Subscription Template Attributes; they are returned 2481 in the Subscription Attributes Group (see below). 2483 Group 3-N: Subscription Attributes 2485 These groups MUST be returned unless the Printer is unable to 2486 interpret the entire request, e.g., the "status-code" parameter 2487 returned in Group 1 has the value: 'client-error-bad-request'. 2489 "notify-status-code" (type2 enum): 2490 Indicates the status of this subscription (see section 17 for 2491 the status code definitions). Section 5.2 defines when this 2492 attribute MUST be present in this group. 2494 See section 5.2 for details on the contents of each occurrence 2495 of this group. 2497 11.1.2 Create-Printer-Subscriptions operation 2499 The operation is identical to Create-Job-Subscriptions with 2500 exceptions noted in this section. 2502 The operation creates Per-Printer Subscription Objects instead of 2503 Per-Job Subscription Objects, and associates each newly created Per- 2504 Printer Subscription Object with the Printer specified by the 2505 operation target rather than with a specific Job. 2507 The Printer MUST accept the request in any of its states, i.e., 2508 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its 2509 "printer-state" attribute because of this operation. 2511 Access Rights: To create Per-Printer Subscription Objects, the 2512 authenticated user (see [RFC2911] section 8.3) performing this 2513 operation MUST have Operator or Administrator access rights for this 2514 Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the Printer 2515 MUST reject the operation and return: the 'client-error-forbidden', 2516 'client-error-not-authenticated', or 'client-error-not-authorized' 2517 status code as appropriate. 2519 11.1.2.1 Create-Printer-Subscriptions Request 2521 The groups are identical to the Create-Job-Subscriptions (see section 2522 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2523 the "notify-job-id" attribute. If the client does supply the 2524 "notify-job-id" attribute, then the Printer MUST treat it as any 2525 other unsupported Operation attribute and MUST return it in the 2526 Unsupported Attributes group. 2528 11.1.2.2 Create-Printer-Subscriptions Response 2530 The groups are identical to the Create-Job-Subscriptions (see section 2531 11.1.1.2). 2533 11.1.3 Job Creation Operation - Extensions for Notification 2535 This document extends the Job Creation operations to create 2536 Subscription Objects as a part of the operation. 2538 The operation is identical to Create-Job-Subscriptions with 2539 exceptions noted in this section. 2541 Unlike the Create-Job-Subscriptions operation, this operation 2542 associates the newly created Subscription Objects with the Job object 2543 created by this operation. The operation succeeds if and only if the 2544 Job creation succeeds. If the Printer does not create some or all of 2545 the requested Subscription Objects, the Printer MUST return a 2546 'successful-ok-ignored-subscriptions' status-code instead of a 2547 'successful-ok' status-code, but the Printer MUST NOT reject the 2548 operation because of a failure to create Subscription Objects. 2550 If the operation includes a Job Template group, the client MUST 2551 supply it after the Operation Attributes group and before the first 2552 Subscription Template Attributes Group. 2554 If a Printer does not support this Notification specification, then 2555 it MUST treat the Subscription Attributes Group like an unknown group 2556 and ignore it (see [RFC2911] section 5.2.2). Because the Printer 2557 ignores the Subscription Attributes Group, it doesn't return them in 2558 the response either, thus indicating to the client that the Printer 2559 doesn't support Notification. 2561 Access Rights: To create Per-Job Subscription Objects, the 2562 authenticated user (see [RFC2911] section 8.3) performing this 2563 operation MUST either have permission to create Jobs on the Printer. 2564 Otherwise the Printer MUST reject the operation and return: the 2565 'client-error-forbidden', 'client-error-not-authenticated', or 2566 'client-error-not-authorized' status code as appropriate. 2568 11.1.3.1 Job Creation Request 2570 The groups for this operation are sufficiently different from the 2571 Create-Job-Subscriptions operation that they are all presented here. 2572 The following groups of attributes are supplied as part of a Job 2573 Creation Request: 2575 Group 1: Operation Attributes 2577 Same as defined in [RFC2911] for Print-Job, Print-URI, and 2578 Create-Job requests. 2579 Group 2: Job Template Attributes 2581 The client OPTIONALLY supplies a set of Job Template attributes 2582 as defined in [RFC2911] section 4.2. 2583 Group 3 to N: Subscription Template Attributes 2585 The same as Group 2-N in Create-Job-Subscriptions. See section 2586 11.1.1.1. 2587 Group N+1: Document Content (Print-Job only) 2589 The client MUST supply the document data to be processed. 2591 11.1.3.2 Job Creation Response 2593 The Printer MUST return to the client the following sets of 2594 attributes as part of a Print-Job, Print-URI, and Create-Job 2595 Response: 2597 Group 1: Operation Attributes 2599 Status Message: 2601 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2602 Job requests. 2604 In this group, the Printer can return any status codes defined 2605 in [RFC2911] and section 16. The following is a description of 2606 the important status codes: 2608 successful-ok: the Printer created the Job and all Subscription 2609 Objects requested. 2610 successful-ok-ignored-subscriptions: the Printer created the Job 2611 and not all of the Subscription Objects requested. This 2612 status-code hides 'successful-ok-xxx' status-codes that could 2613 reveal problems in Job creation. The Printer MUST not return 2614 the 'client-error-ignored-all-subscriptions' status code for 2615 Job Creation operations because the Printer returns an error 2616 status-code only when it fails to create a Job. 2618 Natural Language and Character Set: 2619 The "attributes-charset" and "attributes-natural-language" 2620 attributes as described in [RFC2911] section 3.1.4.2. 2622 Group 2: Unsupported Attributes 2624 See [RFC2911] section 3.1.7 for details on returning 2625 Unsupported Attributes. This group does not contain any 2626 unsupported Subscription Template Attributes; they are returned 2627 in the Subscription Attributes Group (see below). 2629 Group 3: Job Object Attributes 2631 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2632 Job requests. 2634 Group 4 to N: Subscription Attributes 2636 These groups MUST be returned if and only if the client 2637 supplied Subscription Template Attributes and the operation was 2638 accepted. 2640 See section 5.2 for details on the contents of each occurrence 2641 of this group. 2643 11.2 Other Operations 2645 This section defines other operations on Subscription objects. 2647 11.2.1 Validate-Job Operation - Extensions for Notification 2649 A client can test whether one or more Subscription Objects could be 2650 created using the Validate-Job operation. The client supplies one or 2651 more Subscription Template Attributes Groups (defined in section 2652 5.3), just as in a Job Creation request. 2654 A Printer MUST support this extension to this operation. 2656 The Printer MUST accept requests that are identical to the Job 2657 Creation request defined in section 11.1.3.1, except that the request 2658 MUST not contain document data. 2660 The Printer MUST return the same groups and attributes as the Print- 2661 Job operation (section 11.1.3.1) with the following exceptions. The 2662 Printer MUST NOT return a Job Object Attributes Group because no Job 2663 is created. The Printer MUST NOT return the "notify-subscription-id" 2664 attribute in any Subscription Attribute Group because no Subscription 2665 Object is created. 2667 If the Printer would succeed in creating a Subscription Object, the 2668 corresponding Subscription Attributes Group either has no 'status- 2669 code' attribute or a 'status-code' attribute with a value of 2670 'successful-ok-too-many-events' or 'successful-ok-ignored-or- 2671 substituted-attributes' (see sections 5.2 and 17). The status-codes 2672 have the same meaning as in Job Creation except the results state 2673 what "would happen". 2675 The Printer MUST validate Subscription Template Attributes Groups in 2676 the same manner as the Job Creation operations. 2678 11.2.2 Get-Printer-Attributes - Extensions for Notification 2680 This operation is extended so that it returns Printer attributes 2681 defined in this document. 2683 A Printer MUST support this extension to this operation. 2685 In addition to the requirements of [RFC2911] section 3.2.5, a Printer 2686 MUST support the following additional values for the "requested- 2687 attributes" Operation attribute in this operation and return such 2688 attributes in the Printer Object Attributes group of its response. 2690 1.Subscription Template Attributes: Each supported attribute in 2691 column 2 of Table 1. 2693 2.New Printer Description Attributes: Each supported attribute in 2694 section 6. 2696 3.New Group Name: The 'subscription-template' group name, which 2697 names all supported Subscription Template Attribute in column 2 2698 of Table 1. This group name is also used in the Get- 2699 Subscription-Attributes and Get-Subscriptions operation with an 2700 analogous meaning. 2702 4.Extended Group Name: The 'all' group name, which names all 2703 Printer attributes according to [RFC2911] section 3.2.5. In 2704 this extension 'all' names all attributes specified in [RFC2911] 2705 plus those named in items 1 and 2 of this list. 2707 11.2.3 Get-Subscription-Attributes operation 2709 This operation allows a client to request the values of the 2710 attributes of a Subscription Object. 2712 A Printer MUST support this operation. 2714 This operation is almost identical to the Get-Job-Attributes 2715 operation (see [RFC2911] section 3.3.4). The only differences are 2716 that the operation is directed at a Subscription Object rather than a 2717 Job object, and the returned attribute group contains Subscription 2718 Object attributes rather than Job object attributes. 2720 11.2.3.1 Get-Subscription-Attributes Request 2722 The following groups of attributes are part of the Get-Subscription- 2723 Attributes request: 2725 Group 1: Operation Attributes 2727 Natural Language and Character Set: 2728 The "attributes-charset" and "attributes-natural-language" 2729 attributes as described in section [RFC2911] 3.1.4.1. 2731 Target: 2732 The "printer-uri" attribute which defines the target for this 2733 operation as described in [RFC2911] section 3.1.5. 2735 "notify-subscription-id" (integer (1:MAX)): 2736 The client MUST supply this attribute. The Printer MUST 2737 support this attribute. This attribute specifies the 2738 Subscription Object from which the client is requesting 2739 attributes. If the client omits this attribute, the Printer 2740 MUST reject this request with the 'client-error-bad-request' 2741 status code. 2743 Requesting User Name: 2744 The "requesting-user-name" attribute SHOULD be supplied by the 2745 client as described in [RFC2911] section 8.3. 2747 "requested-attributes" (1setOf keyword): 2748 The client OPTIONALLY supplies this attribute. The Printer 2749 MUST support this attribute. This attribute specifies the 2750 attributes of the specified Subscription Object that the 2751 Printer MUST return in the response. Each value of this 2752 attribute is either an attribute name (defined in sections 5.3 2753 and 5.4) or an attribute group name. The attribute group names 2754 are: 2756 - 'subscription-template': all attributes that are both defined 2757 in section 5.3 and present on the specified Subscription 2758 Object (column 1 of Table 1). 2759 - 'subscription-description': all attributes that are both 2760 defined in section 5.4 and present on the specified 2761 Subscription Object (Table 2). 2763 - 'all': all attributes that are present on the specified 2764 Subscription Object. 2765 A Printer MUST support all these group names. 2767 If the client omits this attribute, the Printer MUST respond as 2768 if this attribute had been supplied with a value of 'all'. 2770 11.2.3.2 Get-Subscription-Attributes Response 2772 The Printer returns the following sets of attributes as part of the 2773 Get-Subscription-Attributes Response: 2775 Group 1: Operation Attributes 2777 Status Message: 2778 Same as [RFC2911]. 2780 Natural Language and Character Set: 2781 The "attributes-charset" and "attributes-natural-language" 2782 attributes as described in [RFC2911] section 3.1.4.2. The 2783 "attributes-natural-language" MAY be the natural language of 2784 the Subscription Object, rather than the one requested. 2786 Group 2: Unsupported Attributes 2788 See [RFC2911] section 3.1.7 for details on returning 2789 Unsupported Attributes. 2791 The response NEED NOT contain the "requested-attributes" 2792 operation attribute with any supplied values (attribute 2793 keywords) that were requested by the client but are not 2794 supported by the Printer. If the Printer does return 2795 unsupported attributes referenced in the "requested-attributes" 2796 operation attribute and that attribute included group names, 2797 such as 'all', the unsupported attributes MUST NOT include 2798 attributes described in the standard but not supported by the 2799 implementation. 2801 Group 3: Subscription Attributes 2803 This group contains a set of attributes with their current 2804 values. Each attribute in this group: 2806 a)MUST be specified by the "requested-attributes" attribute 2807 in the request, AND 2809 b)MUST be present on the specified Subscription Object AND 2811 c)MUST NOT be restricted by the security policy in force. 2812 For example, a Printer MAY prohibit a client who is not the 2813 creator of a Subscription Object from seeing some or all of 2814 its attributes. See [RFC2911] section 8. 2816 The Printer can return the attributes of the Subscription 2817 Object in any order. The client MUST accept the attributes in 2818 any order. 2820 11.2.4 Get-Subscriptions operation 2822 This operation allows a client to retrieve the values of attributes 2823 of all Subscription Objects belonging to a Job or Printer. 2825 A Printer MUST supported this operation. 2827 This operation is similar to the Get-Subscription-Attributes 2828 operation, except that this Get-Subscriptions operation returns 2829 attributes from possibly more than one object. 2831 This operation is similar to the Get-Jobs operation (see [RFC2911] 2832 section 3.2.6), except that the operation returns Subscription 2833 Objects rather than Job objects. 2835 11.2.4.1 Get-Subscriptions Request 2837 The following groups of attributes are part of the Get-Subscriptions 2838 request: 2840 Group 1: Operation Attributes 2842 Natural Language and Character Set: 2843 The "attributes-charset" and "attributes-natural-language" 2844 attributes as described in [RFC2911] section 3.1.4.1. 2846 Target: 2847 The "printer-uri" attribute which defines the target for this 2848 operation as described in [RFC2911] section 3.1.5. 2850 Requesting User Name: 2851 The "requesting-user-name" attribute SHOULD be supplied by the 2852 client as described in [RFC2911] section 8.3. 2854 "notify-job-id" (integer(1:MAX)): 2855 If the client specifies this attribute, the Printer returns the 2856 specified attributes of all Per-Job Subscription Objects 2857 associated with the Job whose "job-id" attribute value equals 2858 the value of this attribute. If the client does not specify 2859 this attribute, the Printer returns the specified attributes of 2860 all Per-Printer Subscription Objects. Note: there is no way to 2861 get all Per-Job Subscriptions. 2863 "limit" (integer(1:MAX)): 2864 The client OPTIONALLY supplies this attribute. The Printer 2865 MUST support this attribute. It is an integer value that 2866 determines the maximum number of Subscription Objects that a 2867 client will receive from the Printer even if the "my- 2868 subscriptions" attribute constrains which Subscription Objects 2869 are returned. The limit is a "stateless limit" in that if the 2870 value supplied by the client is 'N', then only the first 'N' 2871 Subscription Objects are returned in the Get-Subscriptions 2872 Response. There is no mechanism to allow for the next 'M' 2873 Subscription Objects after the first 'N' Subscription Objects. 2874 If the client does not supply this attribute, the Printer 2875 responds with all applicable Subscription Objects. 2877 "requested-attributes" (1setOf type2 keyword): 2878 The client OPTIONALLY supplies this attribute. The Printer 2879 MUST support this attribute. This attribute specifies the 2880 attributes of the specified Subscription Objects that the 2881 Printer MUST return in the response. Each value of this 2882 attribute is either an attribute name (defined in sections 5.3 2883 and 5.4) or an attribute group name (defined in section 2884 11.2.3.1). If the client omits this attribute, the Printer MUST 2885 respond as if the client had supplied this attribute with the 2886 one value: 'notify-subscription-id'. 2888 "my-subscriptions" (boolean): 2889 The client OPTIONALLY supplies this attribute. The Printer 2890 MUST support this attribute. If the value is 'false', the 2891 Printer MUST consider the Subscription Objects from all users 2892 as candidates. If the value is 'true', the Printer MUST return 2893 the Subscription Objects created by the requesting user of this 2894 request. If the client does not supply this attribute, the 2895 Printer MUST respond as if the client had supplied the 2896 attribute with a value of 'false'. The means for 2897 authenticating the requesting user and matching the 2898 Subscription Objects is similar to that for Jobs which is 2899 described in [RFC2911] section 8. 2901 11.2.4.2 Get-Subscriptions Response 2903 The Printer returns the following sets of attributes as part of the 2904 Get-Subscriptions Response: 2906 Group 1: Operation Attributes 2908 Status Message: 2909 Same as [RFC2911]. 2911 Natural Language and Character Set: 2912 The "attributes-charset" and "attributes-natural-language" 2913 attributes as described in [RFC2911] section 3.1.4.2. 2915 Group 2: Unsupported Attributes 2917 Same as for Get-Subscription-Attributes. 2919 Groups 3 to N: Subscription Attributes 2921 The Printer responds with one Subscription Attributes Group for 2922 each requested Subscription Object (see the "notify-job-id" 2923 attribute in the Operation Attributes Group of this operation). 2925 The Printer returns Subscription Objects in any order. 2927 If the "limit" attribute is present in the Operation Attributes 2928 group of the request, the number of Subscription Attributes 2929 Groups in the response MUST NOT exceed the value of the "limit" 2930 attribute. 2932 It there are no Subscription Objects associated with the 2933 specified Job or Printer, the Printer MUST return zero 2934 Subscription Attributes Groups and it MUST NOT treat this case 2935 as an error, i.e., the status-code MUST be 'successful-ok' 2936 unless something else causes the status code to have some other 2937 value. 2939 See the Group 3 response (Subscription Attributes Group) of the 2940 Get-Subscription-Attributes operation (section 11.2.3.2) for 2941 the attributes that a Printer returns in this group. 2943 11.2.5 Renew-Subscription operation 2945 This operation allows a client to request the Printer to extend the 2946 lease on a Per-Printer Subscription Object. 2948 The Printer MUST support this operation. 2950 The Printer MUST accept this request for a Per-Printer Subscription 2951 Object in any of the target Printer's states, i.e., 'idle', 2952 'processing', or 'stopped', but MUST NOT change the Printer's 2953 "printer-state" attribute. 2955 The Printer MUST reject this request for a Per-Job Subscription 2956 Object because it has no lease (see section 5.4.3). The status code 2957 returned MUST be 'client-error-not-possible'. 2959 Access Rights: The authenticated user (see [RFC2911] section 8.3) 2960 performing this operation MUST either be the owner of the Per-Printer 2961 Subscription Object or have Operator or Administrator access rights 2962 for the Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the 2963 Printer MUST reject the operation and return: the 'client-error- 2964 forbidden', 'client-error-not-authenticated', or 'client-error-not- 2965 authorized' status code as appropriate. 2967 11.2.5.1 Renew-Subscription Request 2969 The following groups of attributes are part of the Renew-Subscription 2970 Request: 2972 Group 1: Operation Attributes 2974 Natural Language and Character Set: 2975 The "attributes-charset" and "attributes-natural-language" 2976 attributes as described in [RFC2911] section 3.1.4.1. 2978 Target: 2979 The "printer-uri" attribute which defines the target for this 2980 operation as described in [RFC2911] section 3.1.5. 2982 "notify-subscription-id" (integer (1:MAX)): 2983 The client MUST supply this attribute. The Printer MUST 2984 support this attribute. This attribute specifies the Per- 2985 Printer Subscription Object whose lease the Printer MUST renew. 2986 If the client omits this attribute, the Printer MUST reject 2987 this request with the 'client-error-bad-request' status code. 2989 Requesting User Name: 2990 The "requesting-user-name" (name(MAX)) attribute SHOULD be 2991 supplied by the client as described in [RFC2911] section 8.3. 2993 Group 2: Subscription Template Attributes 2995 "notify-lease-duration" (integer(0:MAX)): 2996 The client MAY supply this attribute. It indicates the number 2997 of seconds to renew the lease for the specified Subscription 2998 Object. A value of 0 requests an infinite lease (which MAY 2999 require Operator access rights). If the client omits this 3000 attribute, the Printer MUST use the value of the Printer's 3001 "notify-lease-duration-default" attribute. See section 5.3.7 3002 for more details. 3004 11.2.5.2 Renew-Subscription Response 3006 The Printer returns the following sets of attributes as part of the 3007 Renew-Subscription Response: 3009 Group 1: Operation Attributes 3010 Status Message: 3011 Same as [RFC2911]. 3013 The following are some of the status codes returned: 3015 successful-ok: The operation successfully renewed the lease on the 3016 Subscription Object for the requested duration.. 3017 successful-ok-ignored-or-substituted-attributes: The operation 3018 successfully renewed the lease on the Subscription Object for 3019 some duration other than the amount requested. 3020 client-error-not-possible: The operation failed because the 3021 "notify-subscription-id" Operation attribute identified a Per- 3022 Job Subscription Object. 3023 client-error-not-found: The operation failed because the "notify- 3024 subscription-id" Operation attribute identified a non-existent 3025 Subscription Object. 3027 Natural Language and Character Set: 3028 The "attributes-charset" and "attributes-natural-language" 3029 attributes as described in [RFC2911] section 3.1.4.2. The 3030 "attributes-natural-language" MAY be the natural language of 3031 the Subscription Object, rather than the one requested. 3033 Group 2: Unsupported Attributes 3035 See [RFC2911] section 3.1.7 for details on returning 3036 Unsupported Attributes. 3038 Group 3: Subscription Attributes 3040 The Printer MUST return the following Subscription Attribute: 3042 "notify-lease-duration" (integer(0:MAX)): 3043 The value of this attribute MUST be the number of seconds that 3044 the Printer has granted for the lease of the Subscription 3045 Object (see section 5.3.7 for details, such as the value of 3046 this attribute when the Printer doesn't support the requested 3047 value). 3049 11.2.6 Cancel-Subscription operation 3051 This operation allows a client to delete a Subscription Object and 3052 stop the Printer from sending more Event Notifications. Once 3053 performed, there is no way to reference the Subscription Object. 3055 A Printer MUST supported this operation. 3057 The Printer MUST accept this request in any of the target Printer's 3058 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 3059 the Printer's "printer-state" attribute. 3061 If the specified Subscription Object is a Per-Job Subscription 3062 Object, the Printer MUST accept this request in any of the target 3063 Job's states, but MUST NOT change the Job's "job-state" attribute or 3064 affect the Job. 3066 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3067 performing this operation MUST either be the owner of the 3068 Subscription Object or have Operator or Administrator access rights 3069 for the Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the 3070 Printer MUST reject the operation and return: the 'client-error- 3071 forbidden', 'client-error-not-authenticated', or 'client-error-not- 3072 authorized' status code as appropriate. 3074 Note: There is no way to change any attributes on a Subscription 3075 Object, except the "notify-lease-duration" attribute (using the 3076 Renew-Subscription operation). In order to change other attributes, 3077 a client performs a Subscription Creation Operation and Cancel- 3078 Subscription operation on the old Subscription Object. If the client 3079 wants to avoid missing Event Notifications, it performs the 3080 Subscription Creation Operation first. If this order would create too 3081 many Subscription Objects on the Printer, the client reverses the 3082 order. 3084 11.2.6.1 Cancel-Subscription Request 3086 The following groups of attributes are part of the Cancel- 3087 Subscription Request: 3089 Group 1: Operation Attributes 3091 Natural Language and Character Set: 3092 The "attributes-charset" and "attributes-natural-language" 3093 attributes as described in [RFC2911] section 3.1.4.1. 3095 Target: 3096 The "printer-uri" attribute which defines the target for this 3097 operation as described in [RFC2911] section 3.1.5. 3099 "notify-subscription-id" (integer (1:MAX)): 3100 The client MUST supply this attribute. The Printer MUST 3101 support this attribute. This attribute specifies the 3102 Subscription Object that the Printer MUST cancel. If the client 3103 omits this attribute, the Printer MUST reject this request with 3104 the 'client-error-bad-request' status code. 3106 Requesting User Name: 3107 The "requesting-user-name" attribute SHOULD be supplied by the 3108 client as described in [RFC2911] section 8.3. 3110 11.2.6.2 Cancel-Subscription Response 3112 The Printer returns the following sets of attributes as part of the 3113 Cancel-Subscription Response: 3115 Group 1: Operation Attributes 3117 Status Message: 3118 Same as [RFC2911]. 3120 The following are some of the status codes returned: 3122 successful-ok: The operation successfully canceled (deleted) the 3123 Subscription Object.. 3124 client-error-not-found: The operation failed because the "notify- 3125 subscription-id" Operation attribute identified a non-existent 3126 Subscription Object. 3128 Natural Language and Character Set: 3129 The "attributes-charset" and "attributes-natural-language" 3130 attributes as described in [RFC2911] section 3.1.4.2. The 3131 "attributes-natural-language" MAY be the natural language of 3132 the Subscription Object, rather than the one requested. 3134 Group 2: Unsupported Attributes 3136 See [RFC2911] section 3.1.7 for details on returning 3137 Unsupported Attributes. 3139 12 Conformance Requirements 3141 It is OPTIONAL to implement this Event Notification specification. 3143 If this Event Notification specification is implemented, Printers 3144 MUST: 3146 1.meet the Conformance Requirements detailed in section 5 of 3147 [RFC2911]. 3149 2.support the Subscription Template Attributes Group in requests 3150 and the Subscription Attributes Group in responses. 3152 3.support all of the following attributes: 3154 a. REQUIRED Subscription Object attributes in section 5. 3156 b. REQUIRED Printer Description object attributes in section 6. 3157 c. REQUIRED attributes in Event Notification content in section 3158 8. 3160 4.send Event Notifications that conform to the requirements of the 3161 Delivery Method Document for each supported Delivery Method (the 3162 conformance requirements for Delivery Method Documents is 3163 specified in section 10). 3165 5.support all operations as described in Table 16: 3167 Table 16 - Conformance Requirements for Operations 3169 Operation Conformance 3170 requirements 3172 Create-Printer-Subscriptions (section 11.1.2) REQUIRED 3174 Create-Job-Subscriptions (section 11.1.1) OPTIONAL 3176 Get-Subscription-Attributes (section 11.2.2) REQUIRED 3178 Get-Subscriptions (section 11.2.4) REQUIRED 3180 Renew-Subscription (section 11.2.5) REQUIRED 3182 Cancel-Subscription (section 11.2.6) REQUIRED 3184 13 IANA Considerations 3186 This section contains the exact information for IANA to add to the 3187 IPP Registries according to the procedures defined in RFC 2911 3188 [RFC2911] section 6. 3190 Note to RFC Editors: Replace RFC NNNN below with the RFC number 3191 for this document, so that it accurately reflects the content of 3192 the information for the IANA Registry. 3194 13.1 Attribute Registrations 3196 The attributes defined in this document will be published by IANA 3197 according to the procedures in RFC 2911 [RFC2911] section 6.2 with 3198 the following path: 3200 ftp.isi.edu/iana/assignments/ipp/attributes/ 3202 The registry entry will contain the following information: 3204 Subscription Template attributes: Ref. Section: 3205 notify-recipient-uri (uri) RFC NNNN 5.3.1 3206 notify-events (1setOf type2 keyword) RFC NNNN 5.3.2 3207 notify-attributes (1setOf type2 keyword) RFC NNNN 5.3.3 3208 notify-user-data (octetString(63)) RFC NNNN 5.3.4 3209 notify-charset (charset) RFC NNNN 5.3.5 3210 notify-natural-language (naturalLanguage) RFC NNNN 5.3.6 3211 notify-lease-duration (integer(0:67108863)) RFC NNNN 5.3.7 3212 notify-time-interval (integer(0:MAX)) RFC NNNN 5.3.8 3214 Subscription Description Attributes: 3215 notify-subscription-id (integer (1:MAX))) RFC NNNN 5.4.1 3216 notify-sequence-number (integer (0:MAX))) RFC NNNN 5.4.2 3217 notify-lease-expiration-time (integer(0:MAX))) RFC NNNN 5.4.3 3218 notify-printer-up-time (integer(1:MAX))) RFC NNNN 5.4.4 3219 notify-printer-uri (uri)) RFC NNNN 5.4.5 3220 notify-job-id (integer(1:MAX))) RFC NNNN 5.4.6 3221 notify-subscriber-user-name (name(MAX))) RFC NNNN 5.4.7 3223 Printer Description Attributes: 3224 printer-state-change-time (integer(1:MAX))) RFC NNNN 6.1 3225 printer-state-change-date-time (dateTime)) RFC NNNN 6.2 3227 Attributes Only in Event Notifications 3228 notify-subscribed-event (type2 keyword) RFC NNNN 8.1 3229 notify-text (text(MAX)) RFC NNNN 8.2 3231 13.2 Keyword Attribute Value Registrations 3233 The keyword attribute values defined in this document will be 3234 published by IANA according to the procedures in RFC 2911 [RFC2911] 3235 section 6.1 with the following path: 3237 ftp.isi.edu/iana/assignments/ipp/attribute-values/ 3239 The registry entry will contain the following information: 3241 Keyword Attribute Values: Ref. Section: 3242 New Values for Existing Printer Description Attributes 3243 operations-supported (1setOf type2 enum) RFC NNNN 7.1 3245 13.3 Operation Registrations 3247 The operations defined in this document will be published by IANA 3248 according to the procedures in RFC 2911 [RFC2911] section 6.4 with 3249 the following path: 3251 ftp.isi.edu/iana/assignments/ipp/operations/ 3253 The registry entry will contain the following information: 3255 Operations: Ref. Section: 3256 Create-Job-Subscriptions Operation RFC NNNN 11.1.1 3257 Create-Printer-Subscriptions operation RFC NNNN 11.1.2 3258 Job Creation Operations - Extensions RFC NNNN 11.1.3 3259 Validate-Job Operation - Extensions RFC NNNN 11.2.1 3260 Get-Printer-Attributes - Extensions RFC NNNN 11.2.2 3261 Get-Subscription-Attributes operation RFC NNNN 11.2.3 3262 Get-Subscriptions operation RFC NNNN 11.2.4 3263 Renew-Subscription operation RFC NNNN 11.2.5 3264 Cancel-Subscription operation RFC NNNN 11.2.6 3266 13.4 Status code Registrations 3268 The status codes defined in this document will be published by IANA 3269 according to the procedures in RFC 2911 [RFC2911] section 6.6 with 3270 the following path: 3272 ftp.isi.edu/iana/assignments/ipp/status-codes/ 3274 The registry entry will contain the following information: 3276 Status codes: Ref. Section: 3277 successful-ok-ignored-subscriptions (0x0003) RFC NNNN 16.1 3278 client-error-ignored-all-subscriptions (0x0414) RFC NNNN 16.2 3280 Status Codes in Subscription Attributes Groups: 3281 client-error-uri-scheme-not-supported (0x040C) RFC NNNN 17.1 3282 client-error-too-many-subscriptions (0x0415) RFC NNNN 17.2 3283 successful-ok-too-many-events (0x0005) RFC NNNN 17.3 3284 successful-ok-ignored-or-substituted-attributes (0x0001) 3285 RFC NNNN 17.4 3287 13.5 Attribute Group tag Registrations 3289 The attribute group tags defined in this document will be published 3290 by IANA according to the procedures in RFC 2911 [RFC2911] section 6.5 3291 with the following path: 3293 ftp.isi.edu/iana/assignments/ipp/attribute-group-tags/ 3295 The registry entry will contain the following information: 3297 Attribute Group Tags: Ref. Section: 3298 subscription-attributes-tag RFC NNNN 18 3299 event-notification-attributes-tag RFC NNNN 18 3301 13.6 Format for Event Notification Delivery Method Registration 3302 proposals 3304 This section describes the procedures for registering Event 3305 Notification Delivery Method proposals with IANA to be used with this 3306 document. Such Delivery Method proposals that require a new URL 3307 scheme MUST be IETF standards track documents according to RFC 2717 3308 [RFC2717]. 3310 13.7 Format and Requirements for IPP Delivery Method Registration 3311 Proposals 3313 This section defines the format and requirements for an IPP Event 3314 Notification Delivery Method Registration Proposal. A Delivery 3315 Method Registration Proposal: 3317 1.MUST contain the following information: 3319 Type of registration: IPP Event Notification Delivery Method 3320 Name of this delivery method: 3321 Proposed URL scheme name of this delivery method: 3322 Name of proposer: 3323 Address of proposer: 3324 Email address of proposer: 3325 Is this delivery method REQUIRED or OPTIONAL for conformance to 3326 the IPP Event Notification Specification document: 3327 Is this delivery method defining Machine Consumable and/or Human 3328 Consumable content: 3330 2.MUST meet the conformance requirements for Delivery Method 3331 Documents specified in section 10. 3333 14 Internationalization Considerations 3335 This IPP Notification specification continues support for the 3336 internationalization of [RFC2911] of attributes containing text 3337 strings and names. Allowing a Subscribing Client to specify a 3338 different natural language and charset for each Subscription Object 3339 increases the internationalization support. 3341 The Printer MUST be able to localize the content of Human Consumable 3342 Event Notifications and to localize the value of "notify-text" 3343 attribute in Machine Consumable Event Notifications that it sends to 3344 Notification Recipients. For localization, the Printer MUST use the 3345 value of the "notify-charset" attribute and the "notify-natural- 3346 language" attribute in the Subscription Object supplied by the 3347 Subscribing Client. 3349 15 Security Considerations 3351 By far the biggest security concern is the abuse of notification: 3352 sending unwanted Event Notifications to third parties (i.e., spam). 3353 The problem is made worse by notification addresses that may be 3354 redistributed to multiple parties (e.g., mailing lists). There exist 3355 scenarios where third party notification is required (see Scenario #2 3356 and #3 in [ipp-not-req]). The fully secure solution would require 3357 active agreement of all recipients before sending out anything. 3358 However, requirement #9 in [ipp-req] ("There is no requirement for 3359 IPP Printer receiving the print request to validate the identity of 3360 an Event recipient") argues against this. Certain systems may decide 3361 to disallow third party Event Notifications (a traditional fax 3362 model). 3364 Clients submitting Notification requests to the IPP Printer has the 3365 same security issues as submitting an IPP/1.1 print job request. The 3366 same mechanisms used by IPP/1.1 can therefore be used by the client 3367 Notification submission. Operations that require authentication can 3368 use the HTTP authentication. Operations that require privacy can use 3369 the HTTP/TLS privacy. 3371 The Notification access control model should be similar to the IPP 3372 access control model for Jobs. Creating a Per-Printer Subscription 3373 Object is associated with a user. Only the creator or an Operator 3374 can cancel the Subscription Object. The system may limit the listing 3375 of items to only those items owned by the user. Some Subscription 3376 Objects (e.g., those that have a lifetime longer than a job) can be 3377 done only by privileged users (users having Operator and/or 3378 Administrator access rights), if that is the authorization policy. 3380 The standard security concerns (delivery to the right user, privacy 3381 of content, tamper proof content) apply to the Delivery Method. IPP 3382 should use the security mechanism of the Delivery Method used. Some 3383 delivery mechanisms are more secure than others. Therefore, 3384 sensitive Event Notifications should use the Delivery Method that has 3385 the strongest security. 3387 16 Status Codes 3389 The following status codes are defined as extensions for Notification 3390 and are returned as the value of the "status-code" parameter in the 3391 Operation Attributes Group of a response (see [RFC2911] section 3392 3.1.6.1). Operations in this document can also return the status 3393 codes defined in section 13 of [RFC2911]. The 'successful-ok' status 3394 code is an example of such a status code. 3396 16.1 successful-ok-ignored-subscriptions (0x0003) 3398 The Subscription Creation Operation was unable to create all 3399 requested Subscription Objects. 3401 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3402 operation, this status code means that the Printer created one or 3403 more Subscription Objects, but not all requested Subscription 3404 Objects. 3406 For a Job Creation operation, this status code means that the Printer 3407 created the Job along with zero or more Subscription Objects. The 3408 Printer returns this status code even if other job attributes are 3409 unsupported or in conflict. That is, if an IPP Printer finds a 3410 warning that would allow it to return 'successful-ok-ignored- 3411 subscriptions' and either 'successful-ok-ignored-or-substituted- 3412 attributes' and/or 'successful-ok-conflicting-attributes', it MUST 3413 return 'successful-ok-ignored-subscriptions'. 3415 16.2 client-error-ignored-all-subscriptions (0x0414) 3417 This status code is the same as 'successful-ok-ignored-subscriptions' 3418 except that only the Create-Job-Subscriptions and Create-Printer- 3419 Subscriptions operation return it. They return this status code only 3420 when the Printer creates zero Subscription Objects. 3422 17 Status Codes in Subscription Attributes Groups 3424 This section contains values of the "notify-status-code" (type2 enum) 3425 attribute that the Printer returns in a Subscription Attributes Group 3426 in a response when the corresponding Subscription Object: 3428 1.is not created or 3430 2.is created and some of the client-supplied attributes are not 3431 supported. 3433 The following sections are ordered in decreasing order of importance 3434 of the status-codes. 3436 17.1 client-error-uri-scheme-not-supported (0x040C) 3438 This status code is defined in [RFC2911]. This document extends its 3439 meaning and allows it to be in a Subscription Attributes Group of a 3440 response. 3442 The scheme of the client-supplied URI in a "notify-recipient-uri" 3443 Subscription Template Attribute in a Subscription Creation Operation 3444 is not supported. See section 0. 3446 17.2 client-error-too-many-subscriptions (0x0415) 3448 The number of Subscription Objects supported by the Printer would be 3449 exceeded if this Subscription Object were created (see section 5.2). 3451 17.3 successful-ok-too-many-events (0x0005) 3453 The client supplied more Events in the "notify-events" operation 3454 attribute of a Subscription Creation Operation than the Printer 3455 supports, as indicated in its "notify-max-events-supported" Printer 3456 attribute (see section 5.3.2). 3458 17.4 successful-ok-ignored-or-substituted-attributes (0x0001) 3460 This status code is defined in [RFC2911]. This document extends its 3461 meaning to include unsupported Subscription Template Attributes and 3462 it can appear in a Subscription Attributes Group. 3464 18 Encodings of Additional Attribute Tags 3466 This section assigns values to two attributes tags as extensions to 3467 the encoding defined in [RFC2910]). 3469 The "subscription-attributes-tag" delimits Subscription Template 3470 Attributes Groups in requests and Subscription Attributes Groups in 3471 responses. 3473 The "event-notification-attributes-tag" delimits Event Notifications 3474 in Delivery Methods that use an IPP-like encoding. 3476 The following table specifies the values for the delimiter tags: 3478 Tag Value (Hex) Meaning 3480 0x06 "subscription-attributes-tag" 3482 0x07 "event-notification-attributes-tag" 3484 19 References 3486 [IANA-CON] 3487 Narte, T. and Alvestrand, H.T.: Guidelines for Writing an IANA 3488 Considerations Section in RFCs, Work in Progress, draft-iesg-iana- 3489 considerations-04.txt, May 21, 1998. 3491 [ipp-not-req] 3492 deBry, R., Lewis, H., Hastings, T., "Internet Printing 3493 Protocol/1.1: Requirements for IPP Notifications", , work in progress, January 23, 2001. 3496 [ipp-prog] 3497 Hastings, T., Bergman, R., Lewis, H., "IPP: Job Progress 3498 Attributes", work in 3499 progress, January 23, 2001. 3501 [ipp-set] 3502 Kugler, C., Hastings, T., Herriot, R., Lewis, H, "Internet Printing 3503 Protocol (IPP): Job and Printer Set Operations", , work in progress, January 22, 2001. 3506 [RFC2026] 3507 S. Bradner, "The Internet Standards Process -- Revision 3", RFC 3508 2026, October 1996. 3510 [RFC2119] 3511 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3512 Levels", RFC 2119 , March 1997 3514 [RFC2566] 3515 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3516 "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, 3517 April 1999. 3519 [RFC2567] 3520 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3521 2567, April 1999. 3523 [RFC2568] 3524 Zilles, S., "Rationale for the Structure and Model and Protocol for 3525 the Internet Printing Protocol", RFC 2568, April 1999. 3527 [RFC2569] 3528 Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between 3529 LPD and IPP Protocols", RFC 2569, April 1999. 3531 [RFC2717] 3532 R. Petke and I. King, "Registration Procedures for URL Scheme 3533 Names", RFC 2717, November 1999. 3535 [RFC2910] 3536 Herriot, R., Butler, S., Moore, P., Turner, R., "Internet Printing 3537 Protocol/1.1: Encoding and Transport", RFC 2910, September 2000. 3539 [RFC2911] 3540 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3541 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 3542 September 2000. 3544 20 Author's Addresses 3546 Robert Herriot 3547 Xerox Corporation 3548 3400 Hillview Ave., Bldg #1 3549 Palo Alto, CA 94304 3551 Phone: 650-813-7696 3552 Fax: 650-813-6860 3553 Email: robert.herriot@pahv.xerox.com 3555 Tom Hastings 3556 Xerox Corporation 3557 737 Hawaii St. ESAE 231 3558 El Segundo, CA 90245 3560 Phone: 310-333-6413 3561 Fax: 310-333-5514 3562 e-mail: hastings@cp10.es.xerox.com 3564 Scott A. Isaacson 3565 Novell, Inc. 3566 122 E 1700 S 3567 Provo, UT 84606 3569 Phone: 801-861-7366 3570 Fax: 801-861-2517 3571 e-mail: sisaacson@novell.com 3573 Roger deBry 3574 Utah Valley State College 3575 Orem, UT 84058 3577 Phone: (801) 222-8000 3578 EMail: debryro@uvsc.edu 3580 Jay Martin 3581 Underscore Inc. 3582 9 Jacqueline St. 3583 Hudson, NH 03051-5308 3584 603-889-7000 3585 fax: 775-414-0245 3586 e-mail: jkm@underscore.com 3588 Michael Shepherd 3589 Xerox Corporation 3590 800 Phillips Road MS 128-51E 3591 Webster, NY 14450 3593 Phone: 716-422-2338 3594 Fax: 716-265-8871 3595 e-mail: mshepherd@crt.xerox.com 3597 Ron Bergman 3598 Hitachi Koki Imaging Solutions 3599 1757 Tapo Canyon Road 3600 Simi Valley, CA 93063-3394 3602 Phone: 805-578-4421 3603 Fax: 805-578-4001 3604 Email: rbergma@hitachi-hkis.com 3606 A. Appendix - Model for Notification with Cascading Printers 3608 With this model (see Figure 2), there is an intervening Print server 3609 between the human user and the output-device. So the system 3610 effectively has two Printers. There are two cases to consider. 3612 1.When the Printer 1 (in the server) generates Events, the system 3613 behaves like the client and Printer in Figure 1. In this case, 3614 Printer 1 sends Event Notifications that are shown as Event 3615 Notifications (A) of Figure 2,. 3617 2.When the Printer 2 (in the output-device) generates Events, there 3618 are two possible system configurations: 3620 a)Printer 1 forwards the client-supplied Subscription Creation 3621 Operations to the downstream Printer 2 and lets Printer 2 send 3622 the Event Notifications directly to the Notification Recipients 3623 supplied by the Client (Event Notifications(C) in the diagram). 3625 b)Printer 1 performs the client-supplied Subscription Creation 3626 Operations and also forwards the Subscription Creation 3627 Operations to Printer 2 with the Notification Recipient changed 3628 to be the Printer 1. When an Event occurs in Printer 2, Printer 3629 2 sends the Event Notification (B) to Notification Recipient of 3630 Printer 1, which relays the received Event Notification (B) to 3631 the client-supplied Notification Recipient (as Event 3632 Notifications(A) in the diagram). Note, when a client performs a 3633 Subscription Creation Operation, Printer 1 need not forward the 3634 Subscription Creation Operation to Printer 2 if it would create 3635 a duplicate Subscription Object on Printer 2. 3637 Note: when Printer 1 is forwarding Subscription Creation Operations 3638 to Printer 2, it may request Printer 2 to create additional 3639 Subscription Objects (called "piggy-backing"). Piggy-backing is 3640 useful when: 3642 . Device A is configured to accept (IPP or non-IPP) requests from 3643 other servers. 3645 . Server S wants to receive Job Events that the client didn't 3646 request and Server S wants these Events for jobs it submits and 3647 not for other jobs. 3649 server S device A 3650 +------------+ +------------+ 3651 | | | | 3652 +--------+ Subscription | ###########| | ###########| 3653 | client |--Creation ----># Printer #| Subscription | # Printer #| 3654 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 3655 | ###|#######| Operation | ####|#|####| 3656 +----|---^---+ +-----|-|----+ 3657 +--------+ Event | | | | 3658 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 3659 |ation Re|<-------------Event Notifications(C)-----------------+ 3660 |cipient | 3661 +--------+ 3663 Figure 2 - Model for Notification with Cascading Printers 3665 B. Appendix - Distributed Model for Notification 3667 A Printer implementation could use some other remote notification 3668 service to provide some or most of the service. For example, the 3669 remote notification service could send Event Notifications using 3670 Delivery Methods that are not directly supported by the output device 3671 or server. Or, the remote notification service could store 3672 Subscription Objects (passed to it from the output device in response 3673 to Subscription Creation requests), accept Events, format the Event 3674 Notification in the natural language of the Notification Recipient, 3675 and send the Event Notifications to the Notification Recipient(s). 3677 Figure 3 shows this partitioning. The interface between the output 3678 device (or server) and the remote notification service is outside the 3679 scope of this document and is intended to be transparent to the 3680 client and this document. The combination of the output device (or 3681 server) and the notification service together constitute an IPP 3682 Printer conforming to this Notification document. 3684 *********************** 3685 * 3686 * Printer (including 3687 * the distributed 3688 * Notification Service) 3689 * 3690 * output device or server 3691 * +---------------+ 3692 PDA, desktop, or server * + ########### + 3693 +--------+ * | # partial # | 3694 | client |---IPP Subscription--------># Printer # | 3695 +--------+ Creation operation * | # Object # | 3696 * | #####|##### | 3697 * +-------|-------+ 3698 * | Subscriptions 3699 * | OR Event 3700 +------------+ * | Notifications 3701 |Notification| IPP-defined * +------v--------+ 3702 |Recipient |<--Event Notifications---| Notification | 3703 +------------+ * | Service | 3704 * +---------------+ 3705 * 3706 ************************* 3707 *** = Implementation configuration opaque boundary 3709 Figure 3 - Opaque Use of a Notification Service Transparent to the 3710 Client 3712 C. Appendix - Extended Notification Recipient 3714 The model allows for an extended Notification Recipient that is 3715 itself a notification service that forwards each Event Notification 3716 to another recipient (called the Ultimate Notification Recipient in 3717 this section). The Delivery Method to the Ultimate Recipient is 3718 probably different from the Delivery Method used by the Printer to 3719 the extended Notification Recipient. 3721 This extended Notification Recipient is transparent to the Printer 3722 but not to the client. 3724 When a client performs a Subscription Creation Operation, it 3725 specifies the extended Notification Recipient as it would any 3726 Notification Recipient. In addition, the client specifies the 3727 Ultimate Notification Recipient in the Subscription Creation 3728 Operation in a manner specified by the extended Notification 3729 Recipient. Typically, it is either some bytes in the value of 3730 "notify-user-data" or some additional parameter in the value of 3731 "notify-recipient-uri". The client also subscribes directly with the 3732 extended Notification Recipient (by means outside this document), 3733 since it is a notification service in its own right. 3735 The IPP Printer treats the extended Notification Recipient like any 3736 other Notification Recipient and the IPP Printer is not aware of the 3737 forwarding. The Delivery Method that the extended Notification 3738 Recipient uses for delivering the Event Notification to the Ultimate 3739 Notification Recipient is beyond the scope of this document and is 3740 transparent to the IPP Printer. 3742 Examples of this extended Notification Recipient are paging, 3743 immediate messaging services, general notification services, and NOS 3744 vendors' infrastructure. Figure 4 shows this approach. 3746 PDA, desktop, or server server or output device 3747 +---------------+ 3748 +--------+ | ########### | 3749 | client |---Subscription Creation -----------># Printer # | 3750 +--------+ Operation | # Object # | 3751 | #####|##### | 3752 +------------+ +------------+ IPP-defined +-------|-------+ 3753 |Ultimate | any |Notification|<--Event Notifications----+ 3754 |Notification|<----|Recipient | 3755 |Recipient | +------------+ 3756 +------------+ (Notification Service) 3758 Figure 4 - Use of an Extended Notification Recipient transparent to 3759 the Printer 3761 D. Appendix - Details about Conformance Terminology 3763 The following paragraph provide more details about conformance 3764 terminology. 3766 REQUIRED - an adjective used to indicate that a conforming IPP 3767 Printer implementation MUST support the indicated operation, 3768 object, attribute, attribute value, status code, or out-of-band 3769 value in requests and responses. See [RFC2911] "Appendix A - 3770 Terminology for a definition of "support". Since support of this 3771 entire Notification specification is OPTIONAL for conformance to 3772 IPP/1.0 or IPP/1.1, the use of the term REQUIRED in this document 3773 means "REQUIRED if this OPTIONAL Notification specification is 3774 implemented". 3776 RECOMMENDED - an adjective used to indicate that a conforming IPP 3777 Printer implementation is recommended to support the indicated 3778 operation, object, attribute, attribute value, status code, or 3779 out-of-band value in requests and responses. Since support of 3780 this entire Notification specification is OPTIONAL for conformance 3781 to IPP/1.0 or IPP/1.1, the use of the term RECOMMENDED in this 3782 document means "RECOMMENDED if this OPTIONAL Notification 3783 specification is implemented". 3785 OPTIONAL - an adjective used to indicate that a conforming IPP 3786 Printer implementation MAY, but is NOT REQUIRED to, support the 3787 indicated operation, object, attribute, attribute value, status 3788 code, or out-of-band value in requests and responses. 3790 E. Appendix - Object Model for Notification 3792 This section describes the Notification object model that adds a 3793 Subscription Object which together with the Job and Printer object 3794 provide the complete Notification semantics. 3796 The object relationships can be seen pictorially as: 3798 Subscription Objects (Per-Printer Subscriptions) Printer object 3799 +----+ +------------+ 3800 | s1 |<--------------------------------------------->| | 3801 +----++ | | 3802 | s2 |<-------------------------------------------->| p1 | 3803 +----++ | | 3804 | s3 |<------------------------------------------->| | 3805 +----+ +------------+ 3806 Job objects 3807 +---------+ 3808 | | 3809 +----+ | j1 | 3810 | s4 |<------->| | 3811 +----+ | | 3812 | | s4 is a Per-Job Subscription Object 3813 ++--------++ 3814 | | 3815 +----+ | j2 | 3816 | s5 |<------>| | 3817 +----++ | | 3818 | s6 |<----->| | s5 and s6 are Per-Job Subscription 3819 +----+ ++--------++ Objects 3820 | | 3821 | j3 | 3822 | | 3823 | | <----> indicates association 3824 +---------+ 3826 Figure 5 - Object Model for Notification 3828 s1, s2, and s3 are Per-Printer Subscription Objects and can 3829 identify Printer and/or Job Events. 3830 s4, s5, and s6 are Per-Job Subscription Objects and can identify 3831 Printer and/or Job Events. 3833 E.1 Appendix - Object relationships 3835 This sub-section defines the object relationships between the 3836 Printer, Job, and Subscription Objects by example. Whether Per- 3837 Printer Subscription Objects are actually contained in a Printer 3838 object or are just bi-directionally associated with them in some way 3839 is IMPLEMENTATION DEPENDENT and is transparent to the client. 3840 Similarly, whether Per-Job Subscription Objects are actually 3841 contained in a Job object or are just bi-directionally associated 3842 with them in some way is IMPLEMENTATION DEPENDENT and is transparent 3843 to the client. The object relationships are defined as follows: 3845 E.2 Printer Object and Per-Printer Subscription Objects 3847 1.The Printer object contains (is associated with) zero or more 3848 Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer 3849 Subscription Objects). 3851 2.Each Per-Printer Subscription Object (s1, s2, and s3) is 3852 contained in (or is associated with) exactly one Printer object 3853 (p1). 3855 E.3 Job Object and Per-Job Subscription Objects 3857 1.A Job object (j1, j2, j3) is associated with zero or more Per- 3858 Job Subscription Objects (s4-s6). Job j1 is associated with 3859 Per-Job Subscription Object s4, Job j2 is associated with Per- 3860 Job Subscription Objects s5 and s6, and Job j3 is not associated 3861 with any Per-Job Subscription Object. 3863 2.Each Per-Job Subscription Object is associated with exactly one 3864 Job object. 3866 F. Appendix - Per-Job versus Per-Printer Subscription Objects 3868 Per-Job and Per-Printer Subscription Objects are quite similar. 3869 Either type of Subscription Object can subscribe to Job Events, 3870 Printer Events, or both. Both types of Subscription Objects can be 3871 queried using the Get-Subscriptions and Get-Subscription-Attributes 3872 operations and canceled using the Cancel-Subscription operation. 3873 Both types of Subscription Objects create Subscription Objects which 3874 have the same Subscription Object attributes defined. However, there 3875 are some semantic differences between Per-Job Subscription Objects 3876 and Per-Printer Subscription Objects. A Per-Job Subscription Object 3877 is established by the client when submitting a job and after creating 3878 the job using the Create-Job-Subscriptions operation by specifying 3879 the "job-id" of the Job with the "notify-job-id" attribute. A Per- 3880 Printer Subscription Object is established between a client and a 3881 Printer using the Create-Printer-Subscriptions operation. Some 3882 specific differences are: 3884 1.A client usually creates one or more Per-Job Subscription 3885 Objects as part of the Job Creation operations (Create-Job, 3886 Print-Job, and Print-URI), rather than using the OPTIONAL 3887 Create-Job-Subscriptions operation, especially since Printer 3888 implementations NEED NOT support the Create-Job-Subscriptions 3889 operation, since it is OPTIONAL. 3891 2.For Per-Job Subscription Objects, the Subscription Object is 3892 only valid while the job is "not-complete" (see sections 5.4.3) 3893 while for the Per-Printer Subscription Objects, the Subscription 3894 Object is valid until the time (in seconds) that the Printer 3895 returned in the "notify-lease-expiration-time" operation 3896 attribute. 3898 3.Job Events in a Per-Job Subscription Object apply only to "one 3899 job" (the Job created by the Job Creation operation or 3900 references by the Create-Job-Subscriptions operation) while Job 3901 Events in a Per-Printer Subscription Object apply to ALL jobs 3902 contained in the IPP Printer. 3904 G. Appendix: Full Copyright Statement 3906 Copyright (C) The Internet Society (1998,1999,2000,2001). All Rights 3907 Reserved 3909 This document and translations of it may be copied and furnished to 3910 others, and derivative works that comment on or otherwise explain it 3911 or assist in its implementation may be prepared, copied, published 3912 and distributed, in whole or in part, without restriction of any 3913 kind, provided that the above copyright notice and this paragraph are 3914 included on all such copies and derivative works. However, this 3915 document itself may not be modified in any way, such as by removing 3916 the copyright notice or references to the Internet Society or other 3917 Internet organizations, except as needed for the purpose of 3918 developing Internet standards in which case the procedures for 3919 copyrights defined in the Internet Standards process must be 3920 followed, or as required to translate it into languages other than 3921 English. 3923 The limited permissions granted above are perpetual and will not be 3924 revoked by the Internet Society or its successors or assigns. 3926 This document and the information contained herein is provided on an 3927 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3928 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3929 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3930 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3931 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.