idnits 2.17.1 draft-ietf-ipp-not-spec-04.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? ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard 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-PRO], [IPP-IIG], [IPP-MOD], [RFC2567]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 2 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 1100 has weird spacing: '...ccepted a Job...' == Line 1417 has weird spacing: '...ipients do no...' == Line 2401 has weird spacing: '...rameter retur...' == Line 3691 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 default "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: This attribute MUST not effect any Events other than 'job-progress'. == 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. -- 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 (July 13, 2000) is 8688 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-MOD' is mentioned on line 2968, but not defined == Missing Reference: 'IPP-PRO' is mentioned on line 63, but not defined == Missing Reference: 'IPP-IIG' is mentioned on line 64, but not defined == Unused Reference: 'RFC2566' is defined on line 3330, 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 Summary: 10 errors (**), 0 flaws (~~), 18 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 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 July 13, 2000 17 Internet Printing Protocol (IPP): 18 IPP Event Notification Specification 20 Copyright (C) The Internet Society (2000). All Rights Reserved. 22 Status of this Memo 24 This document is an Internet-Draft and is in full conformance with all 25 provisions of Section 10 of [RFC2026]. Internet-Drafts are working 26 documents of the Internet Engineering Task Force (IETF), its areas, and 27 its working groups. Note that other groups may also distribute working 28 documents as Internet-Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference material 33 or to cite them other than as "work in progress". 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt 38 The list of Internet-Draft Shadow Directories can be accessed as 39 http://www.ietf.org/shadow.html. 41 Abstract 43 This document describes an extension to the IPP/1.0, IPP/1.1, and future 44 versions. This extension allows a client to subscribe to printing 45 related Events. Subscriptions are modeled as Subscription Objects. The 46 Subscription Object specifies that when one of the specified Event 47 occurs, the Printer sends an asynchronous Event Notification to the 48 specified Notification Recipient via the specified Delivery Method 49 (i.e., protocol). A client associates Subscription Objects with a 50 particular Job by performing the Create-Job-Subscriptions operation or 51 by submitting a Job with subscription information. A client associates 52 Subscription Objects with the Printer by performing a Create-Printer- 53 Subscriptions operation. Four other operations are defined for 54 Subscription Objects: Get-Subscriptions-Attributes, Get-Subscriptions, 55 Renew-Subscription, and Cancel-Subscription. 57 The full 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 [IPP-MOD] 63 Internet Printing Protocol/1.1: Encoding and Transport [IPP-PRO] 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 are 73 satisfied in IPP/1.0. Operator and Administrator requirements are out 74 of scope for version 1.0. A few OPTIONAL Operator operations have been 75 added to IPP/1.1. 77 The "Rationale for the Structure and Model and Protocol for the Internet 78 Printing Protocol" document describes IPP from a high level view, 79 defines a roadmap for the various documents that form the suite of IPP 80 specifications, and gives background and rationale for the IETF working 81 group's major decisions. 83 The "Internet Printing Protocol/1.1: Model and Semantics", describes a 84 simplified model with abstract objects, their attributes, and their 85 operations that are independent of encoding and transport. It introduces 86 a Printer object and a Job object. The Job object optionally supports 87 multiple documents per Job. It also addresses security, 88 internationalization, and directory issues. 90 The "Internet Printing Protocol/1.1: Encoding and Transport" document is 91 a formal mapping of the abstract operations and attributes defined in 92 the model document onto HTTP/1.1. It defines the encoding rules for a 93 new Internet MIME media type called "application/ipp". This document 94 also defines the rules for transporting over HTTP a message body whose 95 Content-Type is "application/ipp". This document defines a new scheme 96 named 'ipp' for identifying IPP printers and jobs. Finally, this 97 document defines interoperability rules for supporting IPP/1.0 clients. 99 The "Internet Printing Protocol/1.1: Implementer's Guide" document gives 100 insight and advice to implementers of IPP clients and IPP objects. It 101 is intended to help them understand IPP/1.0 and some of the 102 considerations that may assist them in the design of their client and/or 103 IPP object implementations. For example, a typical order of processing 104 requests is given, including error checking. Motivation for some of the 105 specification decisions is also included. 107 The "Mapping between LPD and IPP Protocols" document gives some advice 108 to implementers of gateways between IPP and LPD (Line Printer Daemon) 109 implementations. 111 Table of Contents 113 1 Introduction .......................................................8 114 1.1 Notification Overview .........................................8 116 2 Models for Notification ...........................................11 117 2.1 Model for Notification (Simple Case) .........................11 118 2.2 Model for Notification with Cascading Printers ...............11 119 2.3 Distributed Model for Notification ...........................12 120 2.4 Extended Notification Recipient ..............................12 122 3 Terminology .......................................................13 123 3.1 Conformance Terminology ......................................13 124 3.2 Other Terminology ............................................13 126 4 Object Relationships ..............................................16 127 4.1 Printer and Per-Printer Subscription Objects .................16 128 4.2 Printer, Job and Per-Job Subscription Objects ................17 130 5 Subscription Object ...............................................17 131 5.1 Rules for Support of Subscription Template Attributes ........18 132 5.2 Rules for Processing Subscription Template Attributes ........19 133 5.3 Subscription Template Attributes .............................23 134 5.3.1 notify-recipient-uri (uri) ...............................24 135 5.3.2 notify-events (1setOf type2 keyword) .....................25 136 5.3.3 notify-attributes (1setOf type2 keyword) .................31 137 5.3.4 notify-user-data (octetString(63)) .......................32 138 5.3.5 notify-charset (charset) .................................33 139 5.3.6 notify-natural-language (naturalLanguage) ................34 140 5.3.7 notify-lease-duration (integer(0:67108863)) ..............34 141 5.3.8 notify-time-interval (integer(0:MAX)) ....................35 142 5.4 Subscription Description Attributes ..........................37 143 5.4.1 notify-subscription-id (integer (1:MAX)) ................37 144 5.4.2 notify-sequence-number (integer (0:MAX)) .................38 145 5.4.3 notify-lease-expiration-time (integer(0:MAX)) ............39 146 5.4.4 notify-printer-up-time (integer(1:MAX)) ..................39 147 5.4.5 notify-printer-uri (uri) .................................40 148 5.4.6 notify-job-id (integer(1:MAX)) ...........................40 149 5.4.7 notify-subscriber-user-name (name(MAX)) ..................41 151 6 Printer Description Attributes Related to Notification ............41 152 6.1 printer-state-change-time (integer(1:MAX)) ...................42 153 6.2 printer-state-change-date-time (dateTime) ....................42 155 7 New Values for Existing Printer Description Attributes ............43 156 7.1 operations-supported (1setOf type2 enum) .....................43 158 8 Attributes Only in Event Notifications ............................43 159 8.1 notify-subscribed-event (type2 keyword) ......................43 160 8.2 notify-text (text(MAX)) ......................................44 162 9 Event Notification Content ........................................44 163 9.1 Content of Machine Consumable Event Notifications ............46 164 9.1.1 Event Notification Content Common to All Events ..........47 165 9.1.2 Additional Event Notification Content for Job Events .....49 166 9.1.3 Additional Event Notification Content for Printer Events .50 167 9.2 Content of Human Consumable Event Notification ...............50 168 9.2.1 Event Notification Content Common to All Events ..........51 169 9.2.2 Additional Event Notification Content for Job Events .....53 170 9.2.3 Additional Event Notification Content for Printer Events .54 172 10 Delivery Methods .................................................55 174 11 Operations for Notification ......................................58 175 11.1 Subscription Creation Operations .............................58 176 11.1.1Create-Job-Subscriptions Operation .......................58 177 11.1.2Create-Printer-Subscriptions operation ...................61 178 11.1.3Job Creation Operation - Extensions for Notification .....62 179 11.2 Other Operations .............................................64 180 11.2.1Validate-Job Operation - Extensions for Notification .....64 181 11.2.2Get-Printer-Attributes - Extensions for Notification .....65 182 11.2.3Get-Subscription-Attributes operation ....................66 183 11.2.4Get-Subscriptions operation ..............................68 184 11.2.5Renew-Subscription operation .............................71 185 11.2.6Cancel-Subscription operation ............................74 187 12 Conformance Requirements .........................................76 189 13 IANA Considerations ..............................................77 190 13.1 Format and Requirements for IPP Delivery Method Registration 191 Proposals .........................................................78 193 14 Internationalization Considerations ..............................78 195 15 Security Considerations ..........................................79 197 16 Status Codes .....................................................80 198 16.1 successful-ok-ignored-subscriptions (0x0003) .................80 199 16.2 client-error-ignored-all-subscriptions (0x0414) ..............80 201 17 Status Codes in Subscription Attributes Groups ...................80 202 17.1 client-error-uri-scheme-not-supported (0x040C) ...............81 203 17.2 client-error-too-many-subscriptions (0x0415) .................81 204 17.3 successful-ok-too-many-events (0x0005) .......................81 205 17.4 successful-ok-ignored-or-substituted-attributes (0x0001) .....81 207 18 Encodings of Additional Attribute Tags ...........................82 209 19 References .......................................................82 211 20 Author's Addresses ...............................................83 213 A.Appendix - Model for Notification with Cascading Printers .........84 215 B.Appendix - Distributed Model for Notification .....................86 217 C.Appendix - Extended Notification Recipient ........................87 219 D.Appendix - Details about Conformance Terminology ..................88 221 E.Appendix - Object Model for Notification ..........................89 222 E.1 Appendix - Object relationships ..............................90 223 E.2 Printer Object and Per-Printer Subscription Objects ..........91 224 E.3 Job Object and Per-Job Subscription Objects ..................91 226 F.Appendix - Per-Job versus Per-Printer Subscription Objects ........91 228 G.Appendix: Full Copyright Statement ................................93 230 Tables 231 Table 1 - Subscription Template Attributes...........................23 232 Table 2 - Subscription Description Attributes........................37 233 Table 3 - Printer Description Attributes Associated with Notification41 234 Table 4 - Operation-id assignments...................................43 235 Table 5 - Attributes in Event Notification Content...................47 236 Table 6 - Additional Event Notification Content for Job Events.......49 237 Table 7 - Combinations of Events and Subscribed Events for "job- 238 impressions-completed" ...........................................49 239 Table 8 - Additional Event Notification Content for Printer Events...50 240 Table 9 - Printer Name in Event Notification Content.................52 241 Table 10 - Event Name in Event Notification Content..................52 242 Table 11 - Event Time in Event Notification Content..................53 243 Table 12 - Job Name in Event Notification Content....................53 244 Table 13 - Job State in Event Notification Content...................54 245 Table 14 - Printer State in Event Notification Content...............54 246 Table 15 - Information about the Delivery Method.....................55 247 Table 16 - Conformance Requirements for Operations...................76 249 Figures 250 Figure 1 - Model for Notification....................................11 251 Figure 2 - Model for Notification with Cascading Printers............86 252 Figure 3 - Opaque Use of a Notification Service Transparent to the 253 Client ...........................................................87 254 Figure 4 - Use of an Extended Notification Recipient transparent to the 255 Printer ..........................................................88 256 Figure 5 - Object Model for Notification.............................90 257 1 Introduction 259 This IPP notification specification is an extension to IPP/1.0 [RFC2568, 260 RFC2569] and IPP/1.1 [ipp-mod, ipp-pro]. This document in combination 261 with the following documents is intended to meet the notification 262 requirements described in [ipp-not-req]: 264 Internet Printing Protocol (IPP): "Job Progress Attributes" [ipp- 265 prog] 266 One or more Delivery Method Documents registered with IANA (see 267 section 13). 269 Note: this document does not define any Delivery Methods, but it does 270 define the rules for conformance for Delivery Method Documents. 272 Refer to the Table of Contents for the layout of this document. 274 1.1 Notification Overview 276 This document defines operations that a client can perform in order to 277 create Subscription Objects in a Printer and carry out other operations 278 on them. A Subscription Object represents a Subscription abstraction. 279 The Subscription Object specifies that when one of the specified Events 280 occurs, the Printer sends an asynchronous Event Notification to the 281 specified Notification Recipient via the specified Delivery Method 282 (i.e., protocol). 284 When a client (called a Subscribing Client) performs an operation that 285 creates a Subscription Object, the operation contains one or more 286 Subscription Template Attributes Groups. Each such group holds 287 information used by the Printer to initialize a newly created 288 Subscription Object. The Printer creates one Subscription Object for 289 each Subscription Template Attributes Group in the operation. This group 290 is like the Job Template Attributes group defined in [ipp-mod]. The 291 following is an example of the information included in a Subscription 292 Template Attributes Group (see section 5 for details on the Subscription 293 Object attributes): 295 1. The names of Subscribed Events that are of interest to the 296 Notification Recipient. 297 2. The address (URL) of one Notification Recipient. 298 3. The Delivery Method (i.e., the protocol) which the Printer uses to 299 send the Event Notification. 301 4. Some opaque data that the Printer sends to the Notification 302 Recipient in the Event Notification. The Notification Recipient 303 might use this opaque data as a forwarding address for the Event 304 Notification. 305 5. The charset to use in text fields within an Event Notification 306 6. The natural language to use in the text fields of the Event 307 Notification 308 7. The requested lease time in seconds for the Subscription Object 310 An operation that creates a Subscription Object is called a Subscription 311 Creation Operation. These operations include the following operations 312 (see section 11.1 for further details): 314 . Job Creation operation: When a client performs such an operation 315 (Print-Job, Print-URI, and Create-Job), a client can include zero 316 or more Subscription Template Attributes Groups in the request. 317 The Printer creates one Subscription Object for each Subscription 318 Template Attributes Group in the request, and the Printer 319 associates each such Subscription Object with the newly created 320 Job. This document extends these operations' definitions in [ipp- 321 mod] by adding Subscription Template Attributes Groups in the 322 request and Subscription Attributes Groups in the response. 324 . Create-Job-Subscriptions operation: A client can include one or 325 more Subscription Template Attributes Groups in the request. The 326 Printer creates one Subscription Object for each Subscription 327 Template Attributes Group and associates each with the job that is 328 the target of this operation. 330 . Create-Printer-Subscriptions operation: A client can include one or 331 more Subscription Template Attributes Groups in the request. The 332 Printer creates one Subscription Object for each Subscription 333 Template Attributes Group and associates each with the Printer that 334 is the target of this operation. 336 For each of the above operations: 338 . the Printer associates a Subscription Object with the Printer or a 339 specific Job. When a Subscription Object is associated with a Job 340 Object, it is called a Per-Job Subscription Object. When a 341 Subscription Object is associated with a Printer Object, it is 342 called a Per-Printer Subscription Object. 344 . the response contains one Subscription Attributes Group for each 345 Subscription Template Attributes Group in the request and in the 346 same order. When the Printer successfully creates a Subscription 347 Object, its corresponding Subscription Attributes Group contains 348 the "notify-subscription-id" attribute. This attribute uniquely 349 identifies the Subscription Object and is analogous to a "job-id" 350 for a Job object. Some operations described below use the "notify- 351 subscription-id" to identify the target Subscription Object. 353 This document adds the following additional operations (see section 11.2 354 for further details):: 356 . Validate-Job operation: When a client performs this operation, a 357 client can include zero or more Subscription Template Attributes 358 Groups in the request. The Printer determines if it could create 359 one Subscription Object for each Subscription Template Attributes 360 Group in the request. This document extends this operation's 361 definition in [ipp-mod] by adding Subscription Template Attributes 362 Groups in the request and Subscription Attributes Groups in the 363 response. 365 . Get-Subscription-Attributes operation: This operation allows a 366 client to obtain the specified attributes of a target Subscription 367 Object. 369 . Get-Subscriptions operation: This operation allows a client to 370 obtain the specified attributes of all Subscription Objects 371 associated with the Printer or a specified Job. 373 . Renew-Subscription operation: This operation renews the lease on 374 the target Per-Printer Subscription Object before it expires. A 375 newly created Per-Printer Subscription Object receives an initial 376 lease. It is the duty of the client to use this operation 377 frequently enough to preserve a Per-Printer Subscription Object. 378 The Printer deletes a Per-Printer Subscription Object when its 379 lease expires. A Per-Job Subscription Object last exactly as long 380 as its associated Job Object and thus doesn't have a lease. 382 . Cancel-Subscription operation: This operation cancels the lease on 383 the specified Per-Printer Subscription Object and thereby deletes 384 the Subscription Object. 386 When an Event occurs, the Printer finds all Subscription Objects 387 listening for the Event (see section 9 for details on finding such 388 Subscription Objects). For each such Subscription Object, the Printer: 389 a) generates an Event Notification with information specified in 390 section 9, AND 391 b) either: 392 i)delivers the Event Notification using the Delivery Method and 393 target address identified in the Subscription Object's "notify- 394 recipient-uri" attribute if the Delivery Method is a "push", OR 395 ii) saves Event Notification for a time period defined by the 396 Delivery Method if the Delivery Method is a "pull", i.e., the 397 Notification Recipient is expected to fetch the Event 398 Notifications. 400 2 Models for Notification 402 2.1 Model for Notification (Simple Case) 404 As part of a Subscription Creation Operation, an IPP Printer (i.e., an 405 output device or a server) creates one or more Subscription Objects. In 406 a Subscription Creation Operation, the client specifies the Notification 407 Recipient to which the Printer is to deliver Event Notifications. A 408 Notification Recipient can be the Subscribing Client or a third party. 410 Figure 1 shows the Notification model for a simple Client-Printer 411 relationship. 413 embedded printer: 414 output device or server 415 PDA, desktop, or server +---------------+ 416 +--------+ | ########### | 417 | client |-----Subscription ---------># Printer # | 418 +--------+ Creation Operation | # Object # | 419 +------------+ | #####|##### | 420 |Notification| +-------|-------+ 421 |Recipient |<----IPP Event Notifications----+ 422 +------------+ (Job and/or Printer Events) 424 Figure 1 - Model for Notification 426 2.2 Model for Notification with Cascading Printers 428 With this model, there is an intervening Print server between the human 429 user and the Printer in the output device. If the Printer in the output 430 device generates an Event, the system can be configured to send Event 431 Notification either 433 . directly to the Notification Recipient specified by the Subscribing 434 Client or 436 . via the Print Server to the Notification Recipient specified by the 437 Subscribing Client. 439 See Appendix A for more details. 441 2.3 Distributed Model for Notification 443 The preceding sections (2.1 and 2.2) assume that the Notification 444 software resides in the same device or Server box as the rest of the 445 Printer software. In many implementations, the assumption is correct. 446 However, the Notification model also permits a distributed 447 implementation. 449 For example, the software that supports both Subscription Creation 450 Operations and sending of Event Notifications could be on hardware that 451 is separate from the output device. To make this work, there must be a 452 symbiotic relationship between the output device software and the remote 453 Notification software. Without the remote Notification software, the 454 output device software is not a complete Printer. 456 The term "Printer" in this document includes the software on the output 457 device or server box as well as Notification software that is local to 458 or remote from the output device. 460 Appendix B describes this example in detail. 462 2.4 Extended Notification Recipient 464 The model allows for an extended Notification Recipient that is itself a 465 Notification service that forwards each Event Notification to another 466 recipient. The client contacts this Notification Recipient to arrange 467 for forwarding by means outside the scope of this document. The Printer 468 need not be aware that the Notification Recipient forwards Event 469 Notifications. 471 Appendix C describes this example in detail. 473 3 Terminology 475 This section defines terminology used throughout this document. 477 3.1 Conformance Terminology 479 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 480 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 481 conformance to this specification. These terms are defined in 482 [ipp-mod section 13.1 on conformance terminology, most of which is 483 taken from RFC 2119 [RFC2119]. See Appendix D for complete details. 485 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 486 the Printer implements a Delivery Method that REQUIRES the feature 488 READ-ONLY - an adjective used in an attribute definition to indicate 489 that an IPP Printer MUST NOT allow the attribute's value to be 490 modified with the Set-Job-Attributes or Set-Printer-Attributes 491 operations (see [ipp-set]). Note: there is no Set-Subscription 492 operation so this term is not used for Subscription object 493 attributes. 495 3.2 Other Terminology 497 Administrator - A human user who establishes policy for and 498 configures the print system. 500 Operator - A human user who carries out the policy established by the 501 Administrator and controls the day to day running of the print 502 system. 504 IPP Client (or client) - The software component (PDA, desktop, or 505 server) that performs an IPP operation directed at an IPP Printer 506 (server or output device). 508 Job Creation operation - One of the operations that creates a Job 509 object: Print-Job, Print-URI and Create-Job. The Validate-Job 510 operation is not a Job Creation operation because no Job object is 511 created. Therefore, when a statement also applies to the Validate- 512 Job operation, it is mentioned explicitly. 514 Event - some occurrence (either expected or unexpected) within the 515 printing system of a change of state, condition, or configuration 516 of a Job or Printer object. An Event occurs only at one instant in 517 time and does not span the time the physical Event takes place. 518 For example, jam-occurred and jam-cleared are two distinct, 519 instantaneous Events, even though the jam may last for a while. 521 Job Event - an Event caused by some change in a particular job on the 522 Printer, e.g., job-completed. 524 Printer Event - an Event caused by some change in the Printer that is 525 not specific to a job, e.g., printer-state-changed. 527 Subscribed Event - an Event that the Subscribing Client expresses 528 interest in by making it a value of the "notify-events" attribute 529 on a Subscription Object. 531 Subscribed Job Event - a Subscribed Event that is a Job Event. 533 Subscribed Printer Event - a Subscribed Event that is a Printer 534 Event. 536 Event Notification - the information about an Event that the Printer 537 sends when an Event occurs. 539 Notification Recipient - the entity to which the Printer sends an 540 Event Notification. 542 Delivery Method - the mechanism by which the Printer delivers the 543 Event Notification, e.g., via email or via SNMP. 545 Delivery Method Document - a document, separate from this document, 546 that defines a Delivery Method. 548 Compound Event Notification - two or more Event Notifications that a 549 Printer sends together as a single entity. The Delivery Method 550 Document specifies whether the Delivery Method supports Compound 551 Event Notifications. 553 Subscription Object - An object containing a set of attributes that 554 indicate: the Notification Recipient, the Delivery Method, the 555 Subscribed Events that cause the Printer to send an Event 556 Notification, and the information to send in an Event Notification. 558 Per-Job Subscription Object - A Subscription Object that is 559 associated with a single Job. The Create-Job-Subscriptions 560 operation and Job Creation operations create such an object. 562 Per-Printer Subscription Object - A Subscription Object that is 563 associated with the Printer as a whole. The Create-Printer- 564 Subscriptions operation creates such an object. 566 Subscribing Client - The client that creates the Subscription Object. 568 Subscription Creation Operation - An operation that creates a 569 Subscription Object: Job Creation operations, Create-Job- 570 Subscriptions operation, and Create-Printer-Subscriptions 571 operation. In the context of a Job Creation operation, a 572 Subscription Creation Operation is the part of the Job Creation 573 operation that creates a Subscription object. 575 Subscription Creation Request - The request portion of a 576 Subscription Creation Operation. 578 Subscription Template Attributes - Subscription Object attributes 579 that a client can supply in a Subscription Creation Operation and 580 associated Printer Object attributes that specify supported and 581 default values for the Subscription Object attributes. 583 Subscription Description Attributes - Subscription Object attributes 584 that a Printer supplies during a Subscription Creation Operation. 586 Subscription Template Attributes Group - The attributes group in a 587 request that contains Subscription Object attributes that are 588 Subscription Template Attributes. 590 Subscription Attributes Group - The attributes group in a response 591 that contains Subscription Object attributes. 593 Human Consumable Event Notification - localized text for human 594 consumption only. There is no standardized format and thus 595 programs should not try to parse this text. 597 Machine Consumable Event Notification - bytes for program 598 consumption. The bytes are formatted according to the Delivery 599 Method document. 601 Printer - the software that supports an output device or print server 602 (see IPP/1.1 [ipp-mod] which uses the terms Printer and Printer 603 object interchangeably). This document extends the IPP/1.1 Printer 604 definition to include the software that implements Subscription 605 Creation Operations and the sending of Event Notifications, even if 606 the software for such a Printer would be distributed across a 607 network (see section 2.3). 609 Notification - when not in the phrases 'Event Notification' and 610 'Notification Recipient' - the concepts of this specification, 611 i.e., Events, Subscription Objects, and Event Notifications. 613 4 Object Relationships 615 This section defines the object relationships between the Printer, Job, 616 and Subscription Objects. It does not define the implementation. For an 617 illustration of these relationships, see Appendix E. 619 4.1 Printer and Per-Printer Subscription Objects 621 1. A Printer object can be associated with zero or more Per-Printer 622 Subscription Objects. 624 2. Each Per-Printer Subscription Object is associated with exactly one 625 Printer object. 627 4.2 Printer, Job and Per-Job Subscription Objects 629 1. A Printer object is associated with zero or more Job objects. 631 2. Each Job object is associated with exactly one Printer object. 633 3. A Job object is associated with zero or more Per-Job Subscription 634 Objects. 636 4. Each Per-Job Subscription Object is associated with exactly one Job 637 object. 639 5 Subscription Object 641 A Subscribing Client creates a Subscription Object with a Subscription 642 Creation Operation in order to indicate its interest in certain Events. 643 See section 11 for a description of these operations. When an Event 644 occurs, the Subscription Object specifies to the Printer where to send 645 Event Notifications, how to send them and what to put in them. See 646 section 9 for details on the contents of an Event Notification. 648 Using the IPP Job Template attributes as a model (see [ipp-mod] section 649 4.2), the attributes of a Subscription Object are divided into two 650 categories: Subscription Template Attributes and Subscription 651 Description Attributes. 653 Subscription Template attributes are, in turn, like the Job Template 654 attributes, divided into 656 1. Subscription Object attributes that a client can supply in a 657 Subscription Creation Request and 659 2. their associated Printer Object attributes that specify supported 660 and default values for the Subscription Object attributes 662 The remainder of this section specifies general rules for Subscription 663 Template Attributes and describes each attribute in a Subscription 664 Object. 666 5.1 Rules for Support of Subscription Template Attributes 668 Subscription Template Attributes are fundamental to the Notification 669 model described in this specification. The client supplies these 670 attributes in Subscription Creation Operations and the Printer uses 671 these attributes to populate a newly created Subscription Object. 673 Subscription Objects attributes that are Subscription Template 674 Attributes conform to the following rules: 676 1. Each attribute's name starts with the prefix string "notify-" and 677 this document calls such attributes "notify-xxx". 679 2. For each "notify-xxx" Subscription Object attribute defined in 680 column 1 of Table 1, Table 1 specifies corresponding Printer 681 attributes: "notify-xxx-default", "notify-xxx-supported", "yyy- 682 supported" and "notify-max-xxx-supported" defined in column 2 of 683 Table 1. 685 3. If a Printer supports "notify-xxx" in column 1 of Table 1, then the 686 Printer MUST support all associated attributes specified in column 687 2 of Table 1. For example, Table 1 shows that if the Printer 688 supports "notify-events", it MUST support "notify-events-default", 689 "notify-events-supported" and "notify-max-events-supported". 691 4. If a Printer does not support "notify-xxx" in column 1 of Table 1, 692 then the Printer MUST NOT support any associated "notify-yyy" 693 attributes specified in column 2 of Table 1. For example, Table 1 694 shows that if the Printer doesn't support "notify-events", it MUST 695 NOT support "notify-events-default", "notify-events-supported" and 696 "notify-max-events-supported". Note this rule does not apply to 697 attributes whose names do not start with the string "notify-" and 698 are thus defined in another object and used by other attributes. 700 5. Most "notify-xxx" attributes have a corresponding "yyy-supported" 701 attribute that specifies the supported values for "notify-xxx". 702 Column 2 of Table 1 specifies the name of each "yyy-supported" 703 attribute. The naming rules of IPP/1.1 (see [ipp-mod]) are used 704 when "yyy-supported" is "notify-xxx-supported". 706 6. Some "notify-xxx" attributes have a corresponding "notify-xxx- 707 default" attribute that specifies the value for "notify-xxx" if the 708 client does not supply it. Column 2 of Table 1 specifies the name 709 of each "notify-xxx-default" attribute. The naming rules of IPP/1.1 710 (see [ipp-mod]) are used. 712 If a client wishes to present an end user with a list of supported 713 values from which to choose, the client SHOULD query the Printer for its 714 supported value attributes. The client SHOULD also query the default 715 value attributes. If the client then limits selectable values to only 716 those values that are supported, the client can guarantee that the 717 values supplied by the client in the create request all fall within the 718 set of supported values at the Printer. When querying the Printer, the 719 client MAY enumerate each attribute by name in the Get-Printer- 720 Attributes Request, or the client MAY just supply the 'subscription- 721 template' group name in order to get the complete set of supported 722 attributes (both supported and default attributes). 724 5.2 Rules for Processing Subscription Template Attributes 726 This section defines a detailed set of rules that a Printer follows when 727 it processes Subscription Template Attributes in a Subscription Creation 728 Request. These rules for are similar to the rules for processing 729 Operation attributes in [ipp-mod]. That is, the Printer may or may not 730 support an attribute and a client may or may not supply the attribute. 731 Some combinations of these cases are OK. Others return warnings or 732 errors, and perhaps a list of unsupported attributes. 734 A Printer MUST implement the following behavior for processing 735 Subscription Template Attributes in a Subscription Creation Request: 737 1. If a client supplies a "notify-xxx" attribute from column 1 of 738 Table 1 and the Printer supports it and its value, the Printer MUST 739 populate the attribute on the created Subscription Object. 741 2. If a client supplies a "notify-xxx" attribute from column 1 of 742 Table 1 and the Printer doesn't support it or its value, the 743 Printer MUST NOT populate the attribute on the created Subscription 744 Object with it. The Printer MUST do one of the following: 746 a)If the value of the "notify-xxx" attribute is unsupported, the 747 Printer MUST return the attribute with its value in the 748 Subscription Attributes Group of the response. 750 b)If "notify-xxx" is an unsupported attribute, the Printer MUST 751 return the attribute in the Subscription Attributes Group of the 752 response with the 'unsupported' out-of-band value. 754 Note: The rules of this step are the same as for Unsupported 755 Attributes [ipp-mod] section 3.1.7. except that the unsupported 756 attributes are returned in the Subscription Attributes Group rather 757 than the Unsupported Attributes Group because Subscription Creation 758 Operations can create more than one Subscription Object). 760 3. If a client is REQUIRED to supply a "notify-xxx" attribute from 761 column 1 of Table 1 and the Printer doesn't support the supplied 762 value, the Printer MUST NOT create a Subscription Object. The rules 763 for Unsupported Attributes in step #2 still apply. 765 4. If a client does not supply a "notify-xxx" attribute from column 1 766 of Table 1 and the attribute is REQUIRED for the client to supply, 767 the Printer MUST reject the Subscription Creation Operation 768 (including Job Creation operations) without creating a Subscription 769 Object, and MUST return in the response: 771 c)the status code 'client-error-bad-request' AND 773 d)no Subscription Attribute Groups. 775 5. If a client does not supply a "notify-xxx" attribute from column 1 776 of Table 1 that is OPTIONAL for the client to supply, and column 2 777 of Table 1 either: 779 a)specifies a "notify-xxx-default" attribute, the Printer MUST 780 behave as if the client had supplied the "notify-xxx-default" 781 attribute (see step #1) and populate the Subscription object 782 with the value of the "notify-xxx-default" attribute as part of 783 the Subscription Creation operation (unlike Job Template 784 attributes where the Printer does not populate the Job object 785 with defaults - see [ipp-mod]) OR 787 b)does not specify a "notify-xxx-default" attribute, the Printer 788 MUST populate the "notify-xxx" attribute on the Subscription 789 Object according to the definition of the "notify-xxx" attribute 790 in a section 5.3. For some attributes, the "notify-xxx" is 791 populated with the value of some other attribute, and for 792 others, the "notify-xxx" is NOT populated on the Subscription 793 object at all. 795 6. A Printer MUST create a Subscription Object for each Subscription 796 Template Attributes group in a request unless the Printer: 798 a)encounters some attributes in a Subscription Template Attributes 799 Group that require the Printer not to create the Subscription 800 Object OR 802 b)would create a Per-Job Subscription Object when it doesn't have 803 space for another Per-Job Subscription Object OR 805 c)would create a Per-Printer Subscription Object when it doesn't 806 have space for another Per-Printer Subscription Object. 808 7. A response MUST contain one Subscription Attributes Group for each 809 Subscription Template Attributes Group in the request (and in the 810 same order) whether the Printer creates a Subscription Object from 811 the Subscription Template Attributes Group or not. However, the 812 attributes in each Subscription Attributes Group can be in any 813 order. 815 8. The Printer MUST populate each Subscription Attributes Group of the 816 response such that each contains: 818 a)the "notify-subscription-id" attribute (see section 5.4.1), if 819 and only if the Printer creates a Subscription Object. 821 b)the "notify-lease-duration" attribute (see section 5.3.7), if 822 and only if the Printer creates a Per-Printer Subscription 823 Object. The value of this attribute is the value of the 824 Subscription Object's "notify-lease-duration" attribute. This 825 value MAY be different from the client-supplied value (see 826 section 5.3.7). If a client supplies this attribute in the 827 creation of a Per-Job Subscription Object, it MUST appear in 828 this group with the out-of-band value 'unsupported' to indicate 829 that the Printer doesn't support it in this context. 831 c)all of the unsupported Subscription Template Attributes from 832 step #2. 834 d)the "notify-status-code" attribute if the Printer does not 835 create the Subscription Object or if there are unsupported 836 attributes from step #2. The possible values of the "notify- 837 status-code" attribute are shown below (see section 17 for more 838 details). The Printer returns the first value in the list below 839 that describes the status. 841 'client-error-uri-scheme-not-supported': the Subscription 842 Object was not created because the scheme of the "notify- 843 recipient-uri" attribute is not supported. See section 17.1 844 for more details about this status code. See step #3 in 845 this section for the case that causes this error, and the 846 resulting step #6a) that causes the Printer not to create 847 the Subscription Object. 849 'client-error-too-many-subscriptions': the Subscription 850 Object was not created because the Printer has no space for 851 additional Subscription Objects. The client SHOULD try 852 again later. See section 17.2 for more details about this 853 status code. See steps #6b) and #6c) in this section for 854 the cases that causes this error. 856 'successful-ok-too-many-events': the Subscription Object was 857 created without the "notify-events" values included in this 858 Subscription Attributes Group because the "notify-events" 859 attribute contains too many values. See section 17.3 for 860 more details about this status code. See step #2 in this 861 section and section 5.3.2 for the cases that cause this 862 status code. 864 'successful-ok-ignored-or-substituted-attributes' : the 865 Subscription Object was created but some supplied 866 Subscription Template Attributes are unsupported. These 867 unsupported attributes are also in the Subscription 868 Attributes Group. See section 17.4 for more details about 869 this status code. See step #2 in this section for the cases 870 that cause this status code. 872 9. The Printer MUST validate all Subscription Template Attributes and 873 MUST return all unsupported attributes and values in the 874 corresponding Subscription Attributes Group of the response (see 875 step #2) unless it determines that it could not create additional 876 Subscription Objects because of condition #6b) or condition #6c). 877 Then, the Printer NEED NOT validate these additional Subscription 878 Template Attributes and the client MUST NOT expect to find 879 unsupported attributes from step #2 in such additional Subscription 880 Attribute Groups. 882 5.3 Subscription Template Attributes 884 This section contains the Subscription Template Attributes defined for 885 the Subscription and Printer objects. 887 Table 1 below shows the Subscription Template Attributes and has two 888 columns: 890 . Attribute in Subscription Object: the name and attribute syntax of 891 each Subscription Object Attribute that is a Subscription Template 892 Attribute 894 . Default and Supported Printer Attributes: the default attribute and 895 supported Printer attributes that are associated with the attribute 896 in column 1. 898 A Printer MUST support all attributes in Table 1 below except for 899 "notify-attributes" (and "notify-attributes-supported"). A client MUST 900 supply "notify-recipient-uri" and MAY omit any of the rest of the 901 attributes in column 1 of Table 1 in a Subscription Creation Request. 903 Table 1 - Subscription Template Attributes 905 Attribute in Subscription Default and Supported Printer 906 Object Attributes 908 notify-recipient-uri (uri) notify-schemes-supported (1setOf 909 uriScheme) 911 notify-events (1setOf type2 notify-events-default (1setOf type2 912 keyword) keyword) 913 notify-events-supported (1setOf type2 914 keyword) 915 notify-max-events-supported 916 (integer(2:MAX)) 918 Attribute in Subscription Default and Supported Printer 919 Object Attributes 921 notify-attributes (1setOf notify-attributes-supported (1setOf 922 type2 keyword) type2 keyword) 924 notify-user-data 925 (octetString(63)) 927 notify-charset (charset) charset-supported (1setOf charset) 929 notify-natural-languages generated-natural-language-supported 930 (naturalLanguage) (1setOf naturalLanguage) 932 notify-lease-duration notify-lease-duration-default 933 (integer(0:MAX)) (integer(0:67108863)) 934 notify-lease-duration-supported (1setOf 935 (integer(0: 67108863) | 936 rangeOfInteger(0:67108863))) 938 notify-time-interval 939 (integer(0:MAX)) 941 5.3.1 notify-recipient-uri (uri) 943 This attribute's value is a URL, which is a special case of a URI. Its 944 value consists of a scheme and an address. The address specifies the 945 Notification Recipient and the scheme specifies the Delivery Method for 946 each Event Notification associated with this Subscription Object. 948 A Printer MUST support this attribute. 950 A client MUST supply this attribute in Subscription Creation Operation. 951 Thus there is no need for a default attribute. 953 The "notify-schemes-supported (1setOf uriScheme)" attribute MUST specify 954 the schemes supported for this attribute. 956 If the client supplies an unsupported scheme in the value of this 957 attribute, then the Printer MUST not create the Subscription Object and 958 MUST return the "notify-status-code" attribute with the 'client-error- 959 uri-scheme-not-supported' value in the Subscription Attributes Group in 960 the response. 962 The Printer MUST treat the address part of this attribute as opaque. 964 5.3.2 notify-events (1setOf type2 keyword) 966 This attribute contains a set of Subscribed Events. When an Event 967 occurs and it "matches" a value of this attribute, the Printer sends an 968 Event Notification using information in the Subscription Object. The 969 details of "matching" are described subsection 5.3.2.2. 971 A Printer MUST support this attribute. 973 A client MAY supply this attribute in a Subscription Creation Operation. 974 If the client does not supply this attribute in Subscription Creation 975 Operation, the Printer MUST populate this attribute on the Subscription 976 Object with its "notify-events-default" attribute value. 978 Each value of this attribute on a Subscription Object MUST be one of the 979 values of the "notify-events-supported (1setOf type2 keyword)" 980 attribute. 982 The number of values of this attribute MUST NOT exceed the value of the 983 "notify-max-events-supported" attribute. A Printer MUST support at least 984 2 values per Subscription Object. If the number of values supplied by a 985 client in a Subscription Creation Operation exceeds the value of this 986 attribute, the Printer MUST treat extra values as unsupported values and 987 MUST use the value of 'successful-ok-too-many-events' for the "notify- 988 status-code" attribute in the Subscription Attributes Group of the 989 response. 991 5.3.2.1 Standard Values for Subscribed Events 993 Each value of this attribute is a keyword and it specifies a Subscribed 994 Event that represents certain changes. Some keywords represent a subset 995 of changes of another keyword, e.g., 'job-completed' is an Event value 996 which is a sub-value of 'job-state-change'. See section 5.3.2.2 for the 997 case where this attribute contains both a value and a sub-value. 999 The values in this section are divided into three categories: No Events, 1000 Job Events and Printer Events. 1002 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1003 support the Events indicated as "OPTIONAL". 1005 5.3.2.1.1 No Events 1007 The standard and only keyword value for No Events is: 1009 'none': REQUIRED - no Event Notifications for any Events. As the 1010 sole value of "notify-events-supported", this value means that the 1011 Printer does not support the sending of Event Notifications. As the 1012 sole value of "notify-events-default", this value means that a 1013 client MUST specify the "notify-events" attribute in order for a 1014 Subscription Creation Operation to succeed. If the Printer receives 1015 this value as the sole value of a Subscription Creation Operation, 1016 it does not create a Subscription Object. If a Printer receives 1017 this value with other values of a Subscription Creation Operation, 1018 the Printer MUST treat this value as an unsupported value. 1020 5.3.2.1.2 Subscribed Printer Events 1022 The standard keyword values for Subscribed Printer Events are: 1024 'printer-state-changed': REQUIRED - the Printer changed state from 1025 any state to any other state. Specifically, the value of the 1026 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1027 accepting-jobs" attributes changed. 1029 This Subscribed Event value has the following sub-values: 'printer- 1030 restarted' and 'printer-shutdown'. A client can listen for any of 1031 these sub-values if it doesn't want to listen to all printer-state 1032 changes: 1034 'printer-restarted': OPTIONAL - when the printer is powered up . 1036 'printer-shutdown': OPTIONAL - when the device is being powered 1037 down . 1039 'printer-stopped: REQUIRED - when the printer stops printing, i.e. 1040 the value of the "printer-state" Printer attribute becomes 1041 'stopped'. 1043 'printer-config-changed': OPTIONAL - when the configuration of a 1044 Printer has changed, i.e., the value of the "printer-message-from- 1045 operator" or any "configuration" Printer attribute has changed. A 1046 "configuration" Printer attribute is an attribute which can change 1047 value because of some human interaction either direct or indirect, 1048 and which is not covered by one of the other Events in this 1049 section. Examples of "configuration" Printer attributes are any of 1050 the Job Template attributes, such as "xxx-supported", "xxx-ready" 1051 and "xxx-default". Often, such a change is the result of a client 1052 performing a Set-Printer-Attributes operation (see [ipp-set]) on 1053 the Printer. The client has to perform a Get-Printer-Attributes to 1054 find out the new values of these changed attributes. This Event is 1055 useful for GUI clients and drivers to update the available printer 1056 capabilities to the user. 1058 This Event value has the following sub-values: 'printer-media- 1059 changed' and 'printer-finishings-changed'. A client can listen for 1060 any of these sub-values if it doesn't want to listen to all 1061 printer-configuration changes: 1063 'printer-media-changed': OPTIONAL - when the media loaded on a 1064 printer has been changed, i.e., the "media-ready" attribute has 1065 changed. This Event includes two cases: an input tray that goes 1066 empty and an input tray that receives additional media of the 1067 same type or of a different type. The client must check the 1068 "media-ready" Printer attribute (see [ipp-mod] section 4.2.11) 1069 separately to find out what changed. 1071 'printer-finishings-changed': OPTIONAL - when the finisher on a 1072 printer has been changed, i.e., the "finishings-ready" attribute 1073 has changed. This Event includes two cases: a finisher that goes 1074 empty and a finisher that is refilled (even if it is not full). 1075 The client must check the "finishings-ready" Printer attribute 1076 separately to find out what changed. 1078 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1079 Printer's queue has changed, so that an application that is 1080 monitoring the queue can perform a Get-Jobs operation to determine 1081 the new order. This Event does not include when a job enters the 1082 queue (the 'job-created' Event covers that) and does not include 1083 when a job leaves the queue (the 'job-completed' Event covers 1084 that). 1086 5.3.2.1.3 Subscribed Job Events 1088 The standard keyword values for Subscribed Job Events are: 1090 'job-state-changed': REQUIRED - the job has changed from any state 1091 to any other state. Specifically, the Printer sends this Event 1092 whenever the value of the "job-state" attribute or "job-state- 1093 reasons" attribute changes. When a Job is removed from the Job 1094 History (see [ipp-mod] 4.3.7.1), no Event is generated. 1096 This Event value has the following sub-values: 'job-created', 'job- 1097 completed' and 'job-purged'. A client can listen for any of these 1098 sub-values if it doesn't want to listen to all 'job-state changes'. 1100 'job-created': REQUIRED - the Printer has accepted a Job Creation 1101 operation and the job's "time-at-creation" attribute value is 1102 set (see [ipp-mod] section 4.3.14.1). The Printer puts the job 1103 in the 'pending', 'pending-held' or 'processing' states.. 1105 'job-completed': REQUIRED - the job has reached one of the 1106 completed states, i.e., the value of the job's "job-state" 1107 attribute has changed to: 'completed', 'aborted', or 'canceled'. 1108 The Job's "time-at-completed" and "date-time-at-completed" (if 1109 supported) attributes are set (see [ipp-mod] section 4.3.14).. 1110 The Printer also sends this Event when a Job is removed with the 1111 Purge-Job operation. In this case, the Event Notification MUST 1112 report the 'job-state' as 'canceled'. 1114 'job-stopped: OPTIONAL - when the job stops printing, i.e. the 1115 value of the "job-state" Job attribute becomes 'processing- 1116 stopped'. 1118 'job-config-changed': OPTIONAL - when the configuration of a job 1119 has changed, i.e., the value of the "job-message-from-operator" or 1120 any of the "configuration" Job attributes have changed. A 1121 "configuration" Job attribute is an attribute that can change value 1122 because of some human interaction either direct or indirect. 1123 Examples of "configuration" Job attributes are any of the job 1124 template attributes and the "job-name" attribute. Often, such a 1125 change is the result of the user or the Operator performing a Set- 1126 Job-Attributes operation (see [ipp-set]) on the Job object. The 1127 client performs a Get-Job-Attributes to find out the new values of 1128 the changed attributes. This Event is useful for GUI clients and 1129 drivers to update the job information to the user. 1131 'job-progress': OPTIONAL - when the Printer has completed Printing a 1132 sheet. See the separate [ipp-prog] specification for additional 1133 attributes that a Printer MAY send in an Event Notification caused 1134 by this Event. The "notify-time-interval" attribute affects this 1135 Event by causing the Printer NOT to send an Event Notification 1136 every time a 'job-progress' Events occurs. See section 5.3.8 for 1137 full details. 1139 5.3.2.2 Rules for Matching of Subscribed Events 1141 When an Event occurs, the Printer MUST find each Subscription object 1142 whose "notify-events" attribute "matches" the Event. The rules for 1143 "matching" of Subscribed Events are described separately for Printer 1144 Events and for Job Events. This section also describes some special 1145 cases. 1147 5.3.2.2.1 Rules for Matching of Printer Events 1149 Suppose that the Printer causes Printer Event E to occur. For each Per- 1150 Job or Per-Printer Subscription S in the Printer, if E equals a value of 1151 this attribute in S or E is a sub-value of a value of this attribute in 1152 S, the Printer MUST generate an Event Notification. 1154 Consider the example. There are three Subscription Objects each with 1155 the Subscribed Printer Event 'printer-state-changed'. Subscription 1156 Object A is a Per-Printer Subscription Object. Subscription Object B 1157 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1158 is a Per-Job Subscription Object for Job 2. When the Printer enters 1159 the 'stopped' state, the Printer sends an Event Notification to the 1160 Notification Recipients of Subscription Objects A, B, and C because 1161 this is a Printer Event. Note if Job 1 has already completed, the 1162 Printer would not send an Event Notification for its Subscription 1163 Object. 1165 5.3.2.2.2 Rules for Matching of Job Events 1167 Suppose that Job J causes Job Event E to occur. 1169 3. For each Per-Printer Subscription S in the Printer, if E equals a 1170 value of this attribute in S or E is a sub-value of a value of this 1171 attribute in S, the Printer MUST generate an Event Notification. 1173 4. For each Per-Job Subscription S associated with Job J, if E equals 1174 a value of this attribute in S or E is a sub-value of a value of 1175 this attribute in S, the Printer MUST generate an Event 1176 Notification. 1178 5. For each Per-Job Subscription S that is NOT associated Job J, if E 1179 equals a value of this attribute in S or E is a sub-value of a 1180 value of this attribute in, the Printer MUST NOT generate an Event 1181 Notification from S. 1183 Consider the example: There are three Subscription Objects listening 1184 for the Job Event 'job-completed'. Subscription Object A is a Per- 1185 Printer Subscription Object. Subscription Object B is a Per-Job 1186 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1187 Subscription Object for Job 2. In addition, Per-Printer Subscription 1188 Object D is listening for the Job Event 'job-state-changed'. When Job 1189 1 completes, the Printer sends an Event Notification to the 1190 Notification Recipient of Subscription Object A (because it is Per- 1191 Printer) and Subscription Object B because it is a Per-Job 1192 Subscription Object associated with the Job generating the Event. 1193 The Printer also sends an Event Notification to the Notification 1194 Recipient of Subscription Object D because 'job-completed' is a sub- 1195 value of 'job-state-changed' - the value that Subscription Object D 1196 is listening for. The Printer does not send an Event Notification to 1197 the Notification Recipients of Subscription Object C because it is a 1198 Per-Job Subscription Object associated with some Job other than the 1199 Job generating the Event. 1201 5.3.2.2.3 Special Cases for Matching Rules 1203 This section contains rule for special cases. 1205 If an Event matches Subscribed Events in two different Subscription 1206 Objects and the Printer would send two identical Event Notifications 1207 (except for the "notify-subscription-id" attribute) to the same 1208 Notification Recipient using the same Delivery Method, the Printer MUST 1209 send both Event Notifications. That is, the Printer MUST NOT try to 1210 consolidate seemingly identical Event Notifications that occur in 1211 separate Subscription objects. Incidentally, the Printer MUST NOT reject 1212 Subscription Creation Operations that would create this scenario. 1214 If an Event matches two values of this "notify-events" attribute in a 1215 single Subscription object (e.g., a value and its sub-value), a Printer 1216 MAY send one Event Notification for each matched value in the 1217 Subscription Object or it MAY send only one Event Notification per 1218 Subscription Object. The rules in sections 5.3.2.2.1 and 5.3.2.2.2 are 1219 purposefully ambiguous about the number of Event Notification sent when 1220 Event E matches two or more values in a Subscription Object. 1222 Consider the example: There are two Per-Printer Subscription Objects 1223 when a Job completes. Subscription Object A has the Subscribed Job 1224 Event 'job-state-changed'. Subscription Object B has the Subscribed 1225 Job Events 'job-state-changed' and 'job-completed'. The Printer sends 1226 an Event Notification to the Notification Recipient of Subscription 1227 Object A with the value of 'job-state-changed' for the "notify- 1228 subscribing-event" attribute. The Printer sends either one or two 1229 Event Notifications to the Notification Recipient of Subscription 1230 Object B, depending on implementation. If it sends two Event 1231 Notifications, one has the value of 'job-state-changed' for the 1232 "notify-subscribing-event" attribute, and the other has the value of 1233 'job-completed' for the "notify-subscribing-event" attribute. If it 1234 sends one Event Notification, it has the value of either 'job-state- 1235 changed' or 'job-completed' for the "notify-subscribing-event" 1236 attribute, depending on implementation. The algorithm for choosing 1237 such a value is implementation dependent. 1239 5.3.3 notify-attributes (1setOf type2 keyword) 1241 This attribute contains a set of attribute names. When a Printer sends a 1242 Machine Consumable Event Notification, it includes a fixed set of 1243 attributes (see section 0). If this attribute is present and the Event 1244 Notification is Machine Consumable, the Printer also includes the 1245 attributes specified by this attribute. 1247 A Printer MAY support this attribute. 1249 A client MAY supply this attribute in a Subscription Creation Operation. 1250 If the client does not supply this attribute in Subscription Creation 1251 Operation or the Printer does not support this attribute, the 1252 Subscription Object MUST NOT contain the "notify-attributes" attribute. 1253 There is no "notify-attributes-default" attribute. 1255 Each keyword value of this attribute on a Subscription Object MUST be a 1256 value of the "notify-attributes-supported (1setOf type2 keyword)" 1257 attribute. The "notify-attributes-supported" MAY contain any Printer 1258 attribute, Job attribute or Subscription Object attribute that the 1259 Printer supports in an Event Notification. It MUST NOT contain any of 1260 the attributes in Section 0 that a Printer automatically puts in an 1261 Event Notification; it would be redundant. If a client supplies an 1262 attribute in Section 0, the Printer MUST treat it as an unsupported 1263 attribute value of the "notify-attributes" attribute. 1265 The following rules apply to each keyword value N of the "notify- 1266 attributes" attribute: If the value N names: 1268 a) a Subscription attribute, the Printer MUST use the attribute N in 1269 the Subscription Object that is being used to generate the Event 1270 Notification. 1272 b) a Job attribute and the Printer is generating an Event Notification 1273 from a Per-Job Subscription Object S, the Printer MUST use the 1274 attribute N in the Job object associated with S. 1276 c) a Job attribute and the Printer is generating an Event Notification 1277 from a Per-Printer Subscription Object and the Event is: 1279 . a Job Event, the Printer MUST use the attribute N in the Job 1280 object that caused the Event. 1282 . a Printer Event, the Printer MUST use the attribute N in the 1283 active Job. 1285 If a Printer supports this attribute and a Subscription Object contains 1286 this attribute and the Delivery Method generates a Machine Consumable 1287 Event Notification, the Printer MUST include in each Event Notification: 1289 a)the attributes specified in section 0 and 1291 b)each attribute named by this attribute. 1293 5.3.4 notify-user-data (octetString(63)) 1295 This attribute contains opaque data that some Delivery Methods include 1296 in each Machine Consumable Event Notification. The opaque data might 1297 contain, for example: 1299 . the identity of the Subscriber 1301 . a path or index to some Subscriber information 1302 . a key that identifies to the Notification Recipient the ultimate 1303 recipient of the Event Notification 1305 . the id for a Notification Recipient that had previously registered 1306 with an Instant Messaging Service 1308 A Printer MUST support this attribute. 1310 A client MAY supply this attribute in a Subscription Creation Operation. 1311 If the client does not supply this attribute in Subscription Creation 1312 Operation, the Subscription Object MUST NOT contain the "notify-user- 1313 data" attribute. There is no "notify-user-data-default" attribute. 1315 There is no "user-data-supported" attribute. Rather, any octetString 1316 whose length does not exceed 63 octets is a supported value. If the 1317 length exceeds 63 octets, the Printer MUST treat it as an unsupported 1318 value. 1320 5.3.5 notify-charset (charset) 1322 This attribute specifies the charset to be used in the Event 1323 Notification content sent to the Notification Recipient, whether the 1324 Event Notification content is Machine Consumable or Human Consumable. 1326 A Printer MUST support this attribute. 1328 A client MAY supply this attribute in a Subscription Creation Operation. 1329 If the client does not supply this attribute in Subscription Creation 1330 Operation or supplies an unsupported value, the Printer MUST populate 1331 this attribute in the Subscription Object with the value of the 1332 "attributes-charset" operation attribute, which is a REQUIRED attribute 1333 in all IPP requests (see [ipp-mod]). If the value of the "attributes- 1334 charset" attribute is unsupported, the Printer MUST populate this 1335 attribute in the Subscription Object with the value of the Printer's 1336 "charset-configured" attribute. There is no "notify-charset-default" 1337 attribute. 1339 The value of this attribute on a Subscription Object MUST be a value of 1340 the "charset-supported (1setOf charset)" attribute. 1342 5.3.6 notify-natural-language (naturalLanguage) 1344 This attribute specifies the natural language to be used in any human 1345 consumable text in the Event Notification content sent to the 1346 Notification Recipient, whether the Event Notification content is 1347 Machine Consumable or Human Consumable. 1349 A Printer MUST support this attribute. 1351 A client MAY supply this attribute in a Subscription Creation Operation. 1352 If the client does not supply this attribute in Subscription Creation 1353 Operation or supplies an unsupported value, the Printer MUST populate 1354 this attribute in the Subscription Object with the value of the 1355 "attributes-natural-language" operation attribute, which is a REQUIRED 1356 attribute in all IPP requests (see [ipp-mod]). If the value of the 1357 "attributes-natural-language" attribute is unsupported, the Printer MUST 1358 populate this attribute in the Subscription Object with the value of the 1359 Printer's "natural-language-configured" attribute. There is no "notify- 1360 natural-language-default" attribute. 1362 The value of this attribute on a Subscription Object MUST be a value of 1363 the "generated-natural-language-supported (1setOf type2 1364 naturalLanguage)" attribute. 1366 5.3.7 notify-lease-duration (integer(0:67108863)) 1368 This attribute specifies the duration of the lease associated with the 1369 Per-Printer Subscription Object at the time the Subscription Object was 1370 created or the lease was renewed. The duration of the lease is infinite 1371 if the value is 0, i.e., the lease never expires. 1373 This attribute is not present on a Per-Job Subscription Object because 1374 the Subscription Object lasts exactly as long as the associated Job 1375 object. See section 5.4.3 on "notify-lease-expiration-time 1376 (integer(0:MAX))" for more details. 1378 A Printer MUST support this attribute. 1380 For a Subscription Object Creation operation of a Per-Job Subscription 1381 Object, the client MUST NOT supply this attribute. If the client does 1382 supply this attribute, the Printer MUST treat it as an unsupported 1383 attribute. 1385 For a Subscription Creation Operation of a Per-Printer Subscription 1386 Object or a Renew-Subscription operation, a client MAY supply this 1387 attribute. If the client does not supply this attribute, the Printer 1388 MUST populate this attribute with its "notify-lease-duration-default" 1389 (0:67108863) attribute value. If the client supplies this attribute with 1390 an unsupported value, the Printer MUST populate this attribute with a 1391 supported value, and this value SHOULD be as close as possible to the 1392 value requested by the client. Note: this rule implies that a Printer 1393 doesn't assign the value of 0 (infinite) unless the client requests it. 1395 After the Printer has populated this attribute with a supported value, 1396 the value represents the "granted duration" of the lease and the Printer 1397 sets the value of the Subscription Object's "notify-lease-expiration- 1398 time" attribute as specified in section 5.4.3. 1400 The value of this attribute on a Subscription Object MUST be a value of 1401 the "notify-lease-duration-supported" (1setOf (integer(0:67108863) | 1402 rangeOfInteger(0:67108863))) attribute. 1404 A Printer MAY require authentication in order to return the value of 0 1405 (the lease never expires) as one of the values of "notify-lease- 1406 duration-supported", and to allow 0 as a value of the "notify-lease- 1407 duration" attribute. 1409 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1 1410 and is about 2 years in seconds. The value is considerably less than 1411 MAX so that there is virtually no chance of an overflow when it is added 1412 to "printer-up-time" to produce "notify-lease-expiration-time". 1414 5.3.8 notify-time-interval (integer(0:MAX)) 1416 The 'job-progress' Event occurs each time that a Printer completes a 1417 sheet. Some Notification Recipients do not want to receive an Event 1418 Notification every time this Event occurs. This attribute allows a 1419 Subscribing Client to request how often it want to receive Event 1420 Notifications for 'job-progress' Events. 1422 The Printer MUST support this attribute if and only if the Printer 1423 supports the 'job-progress' Event. 1425 A client MAY supply this attribute in a Subscription Creation Operation. 1426 If the client does not supply this attribute, the Printer MUST not 1427 populate this attribute on the Subscription Object. There is no default 1428 "notify-time-interval-default" attribute. 1430 There is no "notify-time-interval-supported". The value of this 1431 attribute MAY be any nonnegative integer (0,MAX). 1433 If the 'job-progress' Event occurs and a Subscription Object contains 1434 the 'job-progress' Event as a value of the 'notify-events' attribute, 1435 there are two cases to consider: 1437 1. This attribute is not present on the Subscription Object or has the 1438 value of 0. The Printer MUST generate and send an Event 1439 Notification (as is the case with other Events). 1441 2. This attribute is present with a nonzero value of N: 1443 a)If the Printer has not sent an Event Notification for the 'job- 1444 progress' Event for the associated Subscription Object within 1445 the past N seconds, the Printer MUST send an Event Notification 1446 for the Event that just occurred. Note when the Printer 1447 completes the first page of a Job, this rule implies that the 1448 Printer sends an Event Notification for a Per-Job Subscription 1449 Objects. 1451 b)Otherwise, the Printer MUST NOT generate or send an Event 1452 Notification for the associated Subscription Object. The Printer 1453 MUST NOT increase the value of the "notify-sequence-number" 1454 Subscription Object attribute (i.e., the sequence of values of 1455 the "notify-sequence-number" attribute counts the Event 1456 Notifications that the Printer sent and not the Events that do 1457 not cause an Event Notification to be sent). 1459 It is RECOMMENDED that a Subscribing Client use this attribute when it 1460 subscribes to the 'job-progress' Event, and that the value be 1461 sufficiently large to limit the frequency with which the Printer sends 1462 Event Notifications. 1464 This attribute MUST not effect any Events other than 'job-progress'. 1466 5.4 Subscription Description Attributes 1468 Subscription Description Attributes are those attributes that a Printer 1469 adds to a Subscription Object at the time of its creation. 1471 A Printer MUST support all attributes in this Table 2. 1473 A client MUST NOT supply the attributes in Table 2 in a Subscription 1474 Template Attributes Group of a Subscription Creation Operation. If the 1475 client supplies them, the Printer MUST NOT set them and MUST treat them 1476 as unsupported attributes. There are no corresponding default or 1477 supported attributes. 1479 Table 2 - Subscription Description Attributes 1481 Subscription Object attributes: 1483 notify-subscription-id (integer(1:MAX)) 1485 notify-sequence-number (integer(0:MAX)) 1487 notify-lease-expiration-time (integer(0:MAX)) 1489 notify-printer-up-time (integer(1:MAX)) 1491 notify-printer-uri (uri) 1493 notify-job-id (integer(1:MAX)) 1495 notify-subscriber-user-name (name(MAX)) 1497 5.4.1 notify-subscription-id (integer (1:MAX)) 1499 This attribute identifies a Subscription Object instance with a number 1500 that is unique within the context of the Printer. The Printer generates 1501 this value at the time it creates the Subscription Object. 1503 A Printer MUST support this attribute. 1505 The Printer SHOULD NOT assign the value of this attribute sequentially 1506 as it creates Subscription Objects. Sequential assignment makes it easy 1507 for rogue clients to guess the value of this attribute on other 1508 Subscription Objects. 1510 The Printer SHOULD avoid re-using recent values of this attribute during 1511 continuous operation of the Printer as well as across power cycles. Then 1512 a Subscribing Client is unlikely to find that a stale reference accesses 1513 a new Subscription Object. 1515 The 0 value is not permitted in order to allow for compatibility with 1516 "job-id" and with SNMP index values, which also cannot be 0. 1518 5.4.2 notify-sequence-number (integer (0:MAX)) 1520 The value of this attribute indicates the number of times that the 1521 Printer has generated and attempted to send an Event Notification. When 1522 an Event Notification contains this attribute, the Notification 1523 Recipient can determine whether it missed some Event Notifications 1524 (i.e., numbers skipped) or received duplicates (i.e., same number 1525 twice). 1527 A Printer MUST support this attribute. 1529 When the Printer creates a Subscription Object, it MUST set the value of 1530 this attribute to 0. This value indicates that the Printer has not sent 1531 any Event Notifications for this Subscription Object. 1533 Each time the Printer sends a newly generated Event Notification, it 1534 MUST increase the value of this attribute by 1. For some Delivery 1535 Methods, the Printer MUST include this attribute in each Event 1536 Notification, and the value MUST be the value after it is increased by 1537 1. That is, the value of this attribute in the first Event Notification 1538 after Subscription object creation MUST be 1, the second MUST be 2, etc. 1539 If a Delivery Method is defined such that the Notification Recipient 1540 returns a response, the Printer can re-try sending an Event Notification 1541 a certain number of times with the same sequence number when the 1542 Notification Recipient fails to return a response. 1544 If a Subscription Object lasts long enough to reach the value of MAX, 1545 its next value MUST be 0, i.e., it wraps. 1547 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1549 This attribute specifies the time in the future when the lease on the 1550 Per-Printer Subscription Object will expire, i.e. the "printer-up-time" 1551 value at which the lease will expire. If the value is 0, the lease never 1552 expires. 1554 A Printer MUST support this attribute. 1556 When the Printer creates a Per-Job Subscription Object, this attribute 1557 MUST NOT be present - the Subscription Object lasts exactly as long as 1558 the associated Job object. 1560 When the Printer creates a Per-Printer Subscription Object, it populates 1561 this attribute with a value that is the sum of the values of the 1562 Printer's "printer-up-time" attribute and the Subscription Object's 1563 "notify-lease-duration" attribute with the following exception. If the 1564 value of the Subscription Object's "notify-lease-duration" attribute is 1565 0 (i.e., no expiration time), then the value of this attribute MUST be 1566 set to 0 (i.e., no expiration time). 1568 When the Printer powers up, it MUST set the value of this attribute in 1569 each persistent Subscription Object using the algorithm in the previous 1570 paragraph. 1572 When the "printer-up-time" equals the value of this attribute, the 1573 Printer MUST delete the Subscription Object. A client can extend a lease 1574 of a Per-Printer Subscription Object with the Renew-Subscription 1575 operation (see section 11.2.5). 1577 Note: In order to compute the number of seconds remaining in a lease for 1578 a Per-Printer Subscription Object, a client can subtract the 1579 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1580 from the Subscription's "notify-lease-expiration-time" attribute. 1582 5.4.4 notify-printer-up-time (integer(1:MAX)) 1584 This attribute is an alias for the Printer's "printer-up-time" attribute 1585 " (see [ipp-mod] section 4.4.29). 1587 A Printer MUST support this attribute. 1589 When the Printer creates a Per-Job Subscription Object, this attribute 1590 MUST NOT be present. When the Printer creates a Per-Printer Subscription 1591 Object, this attribute MUST be present. 1593 Note: this attribute exists in a Per-Printer Subscription Object so that 1594 a client using the Get-Subscription-Attributes or Get-Subscription 1595 operations can convert the Per-Printer Subscription's "notify-lease- 1596 expiration-time" attribute to wall clock time with one request. If the 1597 value of the "notify-lease-expiration-time" attribute is not 0 (i.e., no 1598 expiration time), then the difference between the "notify-lease- 1599 expiration-time" attribute and the "notify-printer-up-time" is the 1600 remaining number of seconds on the lease from the current time. 1602 5.4.5 notify-printer-uri (uri) 1604 This attribute identifies the Printer object that created this 1605 Subscription Object. 1607 A Printer MUST support this attribute. 1609 During a Subscription Creation Operation, the Printer MUST populate this 1610 attribute with the value of the "printer-uri" operation attribute in the 1611 request. From the Printer URI, the client can, for example, determine 1612 what security scheme was used. 1614 5.4.6 notify-job-id (integer(1:MAX)) 1616 This attribute specifies whether the containing Subscription Object is a 1617 Per-Job or Per-Printer Subscription Object, and for Per-Job Subscription 1618 Objects, it specifies the associated Job. 1620 A Printer MUST support this attribute. 1622 If this attribute is not present, the Subscription Object MUST be a Per- 1623 Printer Subscription. If this attribute is present, the Subscription 1624 Object MUST be a Per-Job Subscription Object and this attribute MUST 1625 identify the Job with which the Subscription Object is associated. 1627 Note: This attribute could be useful to a Notification Recipient that 1628 receives an Event Notification generated from a Per-Job Subscription 1629 Object and caused by a Printer Event. The Event Notification gives 1630 access to the Printer and the Subscription Object. The Event 1631 Notification gives access to the associated Job only via this 1632 attribute.. 1634 5.4.7 notify-subscriber-user-name (name(MAX)) 1636 This attribute contains the name of the user who performed the 1637 Subscription Creation Operation. 1639 A Printer MUST support this attribute. 1641 The Printer sets this attribute to the most authenticated printable name 1642 that it can obtain from the authentication service over which the 1643 Subscription Creation Operation was received. The Printer uses the same 1644 mechanism for determining the value of this attribute as it does for a 1645 Job's "job-originating-user-name" (see [ipp-mod] section 4.3.6). 1647 Note: To help with authentication, a Subscription Object may have 1648 additional private attributes about the user, e.g., a credential of a 1649 principal. Such private attributes are implementation-dependent and not 1650 defined in this document. 1652 6 Printer Description Attributes Related to Notification 1654 This section defines the Printer Description attributes that are related 1655 to Notification. Table 3 lists the Printer Description attributes, 1656 indicates the Printer support required for conformance, and whether or 1657 not the attribute is READ-ONLY (see section 3.1): 1659 Table 3 - Printer Description Attributes Associated with Notification 1661 Printer object attributes: REQUIRED READ-ONLY 1663 printer-state-change-time (integer(1:MAX)) No Yes 1664 Printer object attributes: REQUIRED READ-ONLY 1666 printer-state-change-date-time (dateTime) No Yes 1668 6.1 printer-state-change-time (integer(1:MAX)) 1670 This attribute records the most recent time at which the 'printer-state- 1671 changed' Printer Event occurred whether or not any Subscription objects 1672 were listening for this event. This attribute helps a client or 1673 operator to determine how long the Printer has been in its current 1674 state. 1676 A Printer MAY support this attribute and if so, the attribute MUST be 1677 READ-ONLY. 1679 On power-up, the Printer MUST set the value of this attribute to be the 1680 value of its "printer-up-time" attribute, so that it always has a value. 1681 Whenever the 'printer-state-changed' Printer Event occurs, the Printer 1682 MUST set this attribute to the value of the Printer's "printer-up-time" 1683 attribute. 1685 6.2 printer-state-change-date-time (dateTime) 1687 This attribute records the most recent time at which the 'printer-state- 1688 changed' Printer Event occurred whether or not there were any 1689 Subscription Objects listening for this event. This attribute helps a 1690 client or operator to determine how long the Printer has been in its 1691 current state. 1693 A Printer MAY support this attribute and if so, the attribute MUST be 1694 READ-ONLY. 1696 On power-up, the Printer MUST set the value of this attribute to be the 1697 value of its "printer-current-time" attribute, so that it always has a 1698 value (see [ipp-mod] section 4.4.30 on "printer-current-time"). Whenever 1699 the 'printer-state-changed' Printer Event occurs, the Printer MUST set 1700 this attribute to the value of the Printer's "printer-current-time" 1701 attribute. 1703 7 New Values for Existing Printer Description Attributes 1705 7.1 operations-supported (1setOf type2 enum) 1707 The following "operation-id" values are added in order to support the 1708 new operations defined in this document: 1710 Table 4 - Operation-id assignments 1712 Value Operation Name 1714 0x0016 Create-Printer-Subscriptions 1716 0x0017 Create-Job-Subscriptions 1718 0x0018 Get-Subscription-Attributes 1720 0x0019 Get-Subscriptions 1722 0x001A Renew-Subscription 1724 0x001B Cancel-Subscription 1726 8 Attributes Only in Event Notifications 1728 This section contains those attributes that exist only in Event 1729 Notifications. 1731 8.1 notify-subscribed-event (type2 keyword) 1733 This attribute indicates the Subscribed Event that caused the Printer to 1734 send this Event Notification. This attribute exists only in Event 1735 Notifications. 1737 This attribute MUST contain one of the values of the "notify-events" 1738 attribute in the Subscription Object, i.e., one of the Subscribed Event 1739 values. Its value is the Subscribed Event that "matches" the Event that 1740 caused the Printer to send this Event Notification. This Subscribed 1741 Event value may be identical to the Event or the Event may be a sub- 1742 value of the Subscribed Event. For example, the 'job-completed' Event 1743 (which is a sub-event of the 'job-state-changed' event) would cause the 1744 Printer to send an Event Notification for either the 'job-completed' or 1745 'job-state-changed' Subscribed Events and to send the 'job-completed' or 1746 'job-state-changed' value for this attribute, respectively,. See 1747 section 5.3.2.2 for the "matching" rules of Subscribed Events and for 1748 additional examples. 1750 The Delivery Method Document specifies whether the Printer includes the 1751 value of this attribute in an Event Notification. 1753 8.2 notify-text (text(MAX)) 1755 This attribute contains a Human Consumable text message (see section 1756 9.2). This message describes the Event and is encoded as plain text, 1757 i.e., 'text/plain' with the charset specified by Subscription Object's 1758 "notify-charset" attribute. 1760 The Delivery Method Document specifies whether the Printer includes this 1761 attribute in an Event Notification. 1763 9 Event Notification Content 1765 This section defines the Event Notification content that the Printer 1766 sends when an Event occurs. 1768 When an Event occurs, the Printer MUST find each Subscription object 1769 whose "notify-events" attribute "matches" the Event. See section 5.3.2.2 1770 for details on "matching". For each matched Subscription Object, the 1771 Printer MUST create an Event Notification with the content and format 1772 that the Delivery Method Document specifies. The content contains the 1773 value of attributes specified by the Delivery Method Document. The 1774 Printer obtains the values immediately after the Event occurs. For 1775 example, if the "printer-state" attribute changes from 'idle' to 1776 'processing', the Event 'printer-state-changed' occurs and the Printer 1777 puts various attributes into the Event Notification, including "printer- 1778 up-time" and "printer-state" with the values that they have immediately 1779 after the Event occurs, i.e., the value of "printer-state" is 1780 'processing'. 1782 If two different Events occur simultaneously, or nearly so (e.g., 1783 "printer-up-time" has the same value for both), the Printer MUST create 1784 a separate Event Notification for each Event, even if the associated 1785 Subscription Object is the same for both Events. However, the Printer 1786 MAY combine these distinct Event Notifications into a single Compound 1787 Event Notification if the Delivery Method supports Compound Event 1788 Notifications For example, suppose that two nearly-simultaneously Events 1789 represent two successive 'printer-state-changed' Events, one from 'idle' 1790 to 'processing' and another from 'processing' to 'stopped'. These two 1791 Events have the same name but are different instances of the Event. Then 1792 the Printer MUST create a separate Event Notification for each Event and 1793 SHOULD accurately report the "printer-state" of the first Event as 1794 'processing' and the second Event as 'stopped'. 1796 If a Subscription Object contains more than one Subscribed Event, and 1797 several Events occur in quick succession each matching a different 1798 Subscribed Event in the Subscription Object, the Printer MUST NOT 1799 generate a single Event Notification from several of these Events, but 1800 MAY combine distinct Event Notifications into a single Compound Event 1801 Notification if the Delivery Method supports Compound Event 1802 Notifications. 1804 After the Printer has created the Event Notification, the Printer 1805 delivers it via either a: 1806 Push Delivery Method: The Printer sends the Event Notification 1807 shortly after an Event occurs. For some Push Delivery Methods, the 1808 Notification Recipient MUST send a response; for others it MUST NOT 1809 send a response. 1811 Pull Delivery Method: The Printer saves Event Notifications for 1812 some event-lease time and expects the Notification Recipient to 1813 request Event Notifications. The Printer returns the Event 1814 Notifications in a response to such a request. 1816 If an error that meets the following conditions occurs, the Printer MUST 1817 cancel the Subscription Object. 1819 a) the error occurs during the sending of an Event Notification 1820 generated from Subscription Object S AND 1822 b) the error would continue to occur every time the Printer sends an 1823 Event Notification generated from Subscription Object S in the 1824 future. 1826 >From example, if the address of the "notify-recipient-uri" of 1827 Subscription Object A references a non-existent target and the Printer 1828 determines that this fact, it MUST delete Subscription Object A. 1830 The next two sections describe the values that a Printer sends in the 1831 content of Machine Consumable and Human Consumable Event Notifications, 1832 respectively. 1834 The tables in the sub-sections of this section contain the following 1835 columns: 1837 a)Source Value: the name of the attribute that supplies the value 1838 for the Event Notification. Asterisks in this field refer to a 1839 note below the table. 1841 b)Sends: if the Printer supports the value (column 1) on the 1842 Source Object (column 3) the Delivery Method MUST specify: 1844 MUST: that the Printer MUST send the value. 1846 SHOULD: either that the Printer MUST send the value or that 1847 the value is incompatible with the Delivery Method. 1849 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 1850 or NEED NOT send the value. The Delivery Method specifies the 1851 level of conformance for the Printer. 1853 c)Source Object: the object from which the source value comes. If 1854 the object is "Event Notification", the Printer fabricates the 1855 value when it sends the Event Notification. See section 8. 1857 9.1 Content of Machine Consumable Event Notifications 1859 This section defines the attributes that a Delivery Method MUST mention 1860 in a Delivery Method Document when specifying the Machine Consumable 1861 Event Notification's contents. 1863 This document does not define the order of attributes in Event 1864 Notifications. However, Delivery Method Documents MAY define the order 1865 of some or all of the attributes. 1867 A Delivery Method Document MUST specify additional attributes (if any) 1868 that a Printer implementation sends in a Machine Consumable Event 1869 Notification. 1871 Notification Recipients MUST be able to accept Event Notifications 1872 containing attributes they do not recognize. What a Notification 1873 Recipient does with an unrecognized attribute is implementation- 1874 dependent. Notification Recipients MAY attempt to display unrecognized 1875 attributes anyway or MAY ignore them. 1877 The next three sections define the attributes in Event Notification 1878 Contents that are: 1880 a)for all Events 1882 b)for Job Events only 1884 c)for Printer Events only 1886 9.1.1 Event Notification Content Common to All Events 1888 This section lists the attributes that a Delivery Method MUST specify 1889 for all Events. 1891 Table 5 lists potential values in each Event Notification. 1893 Table 5 - Attributes in Event Notification Content 1895 Source Value Sends Source Object 1897 notify-subscription-id (integer(1:MAX)) MUST Subscription 1899 notify-printer-uri (uri) MUST Subscription 1901 notify-subscribed-event (type2 keyword) MUST Event 1902 Notification 1904 Source Value Sends Source Object 1906 printer-up-time (integer(MIN:MAX)) MUST Printer 1908 printer-current-time (dateTime)* MUST Printer 1910 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 1912 notify-charset (charset) SHOULD Subscription 1914 notify-natural-language (naturalLanguage) SHOULD Subscription 1916 notify-user-data (octetString(63)) ** SHOULD Subscription 1918 notify-text (text) SHOULD Event 1919 Notification 1921 attributes from the "notify-attributes" MAY Printer 1922 attribute *** 1924 attributes from the "notify-attributes" MAY Job 1925 attribute *** 1927 attributes from the "notify-attributes" MAY Subscription 1928 attribute *** 1930 *A Printer MUST send this value only if and only if it supports the 1931 Printer's "printer-current-time" attribute. 1933 ** If the Subscription Object does not contain a "notify-user-data" 1934 attribute and the Delivery Method document REQUIRES the Printer to send 1935 the "notify-user-data" source value in the Event Notification, the 1936 Printer MUST send an octet-string of length 0. 1938 *** The last three rows represent additional attributes that a client 1939 MAY request via the "notify-attributes" attribute. A Printer MAY 1940 support the "notify-attributes" attribute. The Delivery Method MUST say 1941 that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED NOT 1942 support the "notify-attributes" attribute and specific values of this 1943 attribute. The Delivery Method MAY say that support for the "notify- 1944 attributes" is conditioned on support of the attribute by the Printer or 1945 it MAY say that Printer MUST support the "notify-attribute" attribute if 1946 the Printer supports the Delivery Method. 1948 9.1.2 Additional Event Notification Content for Job Events 1950 This section lists the additional attributes that a Delivery Method MUST 1951 specify for Job Events. See Table 6. 1953 Table 6 - Additional Event Notification Content for Job Events 1955 Source Value Sends Source Object 1957 job-id (integer(1:MAX)) MUST Job 1959 job-state (type1 enum) MUST Job 1961 job-state-reasons (1setOf type2 keyword) MUST Job 1963 job-impressions-completed (integer(0:MAX)) MUST Job 1964 * 1966 * The Printer MUST send the "job-impressions-completed" attribute in an 1967 Event Notification only for the combinations of Events and Subscribed 1968 Events shown in Table 7. 1970 Table 7 - Combinations of Events and Subscribed Events for "job- 1971 impressions-completed" 1973 Job Event Subscribed Job Event 1975 'job-progress' 'job-progress' 1977 'job-completed' 'job-completed' 1979 'job-completed' 'job-state-changed' 1980 9.1.3 Additional Event Notification Content for Printer Events 1982 This section lists the additional attributes that a Delivery Method MUST 1983 specify for Printer Events. See Table 8. 1985 Table 8 - Additional Event Notification Content for Printer Events 1987 Source Value Sends Source Object 1989 printer-state (type1 enum) MUST Printer 1991 printer-state-reasons (1setOf type2 MUST Printer 1992 keyword) 1994 printer-is-accepting-jobs (boolean) MUST Printer 1996 9.2 Content of Human Consumable Event Notification 1998 This section defines the information that a Delivery Method MUST mention 1999 in a Delivery Method Document when specifying the Human Consumable Event 2000 Notifications contents or the value of the "notify-text" attribute. 2002 Such a Delivery Method MUST specify the following information and a 2003 Printer SHOULD send it: 2005 a)the Printer name (see Table 9) 2006 b)the time of the Event (see Table 11) 2007 c)for Printer Events only: 2008 i) the Event (see Table 10) and/or Printer state information 2009 (see Table 14) 2010 d)for Job Events only: 2011 i) the job identity (see Table 12) 2012 ii) the Event (see Table 10) and/or Job state information (see 2013 Table 13) 2015 The subsections of this section specify the attributes that a Printer 2016 MUST use to obtain this information. 2018 A Delivery Method Document MUST specify additional information (if any) 2019 that a Printer implementation sends in a Human Consumable Event 2020 Notification or in the "notify-text" attribute. 2022 A client MUST NOT request additional attributes via the "notify- 2023 attributes" attribute because this attribute works only for Machine 2024 Consumable Event Notifications. 2026 Notification Recipients MUST NOT expect to be able to parse the Human 2027 Consumable Event Notification contents or the value of the "notify-text" 2028 attribute. 2030 The next three sections define the attributes in Event Notification 2031 Contents that are: 2033 a)for all Events 2035 b)for Job Events only 2037 c)for Printer Events only 2039 9.2.1 Event Notification Content Common to All Events 2041 This section lists the source of the information that a Delivery Method 2042 MUST specify for all Events. 2044 There is a separate table for each piece of information. Each row in the 2045 table represents a source value for the information and the values are 2046 listed in order of preference, with the first one being the preferred 2047 one. An implementation SHOULD use the source value from the earliest row 2048 in each table. It MAY use the source value from another row instead, or 2049 it MAY combine the source values from several rows. An implementation is 2050 free to determine the best way to present this information. 2052 In all tables of this section, all rows contain a "MAY" in order to 2053 state that the Delivery Method specifies the conformance. 2055 . 2057 Table 9 lists the source of the information for the Printer Name. The 2058 "printer-name" is more user-friendly unless the Notification Recipient 2059 is in a place where the Printer name is not meaningful. For example, an 2060 implementation could have the intelligence to send the value of the 2061 "printer-name" attribute to a Notification Recipient that can access the 2062 Printer via value of the "printer-name" attribute and otherwise send the 2063 value of the "notify-printer-uri" attribute. 2065 Table 9 - Printer Name in Event Notification Content 2067 Source Value Sends Source Object 2069 printer-name (name(127)) MAY Printer 2071 notify-printer-uri (uri) MAY Subscription 2073 Table 10 lists the source of the information for the Event name. A 2074 Printer MAY combine this information with state information described 2075 for Jobs in Table 13 or for Printers in Table 14. 2077 Table 10 - Event Name in Event Notification Content 2079 Source Value Sends Source Object 2081 notify-subscribed-event (type2 keyword) MAY Subscription 2083 Table 11 lists the source of the information for the time that the Event 2084 occurred. A Printer can send this value only if it supports the 2085 Printer's "printer-current-time" attribute. If a Printer does not 2086 support the 2087 "printer-current-time" attribute, it MUST NOT send the "printer-up-time" 2088 value instead, since it is not an allowed option for human consumable 2089 information. 2091 Table 11 - Event Time in Event Notification Content 2093 Source Value Sends Source Object 2095 printer-current-time (dateTime) MAY Printer 2097 9.2.2 Additional Event Notification Content for Job Events 2099 This section lists the source of the additional information that a 2100 Delivery Method MUST specify for Job Events. 2102 Table 12 lists the source of the information for the job name. The "job- 2103 name" is likely more meaningful to a user than "job-id". 2105 Table 12 - Job Name in Event Notification Content 2107 Source Value Sends Source Object 2109 job-name (name(MAX)) MAY Job 2111 job-id (integer(1:MAX)) MAY Job 2113 Table 13 lists the source of the information for the job state. If a 2114 Printer supports the "job-state-message" and "job-detailed-state- 2115 message" attributes, it SHOULD use those attributes for the job state 2116 information, otherwise, it should fabricate such information from the 2117 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2118 combine this information with Event information. 2120 Table 13 - Job State in Event Notification Content 2122 Source Value Sends Source Object 2124 job-state-message (text(MAX)) MAY Job 2126 job-detailed-status-messages (1setOf MAY Job 2127 text(MAX)) 2129 job-state (type1 enum) MAY Job 2131 job-state-reasons (1setOf type2 keyword) MAY Job 2133 9.2.3 Additional Event Notification Content for Printer Events 2135 This section lists the source of the additional information that a 2136 Delivery Method MUST specify for Printer Events. 2138 Table 14 lists the source of the information for the printer state. If a 2139 Printer supports the "printer-state-message", it SHOULD use that 2140 attribute for the job state information, otherwise it SHOULD fabricate 2141 such information from the "printer-state" and "printer-state-reasons". 2142 For some Events, a Printer MAY combine this information with Event 2143 information. 2145 Table 14 - Printer State in Event Notification Content 2147 Source Value Sends Source Object 2149 printer-state-message (text(MAX)) MAY Printer 2151 printer-state (type1 enum) MAY Printer 2153 printer-state-reasons (1setOf type2 MAY Printer 2154 keyword) 2156 printer-is-accepting-jobs (boolean) MAY Printer 2157 10 Delivery Methods 2159 A Delivery Method is the mechanism, i.e., protocol, by which the Printer 2160 delivers an Event Notification to a Notification Recipient. There are 2161 several potential Delivery Methods for Event Notifications, 2162 standardized, as well as proprietary. This document does not define any 2163 of these delivery mechanisms. Each Delivery Method MUST be defined in a 2164 Delivery Method Document that is separate from this document. New 2165 Delivery Methods will be created as needed using an extension to the 2166 registration procedures defined in [ipp-mod]. Such documents are 2167 registered with IANA (see section 13). 2169 The following sorts of Delivery Methods are expected: 2171 - The Notification Recipient polls for Event Notifications at 2172 intervals directed by the Printer 2174 - The Printer sends Event Notifications to the Notification Recipient 2175 using http as the transport. 2177 - The Printer sends an email message. 2179 This section specifies how to define a Delivery Method Document and what 2180 to put in such a document. 2182 A Delivery Method Document MUST contain an exact copy of the following 2183 paragraph, caption and table. In addition, column 2 of the table in the 2184 Delivery Method Document MUST contain answers to questions in column 1 2185 for the Delivery Method. Also, the Delivery Method document MUST contain 2186 a reference to this document and call that reference [ipp-ntfy] because 2187 the table contains an [ipp-ntfy] reference. 2189 If a Printer supports this Delivery Method, the following are its 2190 characteristics. 2192 Table 15 - Information about the Delivery Method 2194 Document Method Conformance Delivery Method Realization 2195 Requirement 2197 1. What is the URL scheme name 2198 for the Delivery Method? 2200 2. Is the Delivery Method 2201 REQUIRED, RECOMMENDED or OPTIONAL 2202 for an IPP Printer to support? 2204 3. What transport and delivery 2205 protocols does the Printer use 2206 to deliver the Event 2207 Notification Content, i.e., 2208 what is the entire network 2209 stack? 2211 4. Can several Event 2212 Notifications be combined into 2213 a Compound Event Notification? 2215 5. Is the Delivery Method 2216 initiated by the Notification 2217 Recipient (pull), or by the 2218 Printer (push)? 2220 6. Is the Event Notification 2221 content Machine Consumable or 2222 Human Consumable? 2224 7. What section in this document 2225 answers the following 2226 question? For a Machine 2227 Consumable Event Notification, 2228 what is the representation and 2229 encoding of values defined in 2230 section 0 of [ipp-ntfy] and 2231 the conformance requirements 2232 thereof? For a Human 2233 Consumable Event Notification, 2234 what is the representation and 2235 encoding of pieces of 2236 information defined in section 2237 9.2 of [ipp-ntfy] and the 2238 conformance requirements 2239 thereof? 2241 8. What are the latency and 2242 reliability of the transport 2243 and delivery protocol? 2245 9. What are the security aspects 2246 of the transport and delivery 2247 protocol, e.g., how it is 2248 handled in firewalls? 2250 10. What are the content length 2251 restrictions? 2253 11. What are the additional 2254 values or pieces of 2255 information that a Printer 2256 sends in an Event Notification 2257 content and the conformance 2258 requirements thereof? 2260 12. What are the additional 2261 Subscription Template and/or 2262 Subscription Description 2263 attributes and the conformance 2264 requirements thereof? 2266 13. What are the additional 2267 Printer Description attributes 2268 and the conformance 2269 requirements thereof? 2271 11 Operations for Notification 2273 This section defines all of the operations for Notification. Section 7.1 2274 assigns of the "operation-id" for each operation. The following two 2275 sub-sections define Subscription Creation Operations, and other 2276 operations. 2278 11.1 Subscription Creation Operations 2280 This section defines the Subscription Creation Operations. The first 2281 section on Create-Job-Subscriptions gives most of the information. The 2282 other Subscription Creation Operations refer to the section on Create- 2283 Job-Subscriptions, even though the Create-Job-Subscriptions operation is 2284 the only OPTIONAL operation in this document (see section 12). 2286 A Printer MUST support Create-Printer-Subscriptions and the Subscription 2287 Template Attributes Group in Job Creation operations. It MAY support 2288 Create-Job-Subscriptions operations. 2290 11.1.1 Create-Job-Subscriptions Operation 2292 The operation creates one or more Per-Job Subscription Objects. The 2293 client supplies one or more Subscription Template Attributes Groups each 2294 containing one or more of Subscription Template Attributes (defined in 2295 section 5.3). 2297 Except for errors, the Printer MUST create exactly one Per-Job 2298 Subscription Object from each Subscription Template Attributes Group in 2299 the request, even if the newly created Subscription Object would have 2300 identical behavior to some existing Subscription Object. The Printer 2301 MUST associate each newly created Per-Job Subscription Object with the 2302 target Job, which is specified by the "notify-job-id" operation 2303 attribute. 2305 The Printer MUST accept the request in any of the target job's 'not- 2306 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2307 'processing-stopped'. The Printer MUST NOT change the job's "job-state" 2308 attribute because of this operation. If the target job is in any of the 2309 'completed' states, i.e., 'completed', 'canceled', or 'aborted, then the 2310 Printer MUST reject the request and return the 'client-error-not- 2311 possible' status code; the response MUST NOT contain any Subscription 2312 Attribute Groups. 2314 Access Rights: To create Per-Job Subscription Objects, the 2315 authenticated user (see [IPP-MOD] section 8.3) performing this operation 2316 MUST either be the job owner or have Operator or Administrator access 2317 rights for this Printer (see [IPP-MOD] sections 1 and 8.5). Otherwise 2318 the Printer MUST reject the operation and return: the 'client-error- 2319 forbidden', 'client-error-not-authenticated', or 'client-error-not- 2320 authorized' status code as appropriate. 2322 11.1.1.1 Create-Job-Subscriptions Request 2324 The following groups of attributes are part of the Create-Job- 2325 Subscriptions Request: 2327 Group 1: Operation Attributes 2329 Natural Language and Character Set: 2330 The "attributes-charset" and "attributes-natural-language" 2331 attributes as described in [ipp-mod] section 3.1.4.1. 2333 Target: 2334 The "printer-uri" attribute which defines the target for this 2335 operation as described in [ipp-mod] section 3.1.5. 2337 Requesting User Name: 2338 The "requesting-user-name" attribute SHOULD be supplied by the 2339 client as described in [ipp-mod] section 8.3. 2341 notify-job-id (integer(1:MAX)): 2342 The client MUST supply this attribute and it MUST specify the Job 2343 object to associate the Per-Job Subscription with. The value of 2344 "notify-job-id" MUST be the value of the "job-id" of the associated 2345 Job object. If the client does not supply this attribute, the 2346 Printer MUST reject this request with a 'client-error-bad-request' 2347 status code. 2349 Group 2-N: Subscription Template Attributes 2351 For each occurrence of this group: 2353 The client MUST supply one or more Subscription Template 2354 Attributes in any order. See section 5.3 for a description of 2355 each such attribute. See section 5.2 for details on processing 2356 these attributes. 2358 11.1.1.2 Create-Job-Subscriptions Response 2360 The Printer MUST return to the client the following sets of attributes 2361 as part of a Create-Job-Subscriptions response: 2363 Group 1: Operation Attributes 2365 Status Message: 2366 As defined in [ipp-mod]. 2368 The Printer can return any status codes defined in [ipp-mod] and 2369 section 16. The following is a description of the important status 2370 codes: 2372 successful-ok: the Printer created all Subscription Objects 2373 requested. 2374 successful-ok-ignored-subscriptions: the Printer created some 2375 Subscription Objects requested but some failed. The 2376 Subscription Attributes Groups with a "notify-status-code" 2377 attribute are the ones that failed. 2378 client-error-ignored-all-subscriptions: the Printer created no 2379 Subscription Objects requested and all failed. The 2380 Subscription Attributes Groups with a "notify-status-code" 2381 attribute are the ones that failed 2383 client-error-not-possible: For this operation and other Per-Job 2384 Subscription operations, this error can occur because the 2385 specified Job has already completed. 2387 Natural Language and Character Set: 2388 The "attributes-charset" and "attributes-natural-language" 2389 attributes as described in [ipp-mod] section 3.1.4.2. 2391 Group 2: Unsupported Attributes 2393 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2394 Attributes. This group does not contain any unsupported 2395 Subscription Template Attributes; they are returned in the 2396 Subscription Attributes Group (see below). 2398 Group 3-N: Subscription Attributes 2400 These groups MUST be returned if and only if the "status-code" 2401 parameter returned in Group 1 has the values: 'successful-ok', 2402 'successful-ok-ignored-subscriptions', or 'client-error-ignored- 2403 all-subscriptions'. 2405 See section 5.2 for details on the contents of each occurrence of 2406 this group. 2408 11.1.2 Create-Printer-Subscriptions operation 2410 The operation is identical to Create-Job-Subscriptions with exceptions 2411 noted in this section. 2413 The operation creates Per-Printer Subscription Objects instead of Per- 2414 Job Subscription Objects, and associates each newly created Per-Printer 2415 Subscription Object with the Printer specified by the operation target 2416 rather than with a specific Job. 2418 The Printer MUST accept the request in any of its states, i.e., 'idle', 2419 'processing', or 'stopped'. The Printer MUST NOT change its "printer- 2420 state" attribute because of this operation. 2422 Access Rights: To create Per-Printer Subscription Objects, the 2423 authenticated user (see [IPP-MOD] section 8.3) performing this operation 2424 MUST have Operator or Administrator access rights for this Printer (see 2425 [IPP-MOD] sections 1 and 8.5). Otherwise, the Printer MUST reject the 2426 operation and return: the 'client-error-forbidden', 'client-error-not- 2427 authenticated', or 'client-error-not-authorized' status code as 2428 appropriate. 2430 11.1.2.1 Create-Printer-Subscriptions Request 2432 The groups are identical to the Create-Job-Subscriptions (see section 2433 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2434 the "notify-job-id" attribute. If the client does supply the "notify- 2435 job-id" attribute, then the Printer MUST treat it as any other 2436 unsupported Operation attribute and MUST return it in the Unsupported 2437 Attributes group. 2439 11.1.2.2 Create-Printer-Subscriptions Response 2441 The groups are identical to the Create-Job-Subscriptions (see section 2442 11.1.1.2). 2444 11.1.3 Job Creation Operation - Extensions for Notification 2446 This document extends the Job Creation operations to create Subscription 2447 Objects as a part of the operation. 2449 The operation is identical to Create-Job-Subscriptions with exceptions 2450 noted in this section. 2452 Unlike the Create-Job-Subscriptions operation, this operation associates 2453 the newly created Subscription Objects with the Job object created by 2454 this operation. The operation succeeds if and only if the Job creation 2455 succeeds. If the Printer does not create some or all of the requested 2456 Subscription Objects, the Printer MUST return a 'successful-ok-ignored- 2457 subscriptions' status-code instead of a 'successful-ok' status-code, but 2458 the Printer MUST NOT reject the operation because of a failure to create 2459 Subscription Objects. 2461 If the operation includes a Job Template group, the client MUST supply 2462 it after the Operation Attributes group and before the first 2463 Subscription Template Attributes Group. 2465 If a Printer does not support this Notification specification, then it 2466 MUST treat the Subscription Attributes Group like an unknown group and 2467 ignore it (see [ipp-mod] section 5.2.2). Because the Printer ignores 2468 the Subscription Attributes Group, it doesn't return them in the 2469 response either, thus indicating to the client that the Printer doesn't 2470 support Notification. 2472 Access Rights: To create Per-Job Subscription Objects, the 2473 authenticated user (see [IPP-MOD] section 8.3) performing this operation 2474 MUST either have permission to create Jobs on the Printer. Otherwise 2475 the Printer MUST reject the operation and return: the 'client-error- 2476 forbidden', 'client-error-not-authenticated', or 'client-error-not- 2477 authorized' status code as appropriate. 2479 11.1.3.1 Job Creation Request 2481 The groups for this operation are sufficiently different from the 2482 Create-Job-Subscriptions operation that they are all presented here. The 2483 following groups of attributes are supplied as part of a Job Creation 2484 Request: 2486 Group 1: Operation Attributes 2488 Same as defined in [ipp-mod] for Print-Job, Print-URI, and Create- 2489 Job requests. 2491 Group 2: Job Template Attributes 2493 The client OPTIONALLY supplies a set of Job Template attributes as 2494 defined in [ipp-mod] section 4.2. 2496 Group 3 to N: Subscription Template Attributes 2498 The same as Group 2-N in Create-Job-Subscriptions. See section 2499 11.1.1.1. 2501 Group N+1: Document Content (Print-Job only) 2503 The client MUST supply the document data to be processed. 2505 11.1.3.2 Job Creation Response 2507 The Printer MUST return to the client the following sets of attributes 2508 as part of a Print-Job, Print-URI, and Create-Job Response: 2510 Group 1: Operation Attributes 2512 Status Message: 2514 As defined in [ipp-mod] for Print-Job, Print-URI, and Create-Job 2515 requests. 2517 The Printer can return any status codes defined in [ipp-mod] and 2518 section 16. The following is a description of the important status 2519 codes: 2521 successful-ok: the Printer created the Job and all Subscription 2522 Objects requested. 2523 successful-ok-ignored-subscriptions: the Printer created the Job 2524 and not all of the Subscription Objects requested. This 2525 status-code hides 'successful-ok-xxx' status-codes that could 2526 reveal problems in Job creation. The Printer MUST not return 2527 the 'client-error-ignored-all-subscriptions' status code for 2528 Job Creation operations because the Printer returns an error 2529 status-code only when it fails to create a Job. 2531 Natural Language and Character Set: 2532 The "attributes-charset" and "attributes-natural-language" 2533 attributes as described in [ipp-mod] section 3.1.4.2. 2535 Group 2: Unsupported Attributes 2537 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2538 Attributes. This group does not contain any unsupported 2539 Subscription Template Attributes; they are returned in the 2540 Subscription Attributes Group (see below). 2542 Group 3: Job Object Attributes 2544 As defined in [ipp-mod] for Print-Job, Print-URI, and Create-Job 2545 requests. 2547 Group 4 to N: Subscription Attributes 2549 These groups MUST be returned if and only if the client supplied 2550 Subscription Template Attributes and the operation was accepted. 2552 See section 5.2 for details on the contents of each occurrence of 2553 this group. 2555 11.2 Other Operations 2557 This section defines other operations on Subscription objects. 2559 11.2.1 Validate-Job Operation - Extensions for Notification 2561 A client can test whether one or more Subscription Objects could be 2562 created using the Validate-Job operation. The client supplies one or 2563 more Subscription Template Attributes Groups (defined in section 5.3), 2564 just as in a Job Creation request. 2566 A Printer MUST support this extension to this operation. 2568 The Printer MUST accept requests that are identical to the Job Creation 2569 request defined in section 11.1.3.1, except that the request MUST not 2570 contain document data. 2572 The Printer MUST return the same groups and attributes as the Print-Job 2573 operation (section 11.1.3.1) with the following exceptions. The Printer 2574 MUST NOT return a Job Object Attributes Group because no Job is created. 2575 The Printer MUST NOT return the "notify-subscription-id" attribute in 2576 any Subscription Attribute Group because no Subscription Object is 2577 created. 2579 If the Printer would succeed in creating a Subscription Object, the 2580 corresponding Subscription Attributes Group either has no 'status-code' 2581 attribute or a 'status-code' attribute with a value of 'successful-ok- 2582 too-many-events' or 'successful-ok-ignored-or-substituted-attributes' 2583 (see sections 5.2 and 17). The status-codes have the same meaning as in 2584 Job Creation except the results state what "would happen". 2586 The Printer MUST validate Subscription Template Attributes Groups in the 2587 same manner as the Job Creation operations. 2589 11.2.2 Get-Printer-Attributes - Extensions for Notification 2591 This operation is extended so that it returns Printer attributes defined 2592 in this document. 2594 A Printer MUST support this extension to this operation. 2596 In addition to the requirements of [ipp-mod] section 3.2.5, a Printer 2597 MUST support the following additional values for the "requested- 2598 attributes" Operation attribute in this operation and return such 2599 attributes in the Printer Object Attributes group of its response. 2601 1. Subscription Template Attributes: Each supported attribute in 2602 column 2 of Table 1. 2604 2. New Printer Description Attributes: Each supported attribute in 2605 section 6. 2607 3. New Group Name: The 'subscription-template' group name, which names 2608 all supported Subscription Template Attribute in column 2 of Table 2609 1. This group name is also used in the Get-Subscription-Attributes 2610 and Get-Subscriptions operation with an analogous meaning. 2612 4. Extended Group Name: The 'all' group name, which names all Printer 2613 attributes according to [ipp-mod] section 3.2.5. In this extension 2614 'all' names all attributes specified in [ipp-mod] plus those named 2615 in items 1 and 2 of this list. 2617 11.2.3 Get-Subscription-Attributes operation 2619 This operation allows a client to request the values of the attributes 2620 of a Subscription Object. 2622 A Printer MUST support this operation. 2624 This operation is almost identical to the Get-Job-Attributes operation 2625 (see [ipp-mod] section 3.3.4). The only differences are that the 2626 operation is directed at a Subscription Object rather than a Job object, 2627 and the returned attribute group contains Subscription Object attributes 2628 rather than Job object attributes. 2630 11.2.3.1 Get-Subscription-Attributes Request 2632 The following groups of attributes are part of the Get-Subscription- 2633 Attributes request: 2635 Group 1: Operation Attributes 2637 Natural Language and Character Set: 2638 The "attributes-charset" and "attributes-natural-language" 2639 attributes as described in section [ipp-mod] 3.1.4.1. 2641 Target: 2642 The "printer-uri" attribute which defines the target for this 2643 operation as described in [ipp-mod] section 3.1.5. 2645 "notify-subscription-id" (integer (1:MAX)): 2646 The client MUST supply this attribute. The Printer MUST support 2647 this attribute. This attribute specifies the Subscription Object 2648 from which the client is requesting attributes. If the client omits 2649 this attribute, the Printer MUST reject this request with the 2650 'client-error-bad-request' status code. 2652 Requesting User Name: 2653 The "requesting-user-name" attribute SHOULD be supplied by the 2654 client as described in [ipp-mod] section 8.3. 2656 "requested-attributes" (1setOf keyword): 2657 The client OPTIONALLY supplies this attribute. The Printer MUST 2658 support this attribute. This attribute specifies the attributes of 2659 the specified Subscription Object that the Printer MUST return in 2660 the response. Each value of this attribute is either an attribute 2661 name (defined in sections 5.3 and 5.4) or an attribute group name. 2662 The attribute group names are: 2664 - 'subscription-template': all attributes that are both defined 2665 in section 5.3 and present on the specified Subscription 2666 Object (column 1 of Table 1). 2667 - 'subscription-description': all attributes that are both 2668 defined in section 5.4 and present on the specified 2669 Subscription Object (Table 2). 2670 - 'all': all attributes that are present on the specified 2671 Subscription Object. 2673 A Printer MUST support all these group names. 2675 If the client omits this attribute, the Printer MUST respond as if 2676 this attribute had been supplied with a value of 'all'. 2678 11.2.3.2 Get-Subscription-Attributes Response 2680 The Printer returns the following sets of attributes as part of the Get- 2681 Subscription-Attributes Response: 2683 Group 1: Operation Attributes 2685 Status Message: 2686 Same as [ipp-mod]. 2688 Natural Language and Character Set: 2689 The "attributes-charset" and "attributes-natural-language" 2690 attributes as described in [ipp-mod] section 3.1.4.2. The 2691 "attributes-natural-language" MAY be the natural language of the 2692 Subscription Object, rather than the one requested. 2694 Group 2: Unsupported Attributes 2696 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2697 Attributes. 2699 The response NEED NOT contain the "requested-attributes" operation 2700 attribute with any supplied values (attribute keywords) that were 2701 requested by the client but are not supported by the Printer. If 2702 the Printer does return unsupported attributes referenced in the 2703 "requested-attributes" operation attribute and that attribute 2704 included group names, such as 'all', the unsupported attributes 2705 MUST NOT include attributes described in the standard but not 2706 supported by the implementation. 2708 Group 3: Subscription Attributes 2710 This group contains a set of attributes with their current values. 2711 Each attribute in this group: 2713 a)MUST be specified by the "requested-attributes" attribute in the 2714 request, AND 2716 b)MUST be present on the specified Subscription Object AND 2718 c)MUST NOT be restricted by the security policy in force. For 2719 example, a Printer MAY prohibit a client who is not the creator 2720 of a Subscription Object from seeing some or all of its 2721 attributes. See [ipp-mod] section 8. 2723 The Printer can return the attributes of the Subscription Object in 2724 any order. The client MUST accept the attributes in any order. 2726 11.2.4 Get-Subscriptions operation 2728 This operation allows a client to retrieve the values of attributes of 2729 all Subscription Objects belonging to a Job or Printer. 2731 A Printer MUST supported this operation. 2733 This operation is similar to the Get-Subscription-Attributes operation, 2734 except that this Get-Subscriptions operation returns attributes from 2735 possibly more than one object. 2737 This operation is similar to the Get-Jobs operation (see [ipp-mod] 2738 section 3.2.6), except that the operation returns Subscription Objects 2739 rather than Job objects. 2741 11.2.4.1 Get-Subscriptions Request 2743 The following groups of attributes are part of the Get-Subscriptions 2744 request: 2746 Group 1: Operation Attributes 2748 Natural Language and Character Set: 2749 The "attributes-charset" and "attributes-natural-language" 2750 attributes as described in [ipp-mod] section 3.1.4.1. 2752 Target: 2753 The "printer-uri" attribute which defines the target for this 2754 operation as described in [ipp-mod] section 3.1.5. 2756 Requesting User Name: 2757 The "requesting-user-name" attribute SHOULD be supplied by the 2758 client as described in [ipp-mod] section 8.3. 2760 "notify-job-id" (integer(1:MAX)): 2761 If the client specifies this attribute, the Printer returns the 2762 specified attributes of all Per-Job Subscription Objects associated 2763 with the Job whose "job-id" attribute value equals the value of 2764 this attribute. If the client does not specify this attribute, the 2765 Printer returns the specified attributes of all Per-Printer 2766 Subscription Objects. Note: there is no way to get all Per-Job 2767 Subscriptions. 2769 "limit" (integer(1:MAX)): 2770 The client OPTIONALLY supplies this attribute. The Printer MUST 2771 support this attribute. It is an integer value that determines the 2772 maximum number of Subscription Objects that a client will receive 2773 from the Printer even if the "my-subscriptions" attribute 2774 constrains which Subscription Objects are returned. The limit is a 2775 "stateless limit" in that if the value supplied by the client is 2776 'N', then only the first 'N' Subscription Objects are returned in 2777 the Get-Subscriptions Response. There is no mechanism to allow for 2778 the next 'M' Subscription Objects after the first 'N' Subscription 2779 Objects. If the client does not supply this attribute, the Printer 2780 responds with all applicable Subscription Objects. 2782 "requested-attributes" (1setOf type2 keyword): 2783 The client OPTIONALLY supplies this attribute. The Printer MUST 2784 support this attribute. This attribute specifies the attributes of 2785 the specified Subscription Objects that the Printer MUST return in 2786 the response. Each value of this attribute is either an attribute 2787 name (defined in sections 5.3 and 5.4) or an attribute group name 2788 (defined in section 11.2.3.1). If the client omits this attribute, 2789 the Printer MUST respond as if the client had supplied this 2790 attribute with the one value: 'notify-subscription-id'. 2792 "my-subscriptions" (boolean): 2793 The client OPTIONALLY supplies this attribute. The Printer MUST 2794 support this attribute. If the value is 'false', the Printer MUST 2795 consider the Subscription Objects from all users as candidates. If 2796 the value is 'true', the Printer MUST return the Subscription 2797 Objects created by the requesting user of this request. If the 2798 client does not supply this attribute, the Printer MUST respond as 2799 if the client had supplied the attribute with a value of 'false'. 2800 The means for authenticating the requesting user and matching the 2801 Subscription Objects is similar to that for Jobs which is described 2802 in [ipp-mod] section 8. 2804 11.2.4.2 Get-Subscriptions Response 2806 The Printer returns the following sets of attributes as part of the Get- 2807 Subscriptions Response: 2809 Group 1: Operation Attributes 2811 Status Message: 2812 Same as [ipp-mod]. 2814 Natural Language and Character Set: 2815 The "attributes-charset" and "attributes-natural-language" 2816 attributes as described in [ipp-mod] section 3.1.4.2. 2818 Group 2: Unsupported Attributes 2820 Same as for Get-Subscription-Attributes. 2822 Groups 3 to N: Subscription Attributes 2824 The Printer responds with one Subscription Attributes Group for 2825 each requested Subscription Object (see the "notify-job-id" 2826 attribute in the Operation Attributes Group of this operation). 2828 The Printer returns Subscription Objects in any order. 2830 If the "limit" attribute is present in the Operation Attributes 2831 group of the request, the number of Subscription Attributes Groups 2832 in the response MUST NOT exceed the value of the "limit" attribute. 2834 It there are no Subscription Objects associated with the specified 2835 Job or Printer, the Printer MUST return zero Subscription 2836 Attributes Groups and it MUST NOT treat this case as an error, 2837 i.e., the status-code MUST be 'successful-ok' unless something else 2838 causes the status code to have some other value. 2840 See the Group 3 response (Subscription Attributes Group) of the 2841 Get-Subscription-Attributes operation (section 11.2.3.2) for the 2842 attributes that a Printer returns in this group. 2844 11.2.5 Renew-Subscription operation 2846 This operation allows a client to request the Printer to extend the 2847 lease on a Per-Printer Subscription Object. 2849 The Printer MUST support this operation. 2851 The Printer MUST accept this request for a Per-Printer Subscription 2852 Object in any of the target Printer's states, i.e., 'idle', 2853 'processing', or 'stopped', but MUST NOT change the Printer's "printer- 2854 state" attribute. 2856 The Printer MUST reject this request for a Per-Job Subscription Object 2857 because it has no lease (see section 5.4.3). The status code returned 2858 MUST be 'client-error-not-possible'. 2860 Access Rights: The authenticated user (see [IPP-MOD] section 8.3) 2861 performing this operation MUST either be the owner of the Per-Printer 2862 Subscription Object or have Operator or Administrator access rights for 2863 the Printer (see [IPP-MOD] sections 1 and 8.5). Otherwise, the Printer 2864 MUST reject the operation and return: the 'client-error-forbidden', 2865 'client-error-not-authenticated', or 'client-error-not-authorized' 2866 status code as appropriate. 2868 11.2.5.1 Renew-Subscription Request 2870 The following groups of attributes are part of the Renew-Subscription 2871 Request: 2873 Group 1: Operation Attributes 2875 Natural Language and Character Set: 2876 The "attributes-charset" and "attributes-natural-language" 2877 attributes as described in [ipp-mod] section 3.1.4.1. 2879 Target: 2880 The "printer-uri" attribute which defines the target for this 2881 operation as described in [ipp-mod] section 3.1.5. 2883 "notify-subscription-id" (integer (1:MAX)): 2884 The client MUST supply this attribute. The Printer MUST support 2885 this attribute. This attribute specifies the Per-Printer 2886 Subscription Object whose lease the Printer MUST renew. If the 2887 client omits this attribute, the Printer MUST reject this request 2888 with the 'client-error-bad-request' status code. 2890 Requesting User Name: 2891 The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied 2892 by the client as described in [ipp-mod] section 8.3. 2894 Group 2: Subscription Template Attributes 2896 "notify-lease-duration" (integer(0:MAX)): 2897 The client MAY supply this attribute. It indicates the number of 2898 seconds to renew the lease for the specified Subscription Object. 2899 A value of 0 requests an infinite lease (which MAY require Operator 2900 access rights). If the client omits this attribute, the Printer 2901 MUST use the value of the Printer's "notify-lease-duration-default" 2902 attribute. See section 5.3.7 for more details. 2904 11.2.5.2 Renew-Subscription Response 2906 The Printer returns the following sets of attributes as part of the 2907 Renew-Subscription Response: 2909 Group 1: Operation Attributes 2911 Status Message: 2912 Same as [ipp-mod]. 2914 The following are some of the status codes returned: 2916 successful-ok: The operation successfully renewed the lease on the 2917 Subscription Object for the requested duration.. 2918 successful-ok-ignored-or-substituted-attributes: The operation 2919 successfully renewed the lease on the Subscription Object for 2920 some duration other than the amount requested. 2921 client-error-not-possible: The operation failed because the 2922 "notify-subscription-id" Operation attribute identified a Per- 2923 Job Subscription Object. 2924 client-error-not-found: The operation failed because the "notify- 2925 subscription-id" Operation attribute identified a non-existent 2926 Subscription Object. 2928 Natural Language and Character Set: 2929 The "attributes-charset" and "attributes-natural-language" 2930 attributes as described in [ipp-mod] section 3.1.4.2. The 2931 "attributes-natural-language" MAY be the natural language of the 2932 Subscription Object, rather than the one requested. 2934 Group 2: Unsupported Attributes 2936 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2937 Attributes. 2939 Group 3: Subscription Attributes 2941 The Printer MUST return the following Subscription Attribute: 2943 "notify-lease-duration" (integer(0:MAX)): 2944 The value of this attribute MUST be the number of seconds that the 2945 Printer has granted for the lease of the Subscription Object (see 2946 section 5.3.7 for details, such as the value of this attribute when 2947 the Printer doesn't support the requested value). 2949 11.2.6 Cancel-Subscription operation 2951 This operation allows a client to delete a Subscription Object and stop 2952 the Printer from sending more Event Notifications. Once performed, 2953 there is no way to reference the Subscription Object. 2955 A Printer MUST supported this operation. 2957 The Printer MUST accept this request in any of the target Printer's 2958 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 2959 the Printer's "printer-state" attribute. 2961 If the specified Subscription Object is a Per-Job Subscription Object, 2962 the Printer MUST accept this request in any of the target Job's states, 2963 but MUST NOT change the Job's "job-state" attribute or affect the Job. 2965 Access Rights: The authenticated user (see [IPP-MOD] section 8.3) 2966 performing this operation MUST either be the owner of the Subscription 2967 Object or have Operator or Administrator access rights for the Printer 2968 (see [IPP-MOD] sections 1 and 8.5). Otherwise, the Printer MUST reject 2969 the operation and return: the 'client-error-forbidden', 'client-error- 2970 not-authenticated', or 'client-error-not-authorized' status code as 2971 appropriate. 2973 Note: There is no way to change any attributes on a Subscription 2974 Object, except the "notify-lease-duration" attribute (using the Renew- 2975 Subscription operation). In order to change other attributes, a client 2976 performs a Subscription Creation Operation and Cancel-Subscription 2977 operation on the old Subscription Object. If the client wants to avoid 2978 missing Event Notifications, it performs the Subscription Creation 2979 Operation first. If this order would create too many Subscription 2980 Objects on the Printer, the client reverses the order. 2982 11.2.6.1 Cancel-Subscription Request 2984 The following groups of attributes are part of the Cancel-Subscription 2985 Request: 2987 Group 1: Operation Attributes 2989 Natural Language and Character Set: 2990 The "attributes-charset" and "attributes-natural-language" 2991 attributes as described in [ipp-mod] section 3.1.4.1. 2993 Target: 2994 The "printer-uri" attribute which defines the target for this 2995 operation as described in [ipp-mod] section 3.1.5. 2997 "notify-subscription-id" (integer (1:MAX)): 2998 The client MUST supply this attribute. The Printer MUST support 2999 this attribute. This attribute specifies the Subscription Object 3000 that the Printer MUST cancel. If the client omits this attribute, 3001 the Printer MUST reject this request with the 'client-error-bad- 3002 request' status code. 3004 Requesting User Name: 3005 The "requesting-user-name" attribute SHOULD be supplied by the 3006 client as described in [ipp-mod] section 8.3. 3008 11.2.6.2 Cancel-Subscription Response 3010 The Printer returns the following sets of attributes as part of the 3011 Cancel-Subscription Response: 3013 Group 1: Operation Attributes 3015 Status Message: 3016 Same as [ipp-mod]. 3018 The following are some of the status codes returned: 3020 successful-ok: The operation successfully canceled (deleted) the 3021 Subscription Object.. 3022 client-error-not-found: The operation failed because the "notify- 3023 subscription-id" Operation attribute identified a non-existent 3024 Subscription Object. 3026 Natural Language and Character Set: 3027 The "attributes-charset" and "attributes-natural-language" 3028 attributes as described in [ipp-mod] section 3.1.4.2. The 3029 "attributes-natural-language" MAY be the natural language of the 3030 Subscription Object, rather than the one requested. 3032 Group 2: Unsupported Attributes 3034 See [ipp-mod] section 3.1.7 for details on returning Unsupported 3035 Attributes. 3037 12 Conformance Requirements 3039 It is OPTIONAL to implement this Event Notification specification. 3041 If this Event Notification specification is implemented, Printers MUST: 3043 1. meet the Conformance Requirements detailed in section 5 of [ipp-mod]. 3045 2. support all of the following attributes: 3047 a.REQUIRED Subscription Object attributes in section 5. 3049 b.REQUIRED Printer Description object attributes in section 6. 3051 c.REQUIRED attributes in Event Notification content in section 8. 3053 3. send Event Notifications that conform to the requirements of the 3054 Delivery Method Document for each supported Delivery Method (the 3055 conformance requirements for Delivery Method Documents is specified 3056 in section 10). 3058 4. support all operations as described in Table 16: 3060 Table 16 - Conformance Requirements for Operations 3062 Attribute Conformance requirements 3064 Subscription Attributes Group REQUIRED 3066 Create-Printer-Subscriptions REQUIRED 3067 (section 11.1.2) 3069 Create-Job-Subscriptions (section OPTIONAL 3070 11.1.1) 3072 Get-Subscription-Attributes (section REQUIRED 3073 11.2.2) 3075 Get-Subscriptions (section 11.2.4) REQUIRED 3077 Renew-Subscription (section 11.2.5) REQUIRED 3079 Cancel-Subscription (section 11.2.6) REQUIRED 3081 13 IANA Considerations 3083 This section describes the procedures for registering Event Notification 3084 Delivery Method proposals with IANA to be used with this document. Such 3085 Delivery Method proposals can be IETF standards track documents or 3086 vendor-defined documents. In either case, they will be registered with 3087 IANA using procedures that extend those defined in [ipp-mod] section 6 3088 and 11. 3090 These extension procedures are aligned with the guidelines as set forth 3091 by the IESG [IANA-CON]. Section 13.1 defines the format and content for 3092 new registrations for consideration. IANA will reject registration 3093 proposals that leave out required information or do not follow the 3094 appropriate format described in Section 13.1. 3096 Implementers can, at any time, define new Event Notification Delivery 3097 Methods by proposing the complete specification to IANA: 3099 iana@iana.org 3101 or by filling out the appropriate form on the IANA web pages 3102 (http://www.iana.org). 3104 IANA will forward the registration proposal to the IPP Designated Expert 3105 who will review the proposal with a mailing list that the Designated 3106 Expert keeps for this purpose. Initially, that list will be the mailing 3107 list used by the IPP WG: 3109 ipp@pwg.org 3111 even after the IPP WG is disbanded as permitted by [IANA-CON]. The IPP 3112 Designated Expert is appointed by the IESG Area Director responsible for 3113 IPP, according to [IANA-CON]. 3115 When a Delivery Method Document is approved, the IPP Designated Expert 3116 becomes the point of contact for any future maintenance that might be 3117 required for that registration. 3119 13.1 Format and Requirements for IPP Delivery Method Registration 3120 Proposals 3122 This section defines the format and requirements for an IPP Event 3123 Notification Delivery Method Registration Proposal. A Delivery Method 3124 Registration Proposal: 3126 1. MUST contain the following information: 3128 Type of registration: IPP Event Notification Delivery Method 3129 Name of this delivery method: 3130 Proposed URL scheme name of this delivery method: 3131 Name of proposer: 3132 Address of proposer: 3133 Email address of proposer: 3134 Is this delivery method REQUIRED or OPTIONAL for conformance to the 3135 IPP Event Notification Specification document: 3136 Is this delivery method defining Machine Consumable and/or Human 3137 Consumable content: 3139 2. MUST meet the conformance requirements for Delivery Method Documents 3140 specified in section 10. 3142 14 Internationalization Considerations 3144 This IPP Notification specification continues support for the 3145 internationalization of [ipp-mod] of attributes containing text strings 3146 and names. Allowing a Subscribing Client to specify a different natural 3147 language and charset for each Subscription Object increases the 3148 internationalization support. 3150 The Printer MUST be able to localize the content of Human Consumable 3151 Event Notifications and to localize the value of "notify-text" attribute 3152 in Machine Consumable Event Notifications that it sends to Notification 3153 Recipients. For localization, the Printer MUST use the value of the 3154 "notify-charset" attribute and the "notify-natural-language" attribute 3155 in the Subscription Object supplied by the Subscribing Client. 3157 15 Security Considerations 3159 By far the biggest security concern is the abuse of notification: 3160 sending unwanted Event Notifications to third parties (i.e., spam). The 3161 problem is made worse by notification addresses that may be 3162 redistributed to multiple parties (e.g., mailing lists). There exist 3163 scenarios where third party notification is required (see Scenario #2 3164 and #3 in [ipp-not-req]). The fully secure solution would require 3165 active agreement of all recipients before sending out anything. 3166 However, requirement #9 in [ipp-req] ("There is no requirement for IPP 3167 Printer receiving the print request to validate the identity of an Event 3168 recipient") argues against this. Certain systems may decide to disallow 3169 third party Event Notifications (a traditional fax model). 3171 Clients submitting Notification requests to the IPP Printer has the same 3172 security issues as submitting an IPP/1.1 print job request. The same 3173 mechanisms used by IPP/1.1 can therefore be used by the client 3174 Notification submission. Operations that require authentication can use 3175 the HTTP authentication. Operations that require privacy can use the 3176 HTTP/TLS privacy. 3178 The Notification access control model should be similar to the IPP 3179 access control model for Jobs. Creating a Per-Printer Subscription 3180 Object is associated with a user. Only the creator or an Operator can 3181 cancel the Subscription Object. The system may limit the listing of 3182 items to only those items owned by the user. Some Subscription Objects 3183 (e.g., those that have a lifetime longer than a job) can be done only by 3184 privileged users (users having Operator and/or Administrator access 3185 rights), if that is the authorization policy. 3187 The standard security concerns (delivery to the right user, privacy of 3188 content, tamper proof content) apply to the Delivery Method. IPP should 3189 use the security mechanism of the Delivery Method used. Some delivery 3190 mechanisms are more secure than others. Therefore, sensitive Event 3191 Notifications should use the Delivery Method that has the strongest 3192 security. 3194 16 Status Codes 3196 The following status codes are defined as extensions for Notification 3197 and are returned as the value of the "status-code" parameter in the 3198 Operation Attributes Group of a response (see [ipp-mod] section 3199 3.1.6.1). Operations in this document can also return the status codes 3200 defined in section 13 of [ipp-mod]. The 'successful-ok' status code is 3201 an example of such a status code. 3203 16.1 successful-ok-ignored-subscriptions (0x0003) 3205 The Subscription Creation Operation was unable to create all requested 3206 Subscription Objects. 3208 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3209 operation, this status code means that the Printer created one or more 3210 Subscription Objects, but not all requested Subscription Objects. 3212 For a Job Creation operation, this status code means that the Printer 3213 created the Job along with zero or more Subscription Objects. The 3214 Printer returns this status code even if other job attributes are 3215 unsupported or in conflict. That is, if an IPP Printer finds a warning 3216 that would allow it to return 'successful-ok-ignored-subscriptions' and 3217 either 'successful-ok-ignored-or-substituted-attributes' and/or 3218 'successful-ok-conflicting-attributes', it MUST return 'successful-ok- 3219 ignored-subscriptions'. 3221 16.2 client-error-ignored-all-subscriptions (0x0414) 3223 This status code is the same as 'successful-ok-ignored-subscriptions' 3224 except that only the Create-Job-Subscriptions and Create-Printer- 3225 Subscriptions operation return it. They return this status code only 3226 when the Printer creates zero Subscription Objects. 3228 17 Status Codes in Subscription Attributes Groups 3230 This section contains values of the "notify-status-code" attribute that 3231 the Printer returns in a Subscription Attributes Group in a response 3232 when the corresponding Subscription Object: 3234 1. is not created or 3236 2. is created and some of the client-supplied attributes are not 3237 supported. 3239 The following sections are ordered in decreasing order of importance of 3240 the status-codes. 3242 17.1 client-error-uri-scheme-not-supported (0x040C) 3244 This status code is defined in [ipp-mod]. This document extends its 3245 meaning and allows it to be in a Subscription Attributes Group of a 3246 response. 3248 The scheme of the client-supplied URI in a "notify-recipient-uri" 3249 Subscription Template Attribute in a Subscription Creation Operation is 3250 not supported. See section 5.3.1. 3252 17.2 client-error-too-many-subscriptions (0x0415) 3254 The number of Subscription Objects supported by the Printer would be 3255 exceeded if this Subscription Object were created (see section 5.2). 3257 17.3 successful-ok-too-many-events (0x0005) 3259 The client supplied more Events in the "notify-events" operation 3260 attribute of a Subscription Creation Operation than the Printer 3261 supports, as indicated in its "notify-max-events-supported" Printer 3262 attribute (see section 5.3.2). 3264 17.4 successful-ok-ignored-or-substituted-attributes (0x0001) 3266 This status code is defined in [ipp-mod]. This document extends its 3267 meaning to include unsupported Subscription Template Attributes and it 3268 can appear in a Subscription Attributes Group. 3270 18 Encodings of Additional Attribute Tags 3272 This section assigns values to two attributes tags as extensions to the 3273 encoding defined in [ipp-pro]). 3275 The "subscription-attributes-tag" delimits Subscription Template 3276 Attributes Groups in requests and Subscription Attributes Groups in 3277 responses. 3279 The "event-notification-attributes-tag" delimits Event Notifications in 3280 Delivery Methods that use an IPP-like encoding. 3282 The following table specifies the values for the delimiter tags: 3284 Tag Value (Hex) Meaning 3286 0x06 "subscription-attributes-tag" 3287 0x07 "event-notification-attributes-tag" 3289 19 References 3291 [IANA-CON] 3292 Narte, T. and Alvestrand, H.T.: Guidelines for Writing an IANA 3293 Considerations Section in RFCs, Work in Progress, draft-iesg-iana- 3294 considerations-04.txt, May 21, 1998. 3296 [ipp-mod] 3297 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3298 "Internet Printing Protocol/1.1: Model and Semantics", , work in progress, May 22, 2000. 3301 [ipp-not-req] 3302 deBry, R., Lewis, H., Hastings, T., "Internet Printing 3303 Protocol/1.1: Requirements for IPP Notifications", , work in progress, July 6, 2000. 3306 [ipp-pro] 3307 Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing 3308 Protocol/1.1: Encoding and Transport", , work in progress, May 30, 2000. 3311 [ipp-prog] 3312 Hastings, T., Bergman, R., Lewis, H., "IPP: Job Progress 3313 Attributes", work in 3314 progress, July 6, 2000. 3316 [ipp-set] 3317 Kugler, C., , Hastings, T., Herriot, R., Lewis, H, "Internet 3318 Printing Protocol (IPP): Job and Printer Set Operations", , work in progress, March 23, 3320 2000. 3322 [RFC2026] 3323 S. Bradner, "The Internet Standards Process -- Revision 3", RFC 3324 2026, October 1996. 3326 [RFC2119] 3327 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3328 Levels", RFC 2119 , March 1997 3330 [RFC2566] 3331 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3332 "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, 3333 April 1999. 3335 [RFC2567] 3336 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3337 2567, April 1999. 3339 [RFC2568] 3340 Zilles, S., "Rationale for the Structure and Model and Protocol for 3341 the Internet Printing Protocol", RFC 2568, April 1999. 3343 [RFC2569] 3344 Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between 3345 LPD and IPP Protocols", RFC 2569, April 1999. 3347 20 Author's Addresses 3349 Scott A. Isaacson (Editor) 3350 Novell, Inc. 3351 122 E 1700 S 3352 Provo, UT 84606 3354 Phone: 801-861-7366 3355 Fax: 801-861-2517 3356 e-mail: sisaacson@novell.com 3358 Tom Hastings 3359 Xerox Corporation 3360 737 Hawaii St. ESAE 231 3361 El Segundo, CA 90245 3363 Phone: 310-333-6413 3364 Fax: 310-333-5514 3365 e-mail: hastings@cp10.es.xerox.com 3367 Robert Herriot 3368 Xerox Corporation 3369 3400 Hillview Ave., Bldg #1 3370 Palo Alto, CA 94304 3372 Phone: 650-813-7696 3373 Fax: 650-813-6860 3374 Email: robert.herriot@pahv.xerox.com 3376 Roger deBry 3377 Utah Valley State College 3378 Orem, UT 84058 3380 Phone: (801) 222-8000 3381 EMail: debryro@uvsc.edu 3383 Jay Martin 3384 e-mail: jkm@underscore.com 3386 Michael Shepherd 3387 Xerox Corporation 3388 800 Phillips Road MS 128-51E 3389 Webster, NY 14450 3391 Phone: 716-422-2338 3392 Fax: 716-265-8871 3393 e-mail: mshepherd@crt.xerox.com 3394 Ron Bergman (Editor) 3395 Hitachi Koki Imaging Solutions 3396 1757 Tapo Canyon Road 3397 Simi Valley, CA 93063-3394 3399 Phone: 805-578-4421 3400 Fax: 805-578-4001 3401 Email: rbergma@hitachi-hkis.com 3403 A. Appendix - Model for Notification with Cascading Printers 3405 With this model (see Figure 2), there is an intervening Print server 3406 between the human user and the output-device. So the system effectively 3407 has two Printers. There are two cases to consider. 3409 1. When the Printer 1 (in the server) generates Events, the system 3410 behaves like the client and Printer in Figure 1. In this case, 3411 Printer 1 sends Event Notifications that are shown as Event 3412 Notifications (A) of Figure 2,. 3414 2. When the Printer 2 (in the output-device) generates Events, there 3415 are two possible system configurations: 3417 a)Printer 1 forwards the client-supplied Subscription Creation 3418 Operations to the downstream Printer 2 and lets Printer 2 send 3419 the Event Notifications directly to the Notification Recipients 3420 supplied by the Client (Event Notifications(C) in the diagram). 3422 b)Printer 1 performs the client-supplied Subscription Creation 3423 Operations and also forwards the Subscription Creation 3424 Operations to Printer 2 with the Notification Recipient changed 3425 to be the Printer 1. When an Event occurs in Printer 2, Printer 3426 2 sends the Event Notification (B) to Notification Recipient of 3427 Printer 1, which relays the received Event Notification (B) to 3428 the client-supplied Notification Recipient (as Event 3429 Notifications(A) in the diagram). Note, when a client performs a 3430 Subscription Creation Operation, Printer 1 need not forward the 3431 Subscription Creation Operation to Printer 2 if it would create 3432 a duplicate Subscription Object on Printer 2. 3434 Note: when Printer 1 is forwarding Subscription Creation Operations to 3435 Printer 2, it may request Printer 2 to create additional Subscription 3436 Objects (called "piggy-backing"). Piggy-backing is useful when: 3438 . Device A is configured to accept (IPP or non-IPP) requests from 3439 other servers. 3441 . Server S wants to receive Job Events that the client didn't request 3442 and Server S wants these Events for jobs it submits and not for 3443 other jobs. 3445 server S device A 3446 +------------+ +------------+ 3447 | | | | 3448 +--------+ Subscription | ###########| | ###########| 3449 | client |--Creation ----># Printer #| Subscription | # Printer #| 3450 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 3451 | ###|#######| Operation | ####|#|####| 3452 +----|---^---+ +-----|-|----+ 3453 +--------+ Event | | | | 3454 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 3455 |ation Re|<-------------Event Notifications(C)-----------------+ 3456 |cipient | 3457 +--------+ 3459 Figure 2 - Model for Notification with Cascading Printers 3461 B. Appendix - Distributed Model for Notification 3463 A Printer implementation could use some other remote notification 3464 service to provide some or most of the service. For example, the remote 3465 notification service could send Event Notifications using Delivery 3466 Methods that are not directly supported by the output device or server. 3467 Or, the remote notification service could store Subscription Objects 3468 (passed to it from the output device in response to Subscription 3469 Creation requests), accept Events, format the Event Notification in the 3470 natural language of the Notification Recipient, and send the Event 3471 Notifications to the Notification Recipient(s). 3473 Figure 3 shows this partitioning. The interface between the output 3474 device (or server) and the remote notification service is outside the 3475 scope of this document and is intended to be transparent to the client 3476 and this document. The combination of the output device (or server) and 3477 the notification service together constitute an IPP Printer conforming 3478 to this Notification document. 3480 *********************** 3481 * 3482 * Printer (including 3483 * the distributed 3484 * Notification Service) 3485 * 3486 * output device or server 3487 * +---------------+ 3488 PDA, desktop, or server * + ########### + 3489 +--------+ * | # partial # | 3490 | client |---IPP Subscription--------># Printer # | 3491 +--------+ Creation operation * | # Object # | 3492 * | #####|##### | 3493 * +-------|-------+ 3494 * | Subscriptions 3495 * | OR Event 3496 +------------+ * | Notifications 3497 |Notification| IPP-defined * +------v--------+ 3498 |Recipient |<--Event Notifications---| Notification | 3499 +------------+ * | Service | 3500 * +---------------+ 3501 * 3502 ************************* 3503 *** = Implementation configuration opaque boundary 3505 Figure 3 - Opaque Use of a Notification Service Transparent to the 3506 Client 3508 C. Appendix - Extended Notification Recipient 3510 The model allows for an extended Notification Recipient that is itself a 3511 notification service that forwards each Event Notification to another 3512 recipient (called the Ultimate Notification Recipient in this section). 3513 The Delivery Method to the Ultimate Recipient is probably different from 3514 the Delivery Method used by the Printer to the extended Notification 3515 Recipient. 3517 This extended Notification Recipient is transparent to the Printer but 3518 not to the client. 3520 When a client performs a Subscription Creation Operation, it specifies 3521 the extended Notification Recipient as it would any Notification 3522 Recipient. In addition, the client specifies the Ultimate Notification 3523 Recipient in the Subscription Creation Operation in a manner specified 3524 by the extended Notification Recipient. Typically, it is either some 3525 bytes in the value of "notify-user-data" or some additional parameter in 3526 the value of "notify-recipient-uri". The client also subscribes directly 3527 with the extended Notification Recipient (by means outside this 3528 document), since it is a notification service in its own right. 3530 The IPP Printer treats the extended Notification Recipient like any 3531 other Notification Recipient and the IPP Printer is not aware of the 3532 forwarding. The Delivery Method that the extended Notification Recipient 3533 uses for delivering the Event Notification to the Ultimate Notification 3534 Recipient is beyond the scope of this document and is transparent to the 3535 IPP Printer. 3537 Examples of this extended Notification Recipient are paging, immediate 3538 messaging services, general notification services, and NOS vendors' 3539 infrastructure. Figure 4 shows this approach. 3541 PDA, desktop, or server server or output device 3542 +---------------+ 3543 +--------+ | ########### | 3544 | client |---Subscription Creation -----------># Printer # | 3545 +--------+ Operation | # Object # | 3546 | #####|##### | 3547 +------------+ +------------+ IPP-defined +-------|-------+ 3548 |Ultimate | any |Notification|<--Event Notifications----+ 3549 |Notification|<----|Recipient | 3550 |Recipient | +------------+ 3551 +------------+ (Notification Service) 3553 Figure 4 - Use of an Extended Notification Recipient transparent to the 3554 Printer 3556 D. Appendix - Details about Conformance Terminology 3558 The following paragraph provide more details about conformance 3559 terminology. 3561 REQUIRED - an adjective used to indicate that a conforming IPP 3562 Printer implementation MUST support the indicated operation, 3563 object, attribute, attribute value, status code, or out-of-band 3564 value in requests and responses. See [ipp-mod] "Appendix A - 3565 Terminology for a definition of "support". Since support of this 3566 entire Notification specification is OPTIONAL for conformance to 3567 IPP/1.0 or IPP/1.1, the use of the term REQUIRED in this document 3568 means "REQUIRED if this OPTIONAL Notification specification is 3569 implemented". 3571 RECOMMENDED - an adjective used to indicate that a conforming IPP 3572 Printer implementation is recommended to support the indicated 3573 operation, object, attribute, attribute value, status code, or out- 3574 of-band value in requests and responses. Since support of this 3575 entire Notification specification is OPTIONAL for conformance to 3576 IPP/1.0 or IPP/1.1, the use of the term RECOMMENDED in this 3577 document means "RECOMMENDED if this OPTIONAL Notification 3578 specification is implemented". 3580 OPTIONAL - an adjective used to indicate that a conforming IPP 3581 Printer implementation MAY, but is NOT REQUIRED to, support the 3582 indicated operation, object, attribute, attribute value, status 3583 code, or out-of-band value in requests and responses. 3585 E. Appendix - Object Model for Notification 3587 This section describes the Notification object model that adds a 3588 Subscription Object which together with the Job and Printer object 3589 provide the complete Notification semantics. 3591 The object relationships can be seen pictorially as: 3593 Subscription Objects (Per-Printer Subscriptions) Printer object 3594 +----+ +------------+ 3595 | s1 |<---------------------------------------------->| | 3596 +----++ | | 3597 | s2 |<--------------------------------------------->| p1 | 3598 +----++ | | 3599 | s3 |<-------------------------------------------->| | 3600 +----+ +------------+ 3601 Job objects 3602 +---------+ 3603 | | 3604 +----+ | j1 | 3605 | s4 |<-------->| | 3606 +----+ | | 3607 | | s4 is a Per-Job Subscription Object 3608 ++--------++ 3609 | | 3610 +----+ | j2 | 3611 | s5 |<------->| | 3612 +----++ | | 3613 | s6 |<------>| | s5 and s6 are Per-Job Subscription 3614 +----+ ++--------++ Objects 3615 | | 3616 | j3 | 3617 | | 3618 | | <----> indicates association 3619 +---------+ 3621 Figure 5 - Object Model for Notification 3623 s1, s2, and s3 are Per-Printer Subscription Objects and can 3624 identify Printer and/or Job Events. 3625 s4, s5, and s6 are Per-Job Subscription Objects and can identify 3626 Printer and/or Job Events. 3628 E.1 Appendix - Object relationships 3630 This sub-section defines the object relationships between the Printer, 3631 Job, and Subscription Objects by example. Whether Per-Printer 3632 Subscription Objects are actually contained in a Printer object or are 3633 just bi-directionally associated with them in some way is IMPLEMENTATION 3634 DEPENDENT and is transparent to the client. Similarly, whether Per-Job 3635 Subscription Objects are actually contained in a Job object or are just 3636 bi-directionally associated with them in some way is IMPLEMENTATION 3637 DEPENDENT and is transparent to the client. The object relationships 3638 are defined as follows: 3640 E.2 Printer Object and Per-Printer Subscription Objects 3642 1. The Printer object contains (is associated with) zero or more Per- 3643 Printer Subscription Objects (p1 contains s1-s3 Per-Printer 3644 Subscription Objects). 3646 2. Each Per-Printer Subscription Object (s1, s2, and s3) is contained 3647 in (or is associated with) exactly one Printer object (p1). 3649 E.3 Job Object and Per-Job Subscription Objects 3651 1. A Job object (j1, j2, j3) is associated with zero or more Per-Job 3652 Subscription Objects (s4-s6). Job j1 is associated with Per-Job 3653 Subscription Object s4, Job j2 is associated with Per-Job 3654 Subscription Objects s5 and s6, and Job j3 is not associated with 3655 any Per-Job Subscription Object. 3657 2. Each Per-Job Subscription Object is associated with exactly one Job 3658 object. 3660 F. Appendix - Per-Job versus Per-Printer Subscription Objects 3662 Per-Job and Per-Printer Subscription Objects are quite similar. Either 3663 type of Subscription Object can subscribe to Job Events, Printer Events, 3664 or both. Both types of Subscription Objects can be queried using the 3665 Get-Subscriptions and Get-Subscription-Attributes operations and 3666 canceled using the Cancel-Subscription operation. Both types of 3667 Subscription Objects create Subscription Objects which have the same 3668 Subscription Object attributes defined. However, there are some 3669 semantic differences between Per-Job Subscription Objects and Per- 3670 Printer Subscription Objects. A Per-Job Subscription Object is 3671 established by the client when submitting a job and after creating the 3672 job using the Create-Job-Subscriptions operation by specifying the "job- 3673 id" of the Job with the "notify-job-id" attribute. A Per-Printer 3674 Subscription Object is established between a client and a Printer using 3675 the Create-Printer-Subscriptions operation. Some specific differences 3676 are: 3678 1.A client usually creates one or more Per-Job Subscription Objects as 3679 part of the Job Creation operations (Create-Job, Print-Job, and 3680 Print-URI), rather than using the OPTIONAL Create-Job-Subscriptions 3681 operation, especially since Printer implementations NEED NOT support 3682 the Create-Job-Subscriptions operation, since it is OPTIONAL. 3684 2.For Per-Job Subscription Objects, the Subscription Object is only 3685 valid while the job is "not-complete" (see sections 5.4.3) while for 3686 the Per-Printer Subscription Objects, the Subscription Object is 3687 valid until the time (in seconds) that the Printer returned in the 3688 "notify-lease-expiration-time" operation attribute. 3690 3.Job Events in a Per-Job Subscription Object apply only to "one job" 3691 (the Job created by the Job Creation operation or references by the 3692 Create-Job-Subscriptions operation) while Job Events in a Per-Printer 3693 Subscription Object apply to ALL jobs contained in the IPP Printer. 3695 G. Appendix: Full Copyright Statement 3697 Copyright (C) The Internet Society (1998,1999,2000). All Rights Reserved 3699 This document and translations of it may be copied and furnished to 3700 others, and derivative works that comment on or otherwise explain it or 3701 assist in its implementation may be prepared, copied, published and 3702 distributed, in whole or in part, without restriction of any kind, 3703 provided that the above copyright notice and this paragraph are included 3704 on all such copies and derivative works. However, this document itself 3705 may not be modified in any way, such as by removing the copyright notice 3706 or references to the Internet Society or other Internet organizations, 3707 except as needed for the purpose of developing Internet standards in 3708 which case the procedures for copyrights defined in the Internet 3709 Standards process must be followed, or as required to translate it into 3710 languages other than English. 3712 The limited permissions granted above are perpetual and will not be 3713 revoked by the Internet Society or its successors or assigns. 3715 This document and the information contained herein is provided on an "AS 3716 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 3717 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 3718 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 3719 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 3720 FITNESS FOR A PARTICULAR PURPOSE.