idnits 2.17.1 draft-ietf-ipp-not-spec-05.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. 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 1423 has weird spacing: '...ipients do no...' == Line 2412 has weird spacing: '...rameter retur...' == Line 3706 has weird spacing: '...reation opera...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If the client supplies an unsupported scheme in the value of this attribute, then the Printer MUST not create the Subscription Object and MUST return the "notify-status-code" attribute with the 'client-error-uri-scheme-not-supported' value in the Subscription Attributes Group in the response. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute, the Printer MUST not populate this attribute on the Subscription Object. There is no "notify-time-interval-default" attribute. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: successful-ok: the Printer created the Job and all Subscription Objects requested. successful-ok-ignored-subscriptions: the Printer created the Job and not all of the Subscription Objects requested. This status-code hides 'successful-ok-xxx' status-codes that could reveal problems in Job creation. The Printer MUST not return the 'client-error-ignored-all-subscriptions' status code for Job Creation operations because the Printer returns an error status-code only when it fails to create a Job. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The Printer MUST accept requests that are identical to the Job Creation request defined in section 11.1.3.1, except that the request MUST not contain document data. -- 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 (August 30, 2000) is 8633 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 2978, 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 3340, 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 (~~), 16 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 Category: standards track T. Hastings 5 Xerox Corporation 6 R. deBry 7 Utah Valley State College 8 S. Isaacson 9 Novell, Inc. 10 J. Martin 11 Underscore 12 M. Shepherd 13 Xerox Corporation 14 R. Bergman 15 Hitachi Koki Imaging Solutions 16 August 30, 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 basic set of IPP documents includes: 59 Design Goals for an Internet Printing Protocol [RFC2567] 60 Rationale for the Structure and Model and Protocol for the Internet 61 Printing Protocol [RFC2568] 62 Internet Printing Protocol/1.1: Model and Semantics [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 .......................................................9 114 1.1 Notification Overview .........................................9 116 2 Models for Notification ...........................................12 117 2.1 Model for Notification (Simple Case) .........................12 118 2.2 Model for Notification with Cascading Printers ...............13 119 2.3 Distributed Model for Notification ...........................13 120 2.4 Extended Notification Recipient ..............................14 122 3 Terminology .......................................................14 123 3.1 Conformance Terminology ......................................14 124 3.2 Other Terminology ............................................14 126 4 Object Relationships ..............................................17 127 4.1 Printer and Per-Printer Subscription Objects .................18 128 4.2 Printer, Job and Per-Job Subscription Objects ................18 130 5 Subscription Object ...............................................18 131 5.1 Rules for Support of Subscription Template Attributes ........19 132 5.2 Rules for Processing Subscription Template Attributes ........20 133 5.3 Subscription Template Attributes .............................24 134 5.3.1 notify-recipient-uri (uri) ...............................25 135 5.3.2 notify-events (1setOf type2 keyword) .....................26 136 5.3.3 notify-attributes (1setOf type2 keyword) .................32 137 5.3.4 notify-user-data (octetString(63)) .......................34 138 5.3.5 notify-charset (charset) .................................34 139 5.3.6 notify-natural-language (naturalLanguage) ................35 140 5.3.7 notify-lease-duration (integer(0:67108863)) ..............35 141 5.3.8 notify-time-interval (integer(0:MAX)) ....................37 142 5.4 Subscription Description Attributes ..........................38 143 5.4.1 notify-subscription-id (integer (1:MAX)) ................39 144 5.4.2 notify-sequence-number (integer (0:MAX)) .................39 145 5.4.3 notify-lease-expiration-time (integer(0:MAX)) ............40 146 5.4.4 notify-printer-up-time (integer(1:MAX)) ..................41 147 5.4.5 notify-printer-uri (uri) .................................41 148 5.4.6 notify-job-id (integer(1:MAX)) ...........................42 149 5.4.7 notify-subscriber-user-name (name(MAX)) ..................42 151 6 Printer Description Attributes Related to Notification ............43 152 6.1 printer-state-change-time (integer(1:MAX)) ...................43 153 6.2 printer-state-change-date-time (dateTime) ....................44 155 7 New Values for Existing Printer Description Attributes ............44 156 7.1 operations-supported (1setOf type2 enum) .....................44 158 8 Attributes Only in Event Notifications ............................45 159 8.1 notify-subscribed-event (type2 keyword) ......................45 160 8.2 notify-text (text(MAX)) ......................................45 162 9 Event Notification Content ........................................46 163 9.1 Content of Machine Consumable Event Notifications ............48 164 9.1.1 Event Notification Content Common to All Events ..........49 165 9.1.2 Additional Event Notification Content for Job Events .....50 166 9.1.3 Additional Event Notification Content for Printer Events .51 167 9.2 Content of Human Consumable Event Notification ...............52 168 9.2.1 Event Notification Content Common to All Events ..........53 169 9.2.2 Additional Event Notification Content for Job Events .....55 170 9.2.3 Additional Event Notification Content for Printer Events .56 172 10Delivery Methods ..................................................57 174 11Operations for Notification .......................................60 175 11.1 Subscription Creation Operations .............................60 176 11.1.1Create-Job-Subscriptions Operation .......................60 177 11.1.2Create-Printer-Subscriptions operation ...................63 178 11.1.3Job Creation Operation - Extensions for Notification .....64 179 11.2 Other Operations .............................................67 180 11.2.1Validate-Job Operation - Extensions for Notification .....67 181 11.2.2Get-Printer-Attributes - Extensions for Notification .....67 182 11.2.3Get-Subscription-Attributes operation ....................68 183 11.2.4Get-Subscriptions operation ..............................71 184 11.2.5Renew-Subscription operation .............................73 185 11.2.6Cancel-Subscription operation ............................76 187 12Conformance Requirements ..........................................78 189 13IANA Considerations ...............................................79 190 13.1 Format and Requirements for IPP Delivery Method Registration 191 Proposals .........................................................80 193 14Internationalization Considerations ...............................81 195 15Security Considerations ...........................................81 197 16Status Codes ......................................................82 198 16.1 successful-ok-ignored-subscriptions (0x0003) .................82 199 16.2 client-error-ignored-all-subscriptions (0x0414) ..............82 201 17Status Codes in Subscription Attributes Groups ....................83 202 17.1 client-error-uri-scheme-not-supported (0x040C) ...............83 203 17.2 client-error-too-many-subscriptions (0x0415) .................83 204 17.3 successful-ok-too-many-events (0x0005) .......................83 205 17.4 successful-ok-ignored-or-substituted-attributes (0x0001) .....84 207 18Encodings of Additional Attribute Tags ............................84 209 19References ........................................................84 210 20Author's Addresses ................................................85 212 A.Appendix - Model for Notification with Cascading Printers .........87 214 B.Appendix - Distributed Model for Notification .....................88 216 C.Appendix - Extended Notification Recipient ........................89 218 D.Appendix - Details about Conformance Terminology ..................90 220 E.Appendix - Object Model for Notification ..........................91 221 E.1 Appendix - Object relationships ..............................92 222 E.2 Printer Object and Per-Printer Subscription Objects ..........93 223 E.3 Job Object and Per-Job Subscription Objects ..................93 225 F.Appendix - Per-Job versus Per-Printer Subscription Objects ........93 227 G.Appendix: Full Copyright Statement ................................94 229 Tables 230 Table 1 - Subscription Template Attributes...........................25 231 Table 2 - Subscription Description Attributes........................38 232 Table 3 - Printer Description Attributes Associated with Notification43 233 Table 4 - Operation-id assignments...................................44 234 Table 5 - Attributes in Event Notification Content...................49 235 Table 6 - Additional Event Notification Content for Job Events.......50 236 Table 7 - Combinations of Events and Subscribed Events for "job- 237 impressions-completed" ...........................................51 238 Table 8 - Additional Event Notification Content for Printer Events...51 239 Table 9 - Printer Name in Event Notification Content.................54 240 Table 10 - Event Name in Event Notification Content..................54 241 Table 11 - Event Time in Event Notification Content..................55 242 Table 12 - Job Name in Event Notification Content....................55 243 Table 13 - Job State in Event Notification Content...................56 244 Table 14 - Printer State in Event Notification Content...............56 245 Table 15 - Information about the Delivery Method.....................58 246 Table 16 - Conformance Requirements for Operations...................79 248 Figures 249 Figure 1 - Model for Notification....................................12 250 Figure 2 - Model for Notification with Cascading Printers............88 251 Figure 3 - Opaque Use of a Notification Service Transparent to the 252 Client ...........................................................89 253 Figure 4 - Use of an Extended Notification Recipient transparent to the 254 Printer ..........................................................90 255 Figure 5 - Object Model for Notification.............................92 256 1 Introduction 258 This IPP notification specification is an extension to IPP/1.0 [RFC2568, 259 RFC2569] and IPP/1.1 [ipp-mod, ipp-pro]. This document in combination 260 with the following documents is intended to meet the notification 261 requirements described in [ipp-not-req]: 263 Internet Printing Protocol (IPP): "Job Progress Attributes" [ipp- 264 prog] 265 One or more Delivery Method Documents registered with IANA (see 266 section 13). 268 Note: this document does not define any Delivery Methods, but it does 269 define the rules for conformance for Delivery Method Documents. 271 Refer to the Table of Contents for the layout of this document. 273 1.1 Notification Overview 275 This document defines operations that a client can perform in order to 276 create Subscription Objects in a Printer and carry out other operations 277 on them. A Subscription Object represents a Subscription abstraction. 278 The Subscription Object specifies that when one of the specified Events 279 occurs, the Printer sends an asynchronous Event Notification to the 280 specified Notification Recipient via the specified Delivery Method 281 (i.e., protocol). 283 When a client (called a Subscribing Client) performs an operation that 284 creates a Subscription Object, the operation contains one or more 285 Subscription Template Attributes Groups. Each such group holds 286 information used by the Printer to initialize a newly created 287 Subscription Object. The Printer creates one Subscription Object for 288 each Subscription Template Attributes Group in the operation. This group 289 is like the Job Template Attributes group defined in [ipp-mod]. The 290 following is an example of the information included in a Subscription 291 Template Attributes Group (see section 5 for details on the Subscription 292 Object attributes): 294 1. The names of Subscribed Events that are of interest to the 295 Notification Recipient. 296 2. The address (URL) of one Notification Recipient. 297 3. The Delivery Method (i.e., the protocol) which the Printer uses to 298 send the Event Notification. 300 4. Some opaque data that the Printer sends to the Notification 301 Recipient in the Event Notification. The Notification Recipient 302 might use this opaque data as a forwarding address for the Event 303 Notification. 304 5. The charset to use in text fields within an Event Notification 305 6. The natural language to use in the text fields of the Event 306 Notification 307 7. The requested lease time in seconds for the Subscription Object 309 An operation that creates a Subscription Object is called a Subscription 310 Creation Operation. These operations include the following operations 311 (see section 11.1 for further details): 313 . Job Creation operation: When a client performs such an operation 314 (Print-Job, Print-URI, and Create-Job), a client can include zero 315 or more Subscription Template Attributes Groups in the request. 316 The Printer creates one Subscription Object for each Subscription 317 Template Attributes Group in the request, and the Printer 318 associates each such Subscription Object with the newly created 319 Job. This document extends these operations' definitions in [ipp- 320 mod] by adding Subscription Template Attributes Groups in the 321 request and Subscription Attributes Groups in the response. 323 . Create-Job-Subscriptions operation: A client can include one or 324 more Subscription Template Attributes Groups in the request. The 325 Printer creates one Subscription Object for each Subscription 326 Template Attributes Group and associates each with the job that is 327 the target of this operation. 329 . Create-Printer-Subscriptions operation: A client can include one or 330 more Subscription Template Attributes Groups in the request. The 331 Printer creates one Subscription Object for each Subscription 332 Template Attributes Group and associates each with the Printer that 333 is the target of this operation. 335 For each of the above operations: 337 . the Printer associates a Subscription Object with the Printer or a 338 specific Job. When a Subscription Object is associated with a Job 339 Object, it is called a Per-Job Subscription Object. When a 340 Subscription Object is associated with a Printer Object, it is 341 called a Per-Printer Subscription Object. 343 . the response contains one Subscription Attributes Group for each 344 Subscription Template Attributes Group in the request and in the 345 same order. When the Printer successfully creates a Subscription 346 Object, its corresponding Subscription Attributes Group contains 347 the "notify-subscription-id" attribute. This attribute uniquely 348 identifies the Subscription Object and is analogous to a "job-id" 349 for a Job object. Some operations described below use the "notify- 350 subscription-id" to identify the target Subscription Object. 352 This document defines the following additional operations (see section 353 11.2 for further details): 355 . Validate-Job operation: When a client performs this operation, a 356 client can include zero or more Subscription Template Attributes 357 Groups in the request. The Printer determines if it could create 358 one Subscription Object for each Subscription Template Attributes 359 Group in the request. This document extends this operation's 360 definition in [ipp-mod] by adding Subscription Template Attributes 361 Groups in the request and Subscription Attributes Groups in the 362 response. 364 . Get-Subscription-Attributes operation: This operation allows a 365 client to obtain the specified attributes of a target Subscription 366 Object. 368 . Get-Subscriptions operation: This operation allows a client to 369 obtain the specified attributes of all Subscription Objects 370 associated with the Printer or a specified Job. 372 . Renew-Subscription operation: This operation renews the lease on 373 the target Per-Printer Subscription Object before it expires. A 374 newly created Per-Printer Subscription Object receives an initial 375 lease. It is the duty of the client to use this operation 376 frequently enough to preserve a Per-Printer Subscription Object. 377 The Printer deletes a Per-Printer Subscription Object when its 378 lease expires. A Per-Job Subscription Object last exactly as long 379 as its associated Job Object and thus doesn't have a lease. 381 . Cancel-Subscription operation: This operation cancels the lease on 382 the specified Per-Printer Subscription Object and thereby deletes 383 the Subscription Object. 385 When an Event occurs, the Printer finds all Subscription Objects 386 listening for the Event (see section 9 for details on finding such 387 Subscription Objects). For each such Subscription Object, the Printer: 388 a) generates an Event Notification with information specified in 389 section 9, AND 390 b) either: 391 i)delivers the Event Notification using the Delivery Method and 392 target address identified in the Subscription Object's "notify- 393 recipient-uri" attribute if the Delivery Method is a "push", OR 394 ii) saves Event Notification for a time period defined by the 395 Delivery Method if the Delivery Method is a "pull", i.e., the 396 Notification Recipient is expected to fetch the Event 397 Notifications. 399 2 Models for Notification 401 2.1 Model for Notification (Simple Case) 403 As part of a Subscription Creation Operation, an IPP Printer (i.e., 404 located in an output device or a server) creates one or more 405 Subscription Objects. In a Subscription Creation Operation, the client 406 specifies the Notification Recipient to which the Printer is to deliver 407 Event Notifications. A Notification Recipient can be the Subscribing 408 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. Other 476 terminology is defined in [ipp-mod]. 478 3.1 Conformance Terminology 480 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 481 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 482 conformance to this specification. These terms are defined in 483 [ipp-mod section 13.1 on conformance terminology, most of which is 484 taken from RFC 2119 [RFC2119]. See Appendix D for complete details. 486 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 487 the Printer implements a Delivery Method that REQUIRES the feature 489 READ-ONLY - an adjective used in an attribute definition to indicate 490 that an IPP Printer MUST NOT allow the attribute's value to be 491 modified with the Set-Job-Attributes or Set-Printer-Attributes 492 operations (see [ipp-set]). Note: there is no Set-Subscription 493 operation so this term is not used for Subscription object 494 attributes. 496 3.2 Other Terminology 498 Administrator - A human user who establishes policy for and 499 configures the print system. 501 Operator - A human user who carries out the policy established by the 502 Administrator and controls the day to day running of the print 503 system. 505 IPP Client (or client) - The software component (PDA, desktop, or 506 server) that performs an IPP operation directed at an IPP Printer 507 (located in a server or output device). 509 Job Creation operation - One of the operations that creates a Job 510 object: Print-Job, Print-URI and Create-Job. The Validate-Job 511 operation is not a Job Creation operation because no Job object is 512 created. Therefore, when a statement also applies to the Validate- 513 Job operation, it is mentioned explicitly. 515 Event - some occurrence (either expected or unexpected) within the 516 printing system of a change of state, condition, or configuration 517 of a Job or Printer object. An Event occurs only at one instant in 518 time and does not span the time the physical Event takes place. 519 For example, jam-occurred and jam-cleared are two distinct, 520 instantaneous Events, even though the jam may last for a while. 522 Job Event - an Event caused by some change in a particular job on the 523 Printer, e.g., job-completed. 525 Printer Event - an Event caused by some change in the Printer that is 526 not specific to a job, e.g., printer-state-changed. 528 Subscribed Event - an Event that the Subscribing Client expresses 529 interest in by making it a value of the "notify-events" attribute 530 on a Subscription Object. 532 Subscribed Job Event - a Subscribed Event that is a Job Event. 534 Subscribed Printer Event - a Subscribed Event that is a Printer 535 Event. 537 Event Notification - the information about an Event that the Printer 538 sends when an Event occurs. 540 Notification Recipient - the entity to which the Printer sends an 541 Event Notification. 543 Delivery Method - the mechanism by which the Printer delivers the 544 Event Notification, e.g., via email or via SNMP. 546 Delivery Method Document - a document, separate from this document, 547 that defines a Delivery Method. 549 Compound Event Notification - two or more Event Notifications that a 550 Printer sends together as a single entity. The Delivery Method 551 Document specifies whether the Delivery Method supports Compound 552 Event Notifications. 554 Subscription Object - An object containing a set of attributes that 555 indicate: the Notification Recipient, the Delivery Method, the 556 Subscribed Events that cause the Printer to send an Event 557 Notification, and the information to send in an Event Notification. 559 Per-Job Subscription Object - A Subscription Object that is 560 associated with a single Job. The Create-Job-Subscriptions 561 operation and Job Creation operations create such an object. 563 Per-Printer Subscription Object - A Subscription Object that is 564 associated with the Printer as a whole. The Create-Printer- 565 Subscriptions operation creates such an object. 567 Subscribing Client - The client that creates the Subscription Object. 569 Subscription Creation Operation - An operation that creates a 570 Subscription Object: Job Creation operations, Create-Job- 571 Subscriptions operation, and Create-Printer-Subscriptions 572 operation. In the context of a Job Creation operation, a 573 Subscription Creation Operation is the part of the Job Creation 574 operation that creates a Subscription object. 576 Subscription Creation Request - The request portion of a 577 Subscription Creation Operation. 579 Subscription Template Attributes - Subscription Object attributes 580 that a client can supply in a Subscription Creation Operation and 581 associated Printer Object attributes that specify supported and 582 default values for the Subscription Object attributes. 584 Subscription Description Attributes - Subscription Object attributes 585 that a Printer supplies during a Subscription Creation Operation. 587 Subscription Template Attributes Group - The attributes group in a 588 request that contains Subscription Object attributes that are 589 Subscription Template Attributes. 591 Subscription Attributes Group - The attributes group in a response 592 that contains Subscription Object attributes. 594 Human Consumable Event Notification - localized text for human 595 consumption only. There is no standardized format and thus 596 programs should not try to parse this text. 598 Machine Consumable Event Notification - bytes for program 599 consumption. The bytes are formatted according to the Delivery 600 Method document. 602 Printer - the software that supports an output device or print server 603 (see IPP/1.1 [ipp-mod] which uses the terms Printer and Printer 604 object interchangeably). This document extends the IPP/1.1 Printer 605 definition to include the software that implements Subscription 606 Creation Operations and the sending of Event Notifications, even if 607 the software for such a Printer would be distributed across a 608 network (see section 2.3). 610 Notification - when not in the phrases 'Event Notification' and 611 'Notification Recipient' - the concepts of this specification, 612 i.e., Events, Subscription Objects, and Event Notifications. 614 4 Object Relationships 616 This section defines the object relationships between the Printer, Job, 617 and Subscription Objects. It does not define the implementation. For an 618 illustration of these relationships, see Appendix E. 620 4.1 Printer and Per-Printer Subscription Objects 622 1. A Printer object can be associated with zero or more Per-Printer 623 Subscription Objects. 625 2. Each Per-Printer Subscription Object is associated with exactly one 626 Printer object. 628 4.2 Printer, Job and Per-Job Subscription Objects 630 1. A Printer object is associated with zero or more Job objects. 632 2. Each Job object is associated with exactly one Printer object. 634 3. A Job object is associated with zero or more Per-Job Subscription 635 Objects. 637 4. Each Per-Job Subscription Object is associated with exactly one Job 638 object. 640 5 Subscription Object 642 A Subscribing Client creates a Subscription Object with a Subscription 643 Creation Operation in order to indicate its interest in certain Events. 644 See section 11 for a description of these operations. When an Event 645 occurs, the Subscription Object specifies to the Printer where to send 646 Event Notifications, how to send them and what to put in them. See 647 section 9 for details on the contents of an Event Notification. 649 Using the IPP Job Template attributes as a model (see [ipp-mod] section 650 4.2), the attributes of a Subscription Object are divided into two 651 categories: Subscription Template Attributes and Subscription 652 Description Attributes. 654 Subscription Template attributes are, in turn, like the Job Template 655 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 in section 5.3, Table 1 specifies corresponding 681 Printer attributes: "notify-xxx-default", "notify-xxx-supported", 682 "yyy-supported" and "notify-max-xxx-supported" defined in column 2 683 of Table 1. Note "xxx" stands for the same string in each case and 684 "yyy" stands for some other string. 686 3. If a Printer supports "notify-xxx" in column 1 of Table 1, then the 687 Printer MUST support all associated attributes specified in column 688 2 of Table 1. For example, Table 1 shows that if the Printer 689 supports "notify-events", it MUST support "notify-events-default", 690 "notify-events-supported" and "notify-max-events-supported". 692 4. If a Printer does not support "notify-xxx" in column 1 of Table 1, 693 then the Printer MUST NOT support any associated "notify-yyy" 694 attributes specified in column 2 of Table 1. For example, Table 1 695 shows that if the Printer doesn't support "notify-events", it MUST 696 NOT support "notify-events-default", "notify-events-supported" and 697 "notify-max-events-supported". Note this rule does not apply to 698 attributes whose names do not start with the string "notify-" and 699 are thus defined in another object and used by other attributes. 701 5. Most "notify-xxx" attributes have a corresponding "yyy-supported" 702 attribute that specifies the supported values for "notify-xxx". 703 Column 2 of Table 1 specifies the name of each "yyy-supported" 704 attribute. The naming rules of IPP/1.1 (see [ipp-mod]) are used 705 when "yyy-supported" is "notify-xxx-supported". 707 6. Some "notify-xxx" attributes have a corresponding "notify-xxx- 708 default" attribute that specifies the value for "notify-xxx" if the 709 client does not supply it. Column 2 of Table 1 specifies the name 710 of each "notify-xxx-default" attribute. The naming rules of IPP/1.1 711 (see [ipp-mod]) are used. 713 If a client wishes to present an end user with a list of supported 714 values from which to choose, the client SHOULD query the Printer for its 715 supported value attributes. The client SHOULD also query the default 716 value attributes. If the client then limits selectable values to only 717 those values that are supported, the client can guarantee that the 718 values supplied by the client in the create request all fall within the 719 set of supported values at the Printer. When querying the Printer, the 720 client MAY enumerate each attribute by name in the Get-Printer- 721 Attributes Request, or the client MAY just supply the 'subscription- 722 template' group name in order to get the complete set of supported 723 attributes (both supported and default attributes). 725 5.2 Rules for Processing Subscription Template Attributes 727 This section defines a detailed set of rules that a Printer follows when 728 it processes Subscription Template Attributes in a Subscription Creation 729 Request. These rules for are similar to the rules for processing 730 Operation attributes in [ipp-mod]. That is, the Printer may or may not 731 support an attribute and a client may or may not supply the attribute. 732 Some combinations of these cases are OK. Others return warnings or 733 errors, and perhaps a list of unsupported attributes. 735 A Printer MUST implement the following behavior for processing 736 Subscription Template Attributes in a Subscription Creation Request: 738 1. If a client supplies a "notify-xxx" attribute from column 1 of 739 Table 1 and the Printer supports it and its value, the Printer MUST 740 populate the attribute on the created Subscription Object. 742 2. If a client supplies a "notify-xxx" attribute from column 1 of 743 Table 1 and the Printer doesn't support it or its value, the 744 Printer MUST NOT populate the attribute on the created Subscription 745 Object with it. The Printer MUST do one of the following: 747 a)If the value of the "notify-xxx" attribute is unsupported, the 748 Printer MUST return the attribute with its value in the 749 Subscription Attributes Group of the response. 751 b)If "notify-xxx" is an unsupported attribute, the Printer MUST 752 return the attribute in the Subscription Attributes Group of the 753 response with the 'unsupported' out-of-band value. 755 Note: The rules of this step are the same as for Unsupported 756 Attributes [ipp-mod] section 3.1.7. except that the unsupported 757 attributes are returned in the Subscription Attributes Group rather 758 than the Unsupported Attributes Group because Subscription Creation 759 Operations can create more than one Subscription Object). 761 3. If a client is REQUIRED to supply a "notify-xxx" attribute from 762 column 1 of Table 1 and the Printer doesn't support the supplied 763 value, the Printer MUST NOT create a Subscription Object. The rules 764 for Unsupported Attributes in step #2 still apply. 766 4. If a client does not supply a "notify-xxx" attribute from column 1 767 of Table 1 and the attribute is REQUIRED for the client to supply, 768 the Printer MUST reject the Subscription Creation Operation 769 (including Job Creation operations) without creating a Subscription 770 Object, and MUST return in the response: 772 c)the status code 'client-error-bad-request' AND 774 d)no Subscription Attribute Groups. 776 5. If a client does not supply a "notify-xxx" attribute from column 1 777 of Table 1 that is OPTIONAL for the client to supply, and column 2 778 of Table 1 either: 780 a)specifies a "notify-xxx-default" attribute, the Printer MUST 781 behave as if the client had supplied the "notify-xxx-default" 782 attribute (see step #1) and populate the Subscription object 783 with the value of the "notify-xxx-default" attribute as part of 784 the Subscription Creation operation (unlike Job Template 785 attributes where the Printer does not populate the Job object 786 with defaults - see [ipp-mod]) OR 788 b)does not specify a "notify-xxx-default" attribute, the Printer 789 MUST populate the "notify-xxx" attribute on the Subscription 790 Object according to the definition of the "notify-xxx" attribute 791 in a section 5.3. For some attributes, the "notify-xxx" is 792 populated with the value of some other attribute, and for 793 others, the "notify-xxx" is NOT populated on the Subscription 794 object at all. 796 6. A Printer MUST create a Subscription Object for each Subscription 797 Template Attributes group in a request unless the Printer: 799 a)encounters some attributes in a Subscription Template Attributes 800 Group that require the Printer not to create the Subscription 801 Object OR 803 b)would create a Per-Job Subscription Object when it doesn't have 804 space for another Per-Job Subscription Object OR 806 c)would create a Per-Printer Subscription Object when it doesn't 807 have space for another Per-Printer Subscription Object. 809 7. A response MUST contain one Subscription Attributes Group for each 810 Subscription Template Attributes Group in the request (and in the 811 same order) whether the Printer creates a Subscription Object from 812 the Subscription Template Attributes Group or not. However, the 813 attributes in each Subscription Attributes Group can be in any 814 order. 816 8. The Printer MUST populate each Subscription Attributes Group of the 817 response such that each contains: 819 a)the "notify-subscription-id" attribute (see section 5.4.1), if 820 and only if the Printer creates a Subscription Object. 822 b)the "notify-lease-duration" attribute (see section 5.3.7), if 823 and only if the Printer creates a Per-Printer Subscription 824 Object. The value of this attribute is the value of the 825 Subscription Object's "notify-lease-duration" attribute. This 826 value MAY be different from the client-supplied value (see 827 section 5.3.7). If a client supplies this attribute in the 828 creation of a Per-Job Subscription Object, it MUST appear in 829 this group with the out-of-band value 'unsupported' to indicate 830 that the Printer doesn't support it in this context. 832 c)all of the unsupported Subscription Template Attributes from 833 step #2. Note, they are not returned in the Unsupported 834 Attributes Group in order to separate the unsupported attributes 835 for each Subscription Object. 837 d)the "notify-status-code" attribute if the Printer does not 838 create the Subscription Object or if there are unsupported 839 attributes from step #2. The possible values of the "notify- 840 status-code" attribute are shown below (see section 17 for more 841 details). The Printer returns the first value in the list below 842 that describes the status. 844 'client-error-uri-scheme-not-supported': the Subscription 845 Object was not created because the scheme of the "notify- 846 recipient-uri" attribute is not supported. See section 17.1 847 for more details about this status code. See step #3 in 848 this section for the case that causes this error, and the 849 resulting step #6a) that causes the Printer not to create 850 the Subscription Object. 852 'client-error-too-many-subscriptions': the Subscription 853 Object was not created because the Printer has no space for 854 additional Subscription Objects. The client SHOULD try 855 again later. See section 17.2 for more details about this 856 status code. See steps #6b) and #6c) in this section for 857 the cases that causes this error. 859 'successful-ok-too-many-events': the Subscription Object was 860 created without the "notify-events" values included in this 861 Subscription Attributes Group because the "notify-events" 862 attribute contains too many values. See section 17.3 for 863 more details about this status code. See step #2 in this 864 section and section 5.3.2 for the cases that cause this 865 status code. 867 'successful-ok-ignored-or-substituted-attributes' : the 868 Subscription Object was created but some supplied 869 Subscription Template Attributes are unsupported. These 870 unsupported attributes are also in the Subscription 871 Attributes Group. See section 17.4 for more details about 872 this status code. See step #2 in this section for the cases 873 that cause this status code. 875 9. The Printer MUST validate all Subscription Template Attributes and 876 MUST return all unsupported attributes and values in the 877 corresponding Subscription Attributes Group of the response (see 878 step #2) unless it determines that it could not create additional 879 Subscription Objects because of condition #6b) or condition #6c). 880 Then, the Printer NEED NOT validate these additional Subscription 881 Template Attributes and the client MUST NOT expect to find 882 unsupported attributes from step #2 in such additional Subscription 883 Attribute Groups. 885 5.3 Subscription Template Attributes 887 This section contains the Subscription Template Attributes defined for 888 the Subscription and Printer objects. 890 Table 1 below shows the Subscription Template Attributes and has two 891 columns: 893 . Attribute in Subscription Object: the name and attribute syntax of 894 each Subscription Object Attribute that is a Subscription Template 895 Attribute 897 . Default and Supported Printer Attributes: the default attribute and 898 supported Printer attributes that are associated with the attribute 899 in column 1. 901 A Printer MUST support all attributes in Table 1 below except for 902 "notify-attributes" (and "notify-attributes-supported"). A client MUST 903 supply "notify-recipient-uri" and MAY omit any of the rest of the 904 attributes in column 1 of Table 1 in a Subscription Creation Request. 906 Table 1 - Subscription Template Attributes 908 Attribute in Subscription Default and Supported Printer 909 Object Attributes 911 notify-recipient-uri (uri) notify-schemes-supported (1setOf 912 uriScheme) 914 notify-events (1setOf type2 notify-events-default (1setOf type2 915 keyword) keyword) 916 notify-events-supported (1setOf type2 917 keyword) 918 notify-max-events-supported 919 (integer(2:MAX)) 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.1Standard 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-stopped'. 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. 1124 Examples of "configuration" Job attributes are any of the job 1125 template attributes and the "job-name" attribute. Often, such a 1126 change is the result of the user or the Operator performing a Set- 1127 Job-Attributes operation (see [ipp-set]) on the Job object. The 1128 client performs a Get-Job-Attributes to find out the new values of 1129 the changed attributes. This Event is useful for GUI clients and 1130 drivers to update the job information to the user. 1132 'job-progress': OPTIONAL - when the Printer has completed Printing a 1133 sheet. See the separate [ipp-prog] specification for additional 1134 attributes that a Printer MAY send in an Event Notification caused 1135 by this Event. The "notify-time-interval" attribute affects this 1136 Event by causing the Printer NOT to send an Event Notification 1137 every time a 'job-progress' Events occurs. See section 5.3.8 for 1138 full details. 1140 5.3.2.2Rules for Matching of Subscribed Events 1142 When an Event occurs, the Printer MUST find each Subscription object 1143 whose "notify-events" attribute "matches" the Event. The rules for 1144 "matching" of Subscribed Events are described separately for Printer 1145 Events and for Job Events. This section also describes some special 1146 cases. 1148 5.3.2.2.1 Rules for Matching of Printer Events 1150 Suppose that the Printer causes Printer Event E to occur. For each Per- 1151 Job or Per-Printer Subscription S in the Printer, if E equals a value of 1152 this attribute in S or E is a sub-value of a value of this attribute in 1153 S, the Printer MUST generate an Event Notification. 1155 Consider the example. There are three Subscription Objects each with 1156 the Subscribed Printer Event 'printer-state-changed'. Subscription 1157 Object A is a Per-Printer Subscription Object. Subscription Object B 1158 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1159 is a Per-Job Subscription Object for Job 2. When the Printer enters 1160 the 'stopped' state, the Printer sends an Event Notification to the 1161 Notification Recipients of Subscription Objects A, B, and C because 1162 this is a Printer Event. Note if Job 1 has already completed, the 1163 Printer would not send an Event Notification for its Subscription 1164 Object. 1166 5.3.2.2.2 Rules for Matching of Job Events 1168 Suppose that Job J causes Job Event E to occur. 1170 1. For each Per-Printer Subscription S in the Printer, if E equals a 1171 value of this attribute in S or E is a sub-value of a value of this 1172 attribute in S, the Printer MUST generate an Event Notification. 1174 2. For each Per-Job Subscription S associated with Job J, if E equals 1175 a value of this attribute in S or E is a sub-value of a value of 1176 this attribute in S, the Printer MUST generate an Event 1177 Notification. 1179 3. For each Per-Job Subscription S that is NOT associated Job J, if E 1180 equals a value of this attribute in S or E is a sub-value of a 1181 value of this attribute in, the Printer MUST NOT generate an Event 1182 Notification from S. 1184 Consider the example: There are three Subscription Objects listening 1185 for the Job Event 'job-completed'. Subscription Object A is a Per- 1186 Printer Subscription Object. Subscription Object B is a Per-Job 1187 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1188 Subscription Object for Job 2. In addition, Per-Printer Subscription 1189 Object D is listening for the Job Event 'job-state-changed'. When Job 1190 1 completes, the Printer sends an Event Notification to the 1191 Notification Recipient of Subscription Object A (because it is Per- 1192 Printer) and Subscription Object B because it is a Per-Job 1193 Subscription Object associated with the Job generating the Event. 1194 The Printer also sends an Event Notification to the Notification 1195 Recipient of Subscription Object D because 'job-completed' is a sub- 1196 value of 'job-state-changed' - the value that Subscription Object D 1197 is listening for. The Printer does not send an Event Notification to 1198 the Notification Recipients of Subscription Object C because it is a 1199 Per-Job Subscription Object associated with some Job other than the 1200 Job generating the Event. 1202 5.3.2.2.3 Special Cases for Matching Rules 1204 This section contains rule for special cases. 1206 If an Event matches Subscribed Events in two different Subscription 1207 Objects and the Printer would send two identical Event Notifications 1208 (except for the "notify-subscription-id" attribute) to the same 1209 Notification Recipient using the same Delivery Method, the Printer MUST 1210 send both Event Notifications. That is, the Printer MUST NOT try to 1211 consolidate seemingly identical Event Notifications that occur in 1212 separate Subscription objects. Incidentally, the Printer MUST NOT reject 1213 Subscription Creation Operations that would create this scenario. 1215 If an Event matches two values of this "notify-events" attribute in a 1216 single Subscription object (e.g., a value and its sub-value), a Printer 1217 MAY send one Event Notification for each matched value in the 1218 Subscription Object or it MAY send only one Event Notification per 1219 Subscription Object. The rules in sections 5.3.2.2.1 and 5.3.2.2.2 are 1220 purposefully ambiguous about the number of Event Notification sent when 1221 Event E matches two or more values in a Subscription Object. 1223 Consider the example: There are two Per-Printer Subscription Objects 1224 when a Job completes. Subscription Object A has the Subscribed Job 1225 Event 'job-state-changed'. Subscription Object B has the Subscribed 1226 Job Events 'job-state-changed' and 'job-completed'. The Printer sends 1227 an Event Notification to the Notification Recipient of Subscription 1228 Object A with the value of 'job-state-changed' for the "notify- 1229 subscribing-event" attribute. The Printer sends either one or two 1230 Event Notifications to the Notification Recipient of Subscription 1231 Object B, depending on implementation. If it sends two Event 1232 Notifications, one has the value of 'job-state-changed' for the 1233 "notify-subscribing-event" attribute, and the other has the value of 1234 'job-completed' for the "notify-subscribing-event" attribute. If it 1235 sends one Event Notification, it has the value of either 'job-state- 1236 changed' or 'job-completed' for the "notify-subscribing-event" 1237 attribute, depending on implementation. The algorithm for choosing 1238 such a value is implementation dependent. 1240 5.3.3 notify-attributes (1setOf type2 keyword) 1242 This attribute contains a set of attribute names. When a Printer sends a 1243 Machine Consumable Event Notification, it includes a fixed set of 1244 attributes (see section 9.1). If this attribute is present and the Event 1245 Notification is Machine Consumable, the Printer also includes the 1246 attributes specified by this attribute. 1248 A Printer MAY support this attribute. 1250 A client MAY supply this attribute in a Subscription Creation Operation. 1251 If the client does not supply this attribute in Subscription Creation 1252 Operation or the Printer does not support this attribute, the 1253 Subscription Object MUST NOT contain the "notify-attributes" attribute. 1254 There is no "notify-attributes-default" attribute. 1256 Each keyword value of this attribute on a Subscription Object MUST be a 1257 value of the "notify-attributes-supported (1setOf type2 keyword)" 1258 attribute. The "notify-attributes-supported" MAY contain any Printer 1259 attribute, Job attribute or Subscription Object attribute that the 1260 Printer supports in an Event Notification. It MUST NOT contain any of 1261 the attributes in Section 9.1 that a Printer automatically puts in an 1262 Event Notification; it would be redundant. If a client supplies an 1263 attribute in Section 9.1, the Printer MUST treat it as an unsupported 1264 attribute value of the "notify-attributes" attribute. 1266 The following rules apply to each keyword value N of the "notify- 1267 attributes" attribute: If the value N names: 1269 a) a Subscription attribute, the Printer MUST use the attribute N in 1270 the Subscription Object that is being used to generate the Event 1271 Notification. 1273 b) a Job attribute and the Printer is generating an Event Notification 1274 from a Per-Job Subscription Object S, the Printer MUST use the 1275 attribute N in the Job object associated with S. 1277 c) a Job attribute and the Printer is generating an Event Notification 1278 from a Per-Printer Subscription Object and the Event is: 1280 . a Job Event, the Printer MUST use the attribute N in the Job 1281 object that caused the Event. 1283 . a Printer Event, the Printer MUST use the attribute N in the 1284 active Job. 1286 If a Printer supports this attribute and a Subscription Object contains 1287 this attribute and the Delivery Method generates a Machine Consumable 1288 Event Notification, the Printer MUST include in each Event Notification: 1290 a)the attributes specified in section 9.1 and 1292 b)each attribute named by this attribute. 1294 The Printer MUST NOT use this attribute to generate a Human Consumable 1295 Event Notification. 1297 5.3.4 notify-user-data (octetString(63)) 1299 This attribute contains opaque data that some Delivery Methods include 1300 in each Machine Consumable Event Notification. The opaque data might 1301 contain, for example: 1303 . the identity of the Subscriber 1305 . a path or index to some Subscriber information 1307 . a key that identifies to the Notification Recipient the ultimate 1308 recipient of the Event Notification 1310 . the id for a Notification Recipient that had previously registered 1311 with an Instant Messaging Service 1313 A Printer MUST support this attribute. 1315 A client MAY supply this attribute in a Subscription Creation Operation. 1316 If the client does not supply this attribute in Subscription Creation 1317 Operation, the Subscription Object MUST NOT contain the "notify-user- 1318 data" attribute. There is no "notify-user-data-default" attribute. 1320 There is no "user-data-supported" attribute. Rather, any octetString 1321 whose length does not exceed 63 octets is a supported value. If the 1322 length exceeds 63 octets, the Printer MUST treat it as an unsupported 1323 value. 1325 5.3.5 notify-charset (charset) 1327 This attribute specifies the charset to be used in the Event 1328 Notification content sent to the Notification Recipient, whether the 1329 Event Notification content is Machine Consumable or Human Consumable. 1331 A Printer MUST support this attribute. 1333 A client MAY supply this attribute in a Subscription Creation Operation. 1334 If the client does not supply this attribute in Subscription Creation 1335 Operation or supplies an unsupported value, the Printer MUST populate 1336 this attribute in the Subscription Object with the value of the 1337 "attributes-charset" operation attribute, which is a REQUIRED attribute 1338 in all IPP requests (see [ipp-mod]). If the value of the "attributes- 1339 charset" attribute is unsupported, the Printer MUST populate this 1340 attribute in the Subscription Object with the value of the Printer's 1341 "charset-configured" attribute. There is no "notify-charset-default" 1342 attribute. 1344 The value of this attribute on a Subscription Object MUST be a value of 1345 the "charset-supported (1setOf charset)" attribute. 1347 5.3.6 notify-natural-language (naturalLanguage) 1349 This attribute specifies the natural language to be used in any human 1350 consumable text in the Event Notification content sent to the 1351 Notification Recipient, whether the Event Notification content is 1352 Machine Consumable or Human Consumable. 1354 A Printer MUST support this attribute. 1356 A client MAY supply this attribute in a Subscription Creation Operation. 1357 If the client does not supply this attribute in Subscription Creation 1358 Operation or supplies an unsupported value, the Printer MUST populate 1359 this attribute in the Subscription Object with the value of the 1360 "attributes-natural-language" operation attribute, which is a REQUIRED 1361 attribute in all IPP requests (see [ipp-mod]). If the value of the 1362 "attributes-natural-language" attribute is unsupported, the Printer MUST 1363 populate this attribute in the Subscription Object with the value of the 1364 Printer's "natural-language-configured" attribute. There is no "notify- 1365 natural-language-default" attribute. 1367 The value of this attribute on a Subscription Object MUST be a value of 1368 the "generated-natural-language-supported (1setOf type2 1369 naturalLanguage)" attribute. 1371 5.3.7 notify-lease-duration (integer(0:67108863)) 1373 This attribute specifies the duration of the lease (in seconds) 1374 associated with the Per-Printer Subscription Object at the time the 1375 Subscription Object was created or the lease was renewed. The duration 1376 of the lease is infinite if the value is 0, i.e., the lease never 1377 expires. 1379 This attribute is not present on a Per-Job Subscription Object because 1380 the Subscription Object lasts exactly as long as the associated Job 1381 object. See section 5.4.3 on "notify-lease-expiration-time 1382 (integer(0:MAX))" for more details. 1384 A Printer MUST support this attribute. 1386 For a Subscription Object Creation operation of a Per-Job Subscription 1387 Object, the client MUST NOT supply this attribute. If the client does 1388 supply this attribute, the Printer MUST treat it as an unsupported 1389 attribute. 1391 For a Subscription Creation Operation of a Per-Printer Subscription 1392 Object or a Renew-Subscription operation, a client MAY supply this 1393 attribute. If the client does not supply this attribute, the Printer 1394 MUST populate this attribute with its "notify-lease-duration-default" 1395 (0:67108863) attribute value. If the client supplies this attribute with 1396 an unsupported value, the Printer MUST populate this attribute with a 1397 supported value, and this value SHOULD be as close as possible to the 1398 value requested by the client. Note: this rule implies that a Printer 1399 doesn't assign the value of 0 (infinite) unless the client requests it. 1401 After the Printer has populated this attribute with a supported value, 1402 the value represents the "granted duration" of the lease in seconds and 1403 the Printer sets the value of the Subscription Object's "notify-lease- 1404 expiration-time" attribute as specified in section 5.4.3. 1406 The value of this attribute on a Subscription Object MUST be a value of 1407 the "notify-lease-duration-supported" (1setOf (integer(0:67108863) | 1408 rangeOfInteger(0:67108863))) attribute. 1410 A Printer MAY require authentication in order to return the value of 0 1411 (the lease never expires) as one of the values of "notify-lease- 1412 duration-supported", and to allow 0 as a value of the "notify-lease- 1413 duration" attribute. 1415 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1 1416 and is about 2 years in seconds. The value is considerably less than 1417 MAX so that there is virtually no chance of an overflow when it is added 1418 to "printer-up-time" to produce "notify-lease-expiration-time". 1420 5.3.8 notify-time-interval (integer(0:MAX)) 1422 The 'job-progress' Event occurs each time that a Printer completes a 1423 sheet. Some Notification Recipients do not want to receive an Event 1424 Notification every time this Event occurs. This attribute allows a 1425 Subscribing Client to request how often it wants to receive Event 1426 Notifications for 'job-progress' Events. The value of this attribute MAY 1427 be any nonnegative integer (0,MAX) indicating the minimum number of 1428 seconds between 'job-progress' Event Notifications. 1430 The Printer MUST support this attribute if and only if the Printer 1431 supports the 'job-progress' Event. 1433 A client MAY supply this attribute in a Subscription Creation Operation. 1434 If the client does not supply this attribute, the Printer MUST not 1435 populate this attribute on the Subscription Object. There is no "notify- 1436 time-interval-default" attribute. 1438 There is no "notify-time-interval-supported" attribute. 1440 If the 'job-progress' Event occurs and a Subscription Object contains 1441 the 'job-progress' Event as a value of the 'notify-events' attribute, 1442 there are two cases to consider: 1444 1. This attribute is not present on the Subscription Object or has the 1445 value of 0. The Printer MUST generate and send an Event 1446 Notification (as is the case with other Events). 1448 2. This attribute is present with a nonzero value of N: 1450 a)If the Printer has not sent an Event Notification for the 'job- 1451 progress' Event for the associated Subscription Object within 1452 the past N seconds, the Printer MUST send an Event Notification 1453 for the Event that just occurred. Note when the Printer 1454 completes the first page of a Job, this rule implies that the 1455 Printer sends an Event Notification for a Per-Job Subscription 1456 Objects. 1458 b)Otherwise, the Printer MUST NOT generate or send an Event 1459 Notification for the associated Subscription Object. The Printer 1460 MUST NOT increase the value of the "notify-sequence-number" 1461 Subscription Object attribute (i.e., the sequence of values of 1462 the "notify-sequence-number" attribute counts the Event 1463 Notifications that the Printer sent and not the Events that do 1464 not cause an Event Notification to be sent). 1466 It is RECOMMENDED that a Subscribing Client use this attribute when it 1467 subscribes to the 'job-progress' Event, and that the value be 1468 sufficiently large to limit the frequency with which the Printer sends 1469 Event Notifications requests. 1471 This attribute MUST NOT effect any Events other than 'job-progress'. 1473 5.4 Subscription Description Attributes 1475 Subscription Description Attributes are those attributes that a Printer 1476 adds to a Subscription Object at the time of its creation. 1478 A Printer MUST support all attributes in this Table 2. 1480 A client MUST NOT supply the attributes in Table 2 in a Subscription 1481 Template Attributes Group of a Subscription Creation Operation. If the 1482 client supplies them, the Printer MUST NOT set them and MUST treat them 1483 as unsupported attributes. There are no corresponding default or 1484 supported attributes. 1486 Table 2 - Subscription Description Attributes 1488 Subscription Object attributes: 1490 notify-subscription-id (integer(1:MAX)) 1492 notify-sequence-number (integer(0:MAX)) 1494 notify-lease-expiration-time (integer(0:MAX)) 1496 notify-printer-up-time (integer(1:MAX)) 1497 Subscription Object attributes: 1499 notify-printer-uri (uri) 1501 notify-job-id (integer(1:MAX)) 1503 notify-subscriber-user-name (name(MAX)) 1505 5.4.1 notify-subscription-id (integer (1:MAX)) 1507 This attribute identifies a Subscription Object instance with a number 1508 that is unique within the context of the Printer. The Printer generates 1509 this value at the time it creates the Subscription Object. 1511 A Printer MUST support this attribute. 1513 The Printer SHOULD NOT assign the value of this attribute sequentially 1514 as it creates Subscription Objects. Sequential assignment makes it easy 1515 for rogue clients to guess the value of this attribute on other 1516 Subscription Objects. 1518 The Printer SHOULD avoid re-using recent values of this attribute during 1519 continuous operation of the Printer as well as across power cycles. Then 1520 a Subscribing Client is unlikely to find that a stale reference accesses 1521 a new Subscription Object. 1523 The 0 value is not permitted in order to allow for compatibility with 1524 "job-id" and with SNMP index values, which also cannot be 0. 1526 5.4.2 notify-sequence-number (integer (0:MAX)) 1528 The value of this attribute indicates the number of times that the 1529 Printer has generated and attempted to send an Event Notification. When 1530 an Event Notification contains this attribute, the Notification 1531 Recipient can determine whether it missed some Event Notifications 1532 (i.e., numbers skipped) or received duplicates (i.e., same number 1533 twice). 1535 A Printer MUST support this attribute. 1537 When the Printer creates a Subscription Object, it MUST set the value of 1538 this attribute to 0. This value indicates that the Printer has not sent 1539 any Event Notifications for this Subscription Object. 1541 Each time the Printer sends a newly generated Event Notification, it 1542 MUST increase the value of this attribute by 1. For some Delivery 1543 Methods, the Printer MUST include this attribute in each Event 1544 Notification, and the value MUST be the value after it is increased by 1545 1. That is, the value of this attribute in the first Event Notification 1546 after Subscription object creation MUST be 1, the second MUST be 2, etc. 1547 If a Delivery Method is defined such that the Notification Recipient 1548 returns a response, the Printer can re-try sending an Event Notification 1549 a certain number of times with the same sequence number when the 1550 Notification Recipient fails to return a response. 1552 If a Subscription Object lasts long enough to reach the value of MAX, 1553 its next value MUST be 0, i.e., it wraps. 1555 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1557 This attribute specifies the time in the future when the lease on the 1558 Per-Printer Subscription Object will expire, i.e. the "printer-up-time" 1559 value at which the lease will expire. If the value is 0, the lease never 1560 expires. 1562 A Printer MUST support this attribute. 1564 When the Printer creates a Per-Job Subscription Object, this attribute 1565 MUST NOT be present - the Subscription Object lasts exactly as long as 1566 the associated Job object. 1568 When the Printer creates a Per-Printer Subscription Object, it populates 1569 this attribute with a value that is the sum of the values of the 1570 Printer's "printer-up-time" attribute and the Subscription Object's 1571 "notify-lease-duration" attribute with the following exception. If the 1572 value of the Subscription Object's "notify-lease-duration" attribute is 1573 0 (i.e., no expiration time), then the value of this attribute MUST be 1574 set to 0 (i.e., no expiration time). 1576 When the Printer powers up, it MUST set the value of this attribute in 1577 each persistent Subscription Object using the algorithm in the previous 1578 paragraph. 1580 When the "printer-up-time" equals the value of this attribute, the 1581 Printer MUST delete the Subscription Object. A client can extend a lease 1582 of a Per-Printer Subscription Object with the Renew-Subscription 1583 operation (see section 11.2.5). 1585 Note: In order to compute the number of seconds remaining in a lease for 1586 a Per-Printer Subscription Object, a client can subtract the 1587 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1588 from the Subscription's "notify-lease-expiration-time" attribute. 1590 5.4.4 notify-printer-up-time (integer(1:MAX)) 1592 This attribute is an alias for the Printer's "printer-up-time" attribute 1593 " (see [ipp-mod] section 4.4.29). 1595 A Printer MUST support this attribute. 1597 When the Printer creates a Per-Job Subscription Object, this attribute 1598 MUST NOT be present. When the Printer creates a Per-Printer Subscription 1599 Object, this attribute MUST be present. 1601 Note: this attribute exists in a Per-Printer Subscription Object so that 1602 a client using the Get-Subscription-Attributes or Get-Subscription 1603 operations can convert the Per-Printer Subscription's "notify-lease- 1604 expiration-time" attribute to wall clock time with one request. If the 1605 value of the "notify-lease-expiration-time" attribute is not 0 (i.e., no 1606 expiration time), then the difference between the "notify-lease- 1607 expiration-time" attribute and the "notify-printer-up-time" is the 1608 remaining number of seconds on the lease from the current time. 1610 5.4.5 notify-printer-uri (uri) 1612 This attribute identifies the Printer object that created this 1613 Subscription Object. 1615 A Printer MUST support this attribute. 1617 During a Subscription Creation Operation, the Printer MUST populate this 1618 attribute with the value of the "printer-uri" operation attribute in the 1619 request. From the Printer URI, the client can, for example, determine 1620 what security scheme was used. 1622 5.4.6 notify-job-id (integer(1:MAX)) 1624 This attribute specifies whether the containing Subscription Object is a 1625 Per-Job or Per-Printer Subscription Object, and for Per-Job Subscription 1626 Objects, it specifies the associated Job. 1628 A Printer MUST support this attribute. 1630 If this attribute is not present, the Subscription Object MUST be a Per- 1631 Printer Subscription. If this attribute is present, the Subscription 1632 Object MUST be a Per-Job Subscription Object and this attribute MUST 1633 identify the Job with which the Subscription Object is associated. 1635 Note: This attribute could be useful to a Notification Recipient that 1636 receives an Event Notification generated from a Per-Job Subscription 1637 Object and caused by a Printer Event. The Event Notification gives 1638 access to the Printer and the Subscription Object. The Event 1639 Notification gives access to the associated Job only via this 1640 attribute.. 1642 5.4.7 notify-subscriber-user-name (name(MAX)) 1644 This attribute contains the name of the user who performed the 1645 Subscription Creation Operation. 1647 A Printer MUST support this attribute. 1649 The Printer sets this attribute to the most authenticated printable name 1650 that it can obtain from the authentication service over which the 1651 Subscription Creation Operation was received. The Printer uses the same 1652 mechanism for determining the value of this attribute as it does for a 1653 Job's "job-originating-user-name" (see [ipp-mod] section 4.3.6). 1655 Note: To help with authentication, a Subscription Object may have 1656 additional private attributes about the user, e.g., a credential of a 1657 principal. Such private attributes are implementation-dependent and not 1658 defined in this document. 1660 6 Printer Description Attributes Related to Notification 1662 This section defines the Printer Description attributes that are related 1663 to Notification. Table 3 lists the Printer Description attributes, 1664 indicates the Printer support required for conformance, and whether or 1665 not the attribute is READ-ONLY (see section 3.1): 1667 Table 3 - Printer Description Attributes Associated with Notification 1669 Printer object attributes: REQUIRED READ-ONLY 1671 printer-state-change-time (integer(1:MAX)) No Yes 1673 printer-state-change-date-time (dateTime) No Yes 1675 6.1 printer-state-change-time (integer(1:MAX)) 1677 This attribute records the most recent time at which the 'printer-state- 1678 changed' Printer Event occurred whether or not any Subscription objects 1679 were listening for this event. This attribute helps a client or 1680 operator to determine how long the Printer has been in its current 1681 state. 1683 A Printer MAY support this attribute and if so, the attribute MUST be 1684 READ-ONLY. 1686 On power-up, the Printer MUST set the value of this attribute to be the 1687 value of its "printer-up-time" attribute, so that it always has a value. 1688 Whenever the 'printer-state-changed' Printer Event occurs, the Printer 1689 MUST set this attribute to the value of the Printer's "printer-up-time" 1690 attribute. 1692 6.2 printer-state-change-date-time (dateTime) 1694 This attribute records the most recent time at which the 'printer-state- 1695 changed' Printer Event occurred whether or not there were any 1696 Subscription Objects listening for this event. This attribute helps a 1697 client or operator to determine how long the Printer has been in its 1698 current state. 1700 A Printer MAY support this attribute and if so, the attribute MUST be 1701 READ-ONLY. 1703 On power-up, the Printer MUST set the value of this attribute to be the 1704 value of its "printer-current-time" attribute, so that it always has a 1705 value (see [ipp-mod] section 4.4.30 on "printer-current-time"). Whenever 1706 the 'printer-state-changed' Printer Event occurs, the Printer MUST set 1707 this attribute to the value of the Printer's "printer-current-time" 1708 attribute. 1710 7 New Values for Existing Printer Description Attributes 1712 This section contains those attributes for which additional values are 1713 added. 1715 7.1 operations-supported (1setOf type2 enum) 1717 The following "operation-id" values are added in order to support the 1718 new operations defined in this document: 1720 Table 4 - Operation-id assignments 1722 Value Operation Name 1724 0x0016 Create-Printer-Subscriptions 1726 0x0017 Create-Job-Subscriptions 1728 0x0018 Get-Subscription-Attributes 1729 Value Operation Name 1731 0x0019 Get-Subscriptions 1733 0x001A Renew-Subscription 1735 0x001B Cancel-Subscription 1737 8 Attributes Only in Event Notifications 1739 This section contains those attributes that exist only in Event 1740 Notifications and do not exist in any objects. 1742 8.1 notify-subscribed-event (type2 keyword) 1744 This attribute indicates the Subscribed Event that caused the Printer to 1745 send this Event Notification. This attribute exists only in Event 1746 Notifications. 1748 This attribute MUST contain one of the values of the "notify-events" 1749 attribute in the Subscription Object, i.e., one of the Subscribed Event 1750 values. Its value is the Subscribed Event that "matches" the Event that 1751 caused the Printer to send this Event Notification. This Subscribed 1752 Event value may be identical to the Event or the Event may be a sub- 1753 value of the Subscribed Event. For example, the 'job-completed' Event 1754 (which is a sub-event of the 'job-state-changed' event) would cause the 1755 Printer to send an Event Notification for either the 'job-completed' or 1756 'job-state-changed' Subscribed Events and to send the 'job-completed' or 1757 'job-state-changed' value for this attribute, respectively,. See 1758 section 5.3.2.2 for the "matching" rules of Subscribed Events and for 1759 additional examples. 1761 The Delivery Method Document specifies whether the Printer includes the 1762 value of this attribute in an Event Notification. 1764 8.2 notify-text (text(MAX)) 1766 This attribute contains a Human Consumable text message (see section 1767 9.2). This message describes the Event and is encoded as plain text, 1768 i.e., 'text/plain' with the charset specified by Subscription Object's 1769 "notify-charset" attribute. 1771 The Delivery Method Document specifies whether the Printer includes this 1772 attribute in an Event Notification. 1774 9 Event Notification Content 1776 This section defines the Event Notification content that the Printer 1777 sends when an Event occurs. 1779 When an Event occurs, the Printer MUST find each Subscription object 1780 whose "notify-events" attribute "matches" the Event. See section 5.3.2.2 1781 for details on "matching". For each matched Subscription Object, the 1782 Printer MUST create an Event Notification with the content and format 1783 that the Delivery Method Document specifies. The content contains the 1784 value of attributes specified by the Delivery Method Document. The 1785 Printer obtains the values immediately after the Event occurs. For 1786 example, if the "printer-state" attribute changes from 'idle' to 1787 'processing', the Event 'printer-state-changed' occurs and the Printer 1788 puts various attributes into the Event Notification, including "printer- 1789 up-time" and "printer-state" with the values that they have immediately 1790 after the Event occurs, i.e., the value of "printer-state" is 1791 'processing'. 1793 If two different Events occur simultaneously, or nearly so (e.g., 1794 "printer-up-time" has the same value for both), the Printer MUST create 1795 a separate Event Notification for each Event, even if the associated 1796 Subscription Object is the same for both Events. However, the Printer 1797 MAY combine these distinct Event Notifications into a single Compound 1798 Event Notification if the Delivery Method supports Compound Event 1799 Notifications For example, suppose that two nearly-simultaneously Events 1800 represent two successive 'printer-state-changed' Events, one from 'idle' 1801 to 'processing' and another from 'processing' to 'stopped'. These two 1802 Events have the same name but are different instances of the Event. Then 1803 the Printer MUST create a separate Event Notification for each Event and 1804 SHOULD accurately report the "printer-state" of the first Event as 1805 'processing' and the second Event as 'stopped'. 1807 If a Subscription Object contains more than one Subscribed Event, and 1808 several Events occur in quick succession each matching a different 1809 Subscribed Event in the Subscription Object, the Printer MUST NOT 1810 generate a single Event Notification from several of these Events, but 1811 MAY combine distinct Event Notifications into a single Compound Event 1812 Notification if the Delivery Method supports Compound Event 1813 Notifications. 1815 After the Printer has created the Event Notification, the Printer 1816 delivers it via either a: 1817 Push Delivery Method: The Printer sends the Event Notification 1818 shortly after an Event occurs. For some Push Delivery Methods, the 1819 Notification Recipient MUST send a response; for others it MUST NOT 1820 send a response. 1822 Pull Delivery Method: The Printer saves Event Notifications for 1823 some event-lease time and expects the Notification Recipient to 1824 request Event Notifications. The Printer returns the Event 1825 Notifications in a response to such a request. 1827 If an error that meets the following conditions occurs, the Printer MUST 1828 cancel the Subscription Object. 1830 a) the error occurs during the sending of an Event Notification 1831 generated from Subscription Object S AND 1833 b) the error would continue to occur every time the Printer sends an 1834 Event Notification generated from Subscription Object S in the 1835 future. 1837 >From example, if the address of the "notify-recipient-uri" of 1838 Subscription Object A references a non-existent target and the Printer 1839 determines that this fact, it MUST delete Subscription Object A. 1841 The next two sections describe the values that a Printer sends in the 1842 content of Machine Consumable and Human Consumable Event Notifications, 1843 respectively. 1845 The tables in the sub-sections of this section contain the following 1846 columns: 1848 a)Source Value: the name of the attribute that supplies the value 1849 for the Event Notification. Asterisks in this field refer to a 1850 note below the table. 1852 b)Sends: if the Printer supports the value (column 1) on the 1853 Source Object (column 3) the Delivery Method MUST specify: 1855 MUST: that the Printer MUST send the value. 1857 SHOULD: either that the Printer MUST send the value or that 1858 the value is incompatible with the Delivery Method. 1860 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 1861 or NEED NOT send the value. The Delivery Method specifies the 1862 level of conformance for the Printer. 1864 c)Source Object: the object from which the source value comes. If 1865 the object is "Event Notification", the Printer fabricates the 1866 value when it sends the Event Notification. See section 8. 1868 9.1 Content of Machine Consumable Event Notifications 1870 This section defines the attributes that a Delivery Method MUST mention 1871 in a Delivery Method Document when specifying the Machine Consumable 1872 Event Notification's contents. 1874 This document does not define the order of attributes in Event 1875 Notifications. However, Delivery Method Documents MAY define the order 1876 of some or all of the attributes. 1878 A Delivery Method Document MUST specify additional attributes (if any) 1879 that a Printer implementation sends in a Machine Consumable Event 1880 Notification. 1882 Notification Recipients MUST be able to accept Event Notifications 1883 containing attributes they do not recognize. What a Notification 1884 Recipient does with an unrecognized attribute is implementation- 1885 dependent. Notification Recipients MAY attempt to display unrecognized 1886 attributes anyway or MAY ignore them. 1888 The next three sections define the attributes in Event Notification 1889 Contents that are: 1891 a)for all Events 1893 b)for Job Events only 1894 c)for Printer Events only 1896 9.1.1 Event Notification Content Common to All Events 1898 This section lists the attributes that a Delivery Method Document MUST 1899 specify for all Events. 1901 Table 5 lists potential values in each Event Notification. 1903 Table 5 - Attributes in Event Notification Content 1905 Source Value Sends Source Object 1907 notify-subscription-id (integer(1:MAX)) MUST Subscription 1909 notify-printer-uri (uri) MUST Subscription 1911 notify-subscribed-event (type2 keyword) MUST Event 1912 Notification 1914 printer-up-time (integer(MIN:MAX)) MUST Printer 1916 printer-current-time (dateTime) * MUST Printer 1918 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 1920 notify-charset (charset) SHOULD Subscription 1922 notify-natural-language (naturalLanguage) SHOULD Subscription 1924 notify-user-data (octetString(63)) ** SHOULD Subscription 1926 notify-text (text) SHOULD Event 1927 Notification 1929 attributes from the "notify-attributes" MAY Printer 1930 attribute *** 1932 attributes from the "notify-attributes" MAY Job 1933 attribute *** 1935 attributes from the "notify-attributes" MAY Subscription 1936 Source Value Sends Source Object 1938 attribute *** 1940 *A Printer MUST send this value only if and only if it supports the 1941 Printer's "printer-current-time" attribute. 1943 ** If the Subscription Object does not contain a "notify-user-data" 1944 attribute and the Delivery Method document REQUIRES the Printer to send 1945 the "notify-user-data" source value in the Event Notification, the 1946 Printer MUST send an octet-string of length 0. 1948 *** The last three rows represent additional attributes that a client 1949 MAY request via the "notify-attributes" attribute. A Printer MAY 1950 support the "notify-attributes" attribute. The Delivery Method MUST say 1951 that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED NOT 1952 support the "notify-attributes" attribute and specific values of this 1953 attribute. The Delivery Method MAY say that support for the "notify- 1954 attributes" is conditioned on support of the attribute by the Printer or 1955 it MAY say that Printer MUST support the "notify-attributes" attribute 1956 if the Printer supports the Delivery Method. 1958 9.1.2 Additional Event Notification Content for Job Events 1960 This section lists the additional attributes that a Delivery Method 1961 Document MUST specify for Job Events. See Table 6. 1963 Table 6 - Additional Event Notification Content for Job Events 1965 Source Value Sends Source Object 1967 job-id (integer(1:MAX)) MUST Job 1969 job-state (type1 enum) MUST Job 1971 job-state-reasons (1setOf type2 keyword) MUST Job 1972 Source Value Sends Source Object 1974 job-impressions-completed (integer(0:MAX)) MUST Job 1975 * 1977 * The Printer MUST send the "job-impressions-completed" attribute in an 1978 Event Notification only for the combinations of Events and Subscribed 1979 Events shown in Table 7. 1981 Table 7 - Combinations of Events and Subscribed Events for "job- 1982 impressions-completed" 1984 Job Event Subscribed Job Event 1986 'job-progress' 'job-progress' 1988 'job-completed' 'job-completed' 1990 'job-completed' 'job-state-changed' 1992 9.1.3 Additional Event Notification Content for Printer Events 1994 This section lists the additional attributes that a Delivery Method 1995 Document MUST specify for Printer Events. See Table 8. 1997 Table 8 - Additional Event Notification Content for Printer Events 1999 Source Value Sends Source Object 2001 printer-state (type1 enum) MUST Printer 2003 printer-state-reasons (1setOf type2 MUST Printer 2004 Source Value Sends Source Object 2006 keyword) 2008 printer-is-accepting-jobs (boolean) MUST Printer 2010 9.2 Content of Human Consumable Event Notification 2012 This section defines the information that a Delivery Method MUST mention 2013 in a Delivery Method Document when specifying the Human Consumable Event 2014 Notifications contents or the value of the "notify-text" attribute. 2016 Such a Delivery Method MUST specify the following information and a 2017 Printer SHOULD send it: 2019 a)the Printer name (see Table 9) 2020 b)the time of the Event (see Table 11) 2021 c)for Printer Events only: 2022 i) the Event (see Table 10) and/or Printer state information 2023 (see Table 14) 2024 d)for Job Events only: 2025 i) the job identity (see Table 12) 2026 ii) the Event (see Table 10) and/or Job state information (see 2027 Table 13) 2029 The subsections of this section specify the attributes that a Printer 2030 MUST use to obtain this information. 2032 A Delivery Method Document MUST specify additional information (if any) 2033 that a Printer implementation sends in a Human Consumable Event 2034 Notification or in the "notify-text" attribute. 2036 A client MUST NOT request additional attributes via the "notify- 2037 attributes" attribute because this attribute works only for Machine 2038 Consumable Event Notifications. 2040 Notification Recipients MUST NOT expect to be able to parse the Human 2041 Consumable Event Notification contents or the value of the "notify-text" 2042 attribute. 2044 The next three sections define the attributes in Event Notification 2045 Contents that are: 2047 a)for all Events 2049 b)for Job Events only 2051 c)for Printer Events only 2053 9.2.1 Event Notification Content Common to All Events 2055 This section lists the source of the information that a Delivery Method 2056 MUST specify for all Events. 2058 There is a separate table for each piece of information. Each row in the 2059 table represents a source value for the information and the values are 2060 listed in order of preference, with the first one being the preferred 2061 one. An implementation SHOULD use the source value from the earliest row 2062 in each table. It MAY use the source value from another row instead, or 2063 it MAY combine the source values from several rows. An implementation is 2064 free to determine the best way to present this information. 2066 In all tables of this section, all rows contain a "MAY" in order to 2067 state that the Delivery Method specifies the conformance. 2069 Table 9 lists the source of the information for the Printer Name. The 2070 "printer-name" is more user-friendly unless the Notification Recipient 2071 is in a place where the Printer name is not meaningful. For example, an 2072 implementation could have the intelligence to send the value of the 2073 "printer-name" attribute to a Notification Recipient that can access the 2074 Printer via value of the "printer-name" attribute and otherwise send the 2075 value of the "notify-printer-uri" attribute. 2077 Table 9 - Printer Name in Event Notification Content 2079 Source Value Sends Source Object 2081 printer-name (name(127)) MAY Printer 2083 notify-printer-uri (uri) MAY Subscription 2085 Table 10 lists the source of the information for the Event name. A 2086 Printer MAY combine this information with state information described 2087 for Jobs in Table 13 or for Printers in Table 14. 2089 Table 10 - Event Name in Event Notification Content 2091 Source Value Sends Source Object 2093 notify-subscribed-event (type2 keyword) MAY Subscription 2095 Table 11 lists the source of the information for the time that the Event 2096 occurred. A Printer can send this value only if it supports the 2097 Printer's "printer-current-time" attribute. If a Printer does not 2098 support the 2099 "printer-current-time" attribute, it MUST NOT send the "printer-up-time" 2100 value instead, since it is not an allowed option for human consumable 2101 information. 2103 Table 11 - Event Time in Event Notification Content 2105 Source Value Sends Source Object 2107 printer-current-time (dateTime) MAY Printer 2109 9.2.2 Additional Event Notification Content for Job Events 2111 This section lists the source of the additional information that a 2112 Delivery Method MUST specify for Job Events. 2114 Table 12 lists the source of the information for the job name. The "job- 2115 name" is likely more meaningful to a user than "job-id". 2117 Table 12 - Job Name in Event Notification Content 2119 Source Value Sends Source Object 2121 job-name (name(MAX)) MAY Job 2123 job-id (integer(1:MAX)) MAY Job 2125 Table 13 lists the source of the information for the job state. If a 2126 Printer supports the "job-state-message" and "job-detailed-state- 2127 message" attributes, it SHOULD use those attributes for the job state 2128 information, otherwise, it should fabricate such information from the 2129 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2130 combine this information with Event information. 2132 Table 13 - Job State in Event Notification Content 2134 Source Value Sends Source Object 2136 job-state-message (text(MAX)) MAY Job 2138 job-detailed-status-messages (1setOf MAY Job 2139 text(MAX)) 2141 job-state (type1 enum) MAY Job 2143 job-state-reasons (1setOf type2 keyword) MAY Job 2145 9.2.3 Additional Event Notification Content for Printer Events 2147 This section lists the source of the additional information that a 2148 Delivery Method MUST specify for Printer Events. 2150 Table 14 lists the source of the information for the printer state. If a 2151 Printer supports the "printer-state-message", it SHOULD use that 2152 attribute for the job state information, otherwise it SHOULD fabricate 2153 such information from the "printer-state" and "printer-state-reasons". 2154 For some Events, a Printer MAY combine this information with Event 2155 information. 2157 Table 14 - Printer State in Event Notification Content 2159 Source Value Sends Source Object 2161 printer-state-message (text(MAX)) MAY Printer 2163 printer-state (type1 enum) MAY Printer 2165 printer-state-reasons (1setOf type2 MAY Printer 2166 keyword) 2168 printer-is-accepting-jobs (boolean) MAY Printer 2169 10 Delivery Methods 2171 A Delivery Method is the mechanism, i.e., protocol, by which the Printer 2172 delivers an Event Notification to a Notification Recipient. There are 2173 several potential Delivery Methods for Event Notifications, 2174 standardized, as well as proprietary. This document does not define any 2175 of these delivery mechanisms. Each Delivery Method MUST be defined in a 2176 Delivery Method Document that is separate from this document. New 2177 Delivery Methods will be created as needed using an extension to the 2178 registration procedures defined in [ipp-mod]. Such documents are 2179 registered with IANA (see section 13). 2181 The following sorts of Delivery Methods are expected: 2183 - The Notification Recipient polls for Event Notifications at 2184 intervals directed by the Printer 2186 - The Printer sends Event Notifications to the Notification Recipient 2187 using http as the transport. 2189 - The Printer sends an email message. 2191 This section specifies how to define a Delivery Method Document and what 2192 to put in such a document. 2194 A Delivery Method Document MUST contain an exact copy of the following 2195 paragraph, caption and table. In addition, column 2 of the table in the 2196 Delivery Method Document MUST contain answers to questions in column 1 2197 for the Delivery Method. Also, the Delivery Method document MUST contain 2198 a reference to this document and call that reference [ipp-ntfy] because 2199 the table contains an [ipp-ntfy] reference. 2201 If a Printer supports this Delivery Method, the following are its 2202 characteristics. 2204 Table 15 - Information about the Delivery Method 2206 Document Method Conformance Delivery Method Realization 2207 Requirement 2209 1.What is the URL scheme name 2210 for the Delivery Method? 2212 2.Is the Delivery Method 2213 REQUIRED, RECOMMENDED, or 2214 OPTIONAL for an IPP Printer to 2215 support? 2217 3.What transport and delivery 2218 protocols does the Printer use 2219 to deliver the Event 2220 Notification Content, i.e., 2221 what is the entire network 2222 stack? 2224 4.Can several Event 2225 Notifications be combined into 2226 a Compound Event Notification? 2228 5.Is the Delivery Method 2229 initiated by the Notification 2230 Recipient (pull), or by the 2231 Printer (push)? 2233 6.Is the Event Notification 2234 content Machine Consumable or 2235 Human Consumable? 2237 7.What section in this document 2238 answers the following 2239 question? For a Machine 2240 Consumable Event Notification, 2241 what is the representation and 2242 encoding of values defined in 2243 section 9.1 of [ipp-ntfy] and 2244 the conformance requirements 2245 thereof? For a Human 2246 Consumable Event Notification, 2247 what is the representation and 2248 encoding of pieces of 2249 information defined in section 2250 9.2 of [ipp-ntfy] and the 2251 conformance requirements 2252 thereof? 2254 8.What are the latency and 2255 reliability of the transport 2256 and delivery protocol? 2258 9.What are the security aspects 2259 of the transport and delivery 2260 protocol, e.g., how it is 2261 handled in firewalls? 2263 10. What are the content length 2264 restrictions? 2266 11. What are the additional 2267 values or pieces of 2268 information that a Printer 2269 sends in an Event Notification 2270 content and the conformance 2271 requirements thereof? 2273 12. What are the additional 2274 Subscription Template and/or 2275 Subscription Description 2276 attributes and the conformance 2277 requirements thereof? 2279 13. What are the additional 2280 Printer Description attributes 2281 and the conformance 2282 requirements thereof? 2284 11 Operations for Notification 2286 This section defines all of the operations for Notification. Section 7.1 2287 assigns the "operation-id" for each operation. The following two sub- 2288 sections define Subscription Creation Operations, and other operations. 2290 11.1Subscription Creation Operations 2292 This section defines the Subscription Creation Operations. The first 2293 section on Create-Job-Subscriptions gives most of the information. The 2294 other Subscription Creation Operations refer to the section on Create- 2295 Job-Subscriptions, even though the Create-Job-Subscriptions operation is 2296 the only OPTIONAL operation in this document (see section 12). 2298 A Printer MUST support Create-Printer-Subscriptions and the Subscription 2299 Template Attributes Group in Job Creation operations. It MAY support 2300 Create-Job-Subscriptions operations. 2302 11.1.1Create-Job-Subscriptions Operation 2304 The operation creates one or more Per-Job Subscription Objects. The 2305 client supplies one or more Subscription Template Attributes Groups each 2306 containing one or more of Subscription Template Attributes (defined in 2307 section 5.3). 2309 Except for errors, the Printer MUST create exactly one Per-Job 2310 Subscription Object from each Subscription Template Attributes Group in 2311 the request, even if the newly created Subscription Object would have 2312 identical behavior to some existing Subscription Object. The Printer 2313 MUST associate each newly created Per-Job Subscription Object with the 2314 target Job, which is specified by the "notify-job-id" operation 2315 attribute. 2317 The Printer MUST accept the request in any of the target job's 'not- 2318 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2319 'processing-stopped'. The Printer MUST NOT change the job's "job-state" 2320 attribute because of this operation. If the target job is in any of the 2321 'completed' states, i.e., 'completed', 'canceled', or 'aborted, then the 2322 Printer MUST reject the request and return the 'client-error-not- 2323 possible' status code; the response MUST NOT contain any Subscription 2324 Attribute Groups. 2326 Access Rights: To create Per-Job Subscription Objects, the 2327 authenticated user (see [IPP-MOD] section 8.3) performing this operation 2328 MUST either be the job owner or have Operator or Administrator access 2329 rights for this Printer (see [IPP-MOD] sections 1 and 8.5). Otherwise 2330 the Printer MUST reject the operation and return: the 'client-error- 2331 forbidden', 'client-error-not-authenticated', or 'client-error-not- 2332 authorized' status code as appropriate. 2334 11.1.1.1 Create-Job-Subscriptions Request 2336 The following groups of attributes are part of the Create-Job- 2337 Subscriptions Request: 2339 Group 1: Operation Attributes 2341 Natural Language and Character Set: 2342 The "attributes-charset" and "attributes-natural-language" 2343 attributes as described in [ipp-mod] section 3.1.4.1. 2345 Target: 2346 The "printer-uri" attribute which defines the target for this 2347 operation as described in [ipp-mod] section 3.1.5. 2349 Requesting User Name: 2350 The "requesting-user-name" attribute SHOULD be supplied by the 2351 client as described in [ipp-mod] section 8.3. 2353 notify-job-id (integer(1:MAX)): 2354 The client MUST supply this attribute and it MUST specify the Job 2355 object to associate the Per-Job Subscription with. The value of 2356 "notify-job-id" MUST be the value of the "job-id" of the associated 2357 Job object. If the client does not supply this attribute, the 2358 Printer MUST reject this request with a 'client-error-bad-request' 2359 status code. 2361 Group 2-N: Subscription Template Attributes 2363 For each occurrence of this group: 2365 The client MUST supply one or more Subscription Template 2366 Attributes in any order. See section 5.3 for a description of 2367 each such attribute. See section 5.2 for details on processing 2368 these attributes. 2370 11.1.1.2 Create-Job-Subscriptions Response 2372 The Printer MUST return to the client the following sets of attributes 2373 as part of a Create-Job-Subscriptions response: 2375 Group 1: Operation Attributes 2377 Status Message: 2378 As defined in [ipp-mod]. 2380 In this group, the Printer can return any status codes defined in 2381 [ipp-mod] and section 16. The following is a description of the 2382 important status codes: 2384 successful-ok: the Printer created all Subscription Objects 2385 requested. 2386 successful-ok-ignored-subscriptions: the Printer created some 2387 Subscription Objects requested but some failed. The 2388 Subscription Attributes Groups with a "notify-status-code" 2389 attribute are the ones that failed. 2390 client-error-ignored-all-subscriptions: the Printer created no 2391 Subscription Objects requested and all failed. The 2392 Subscription Attributes Groups with a "notify-status-code" 2393 attribute are the ones that failed 2394 client-error-not-possible: For this operation and other Per-Job 2395 Subscription operations, this error can occur because the 2396 specified Job has already completed. 2398 Natural Language and Character Set: 2399 The "attributes-charset" and "attributes-natural-language" 2400 attributes as described in [ipp-mod] section 3.1.4.2. 2402 Group 2: Unsupported Attributes 2404 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2405 Attributes. This group does not contain any unsupported 2406 Subscription Template Attributes; they are returned in the 2407 Subscription Attributes Group (see below). 2409 Group 3-N: Subscription Attributes 2411 These groups MUST be returned if and only if the "status-code" 2412 parameter returned in Group 1 has the values: 'successful-ok', 2413 'successful-ok-ignored-subscriptions', or 'client-error-ignored- 2414 all-subscriptions'. 2416 See section 5.2 for details on the contents of each occurrence of 2417 this group. 2419 11.1.2Create-Printer-Subscriptions operation 2421 The operation is identical to Create-Job-Subscriptions with exceptions 2422 noted in this section. 2424 The operation creates Per-Printer Subscription Objects instead of Per- 2425 Job Subscription Objects, and associates each newly created Per-Printer 2426 Subscription Object with the Printer specified by the operation target 2427 rather than with a specific Job. 2429 The Printer MUST accept the request in any of its states, i.e., 'idle', 2430 'processing', or 'stopped'. The Printer MUST NOT change its "printer- 2431 state" attribute because of this operation. 2433 Access Rights: To create Per-Printer Subscription Objects, the 2434 authenticated user (see [IPP-MOD] section 8.3) performing this operation 2435 MUST have Operator or Administrator access rights for this Printer (see 2436 [IPP-MOD] sections 1 and 8.5). Otherwise, the Printer MUST reject the 2437 operation and return: the 'client-error-forbidden', 'client-error-not- 2438 authenticated', or 'client-error-not-authorized' status code as 2439 appropriate. 2441 11.1.2.1 Create-Printer-Subscriptions Request 2443 The groups are identical to the Create-Job-Subscriptions (see section 2444 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2445 the "notify-job-id" attribute. If the client does supply the "notify- 2446 job-id" attribute, then the Printer MUST treat it as any other 2447 unsupported Operation attribute and MUST return it in the Unsupported 2448 Attributes group. 2450 11.1.2.2 Create-Printer-Subscriptions Response 2452 The groups are identical to the Create-Job-Subscriptions (see section 2453 11.1.1.2). 2455 11.1.3Job Creation Operation - Extensions for Notification 2457 This document extends the Job Creation operations to create Subscription 2458 Objects as a part of the operation. 2460 The operation is identical to Create-Job-Subscriptions with exceptions 2461 noted in this section. 2463 Unlike the Create-Job-Subscriptions operation, this operation associates 2464 the newly created Subscription Objects with the Job object created by 2465 this operation. The operation succeeds if and only if the Job creation 2466 succeeds. If the Printer does not create some or all of the requested 2467 Subscription Objects, the Printer MUST return a 'successful-ok-ignored- 2468 subscriptions' status-code instead of a 'successful-ok' status-code, but 2469 the Printer MUST NOT reject the operation because of a failure to create 2470 Subscription Objects. 2472 If the operation includes a Job Template group, the client MUST supply 2473 it after the Operation Attributes group and before the first 2474 Subscription Template Attributes Group. 2476 If a Printer does not support this Notification specification, then it 2477 MUST treat the Subscription Attributes Group like an unknown group and 2478 ignore it (see [ipp-mod] section 5.2.2). Because the Printer ignores 2479 the Subscription Attributes Group, it doesn't return them in the 2480 response either, thus indicating to the client that the Printer doesn't 2481 support Notification. 2483 Access Rights: To create Per-Job Subscription Objects, the 2484 authenticated user (see [IPP-MOD] section 8.3) performing this operation 2485 MUST either have permission to create Jobs on the Printer. Otherwise 2486 the Printer MUST reject the operation and return: the 'client-error- 2487 forbidden', 'client-error-not-authenticated', or 'client-error-not- 2488 authorized' status code as appropriate. 2490 11.1.3.1 Job Creation Request 2492 The groups for this operation are sufficiently different from the 2493 Create-Job-Subscriptions operation that they are all presented here. The 2494 following groups of attributes are supplied as part of a Job Creation 2495 Request: 2497 Group 1: Operation Attributes 2499 Same as defined in [ipp-mod] for Print-Job, Print-URI, and Create- 2500 Job requests. 2502 Group 2: Job Template Attributes 2504 The client OPTIONALLY supplies a set of Job Template attributes as 2505 defined in [ipp-mod] section 4.2. 2507 Group 3 to N: Subscription Template Attributes 2509 The same as Group 2-N in Create-Job-Subscriptions. See section 2510 11.1.1.1. 2512 Group N+1: Document Content (Print-Job only) 2514 The client MUST supply the document data to be processed. 2516 11.1.3.2 Job Creation Response 2518 The Printer MUST return to the client the following sets of attributes 2519 as part of a Print-Job, Print-URI, and Create-Job Response: 2521 Group 1: Operation Attributes 2522 Status Message: 2524 As defined in [ipp-mod] for Print-Job, Print-URI, and Create-Job 2525 requests. 2527 In this group, the Printer can return any status codes defined in 2528 [ipp-mod] and section 16. The following is a description of the 2529 important status codes: 2531 successful-ok: the Printer created the Job and all Subscription 2532 Objects requested. 2533 successful-ok-ignored-subscriptions: the Printer created the Job 2534 and not all of the Subscription Objects requested. This 2535 status-code hides 'successful-ok-xxx' status-codes that could 2536 reveal problems in Job creation. The Printer MUST not return 2537 the 'client-error-ignored-all-subscriptions' status code for 2538 Job Creation operations because the Printer returns an error 2539 status-code only when it fails to create a Job. 2541 Natural Language and Character Set: 2542 The "attributes-charset" and "attributes-natural-language" 2543 attributes as described in [ipp-mod] section 3.1.4.2. 2545 Group 2: Unsupported Attributes 2547 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2548 Attributes. This group does not contain any unsupported 2549 Subscription Template Attributes; they are returned in the 2550 Subscription Attributes Group (see below). 2552 Group 3: Job Object Attributes 2554 As defined in [ipp-mod] for Print-Job, Print-URI, and Create-Job 2555 requests. 2557 Group 4 to N: Subscription Attributes 2559 These groups MUST be returned if and only if the client supplied 2560 Subscription Template Attributes and the operation was accepted. 2562 See section 5.2 for details on the contents of each occurrence of 2563 this group. 2565 11.2Other Operations 2567 This section defines other operations on Subscription objects. 2569 11.2.1Validate-Job Operation - Extensions for Notification 2571 A client can test whether one or more Subscription Objects could be 2572 created using the Validate-Job operation. The client supplies one or 2573 more Subscription Template Attributes Groups (defined in section 5.3), 2574 just as in a Job Creation request. 2576 A Printer MUST support this extension to this operation. 2578 The Printer MUST accept requests that are identical to the Job Creation 2579 request defined in section 11.1.3.1, except that the request MUST not 2580 contain document data. 2582 The Printer MUST return the same groups and attributes as the Print-Job 2583 operation (section 11.1.3.1) with the following exceptions. The Printer 2584 MUST NOT return a Job Object Attributes Group because no Job is created. 2585 The Printer MUST NOT return the "notify-subscription-id" attribute in 2586 any Subscription Attribute Group because no Subscription Object is 2587 created. 2589 If the Printer would succeed in creating a Subscription Object, the 2590 corresponding Subscription Attributes Group either has no 'status-code' 2591 attribute or a 'status-code' attribute with a value of 'successful-ok- 2592 too-many-events' or 'successful-ok-ignored-or-substituted-attributes' 2593 (see sections 5.2 and 17). The status-codes have the same meaning as in 2594 Job Creation except the results state what "would happen". 2596 The Printer MUST validate Subscription Template Attributes Groups in the 2597 same manner as the Job Creation operations. 2599 11.2.2Get-Printer-Attributes - Extensions for Notification 2601 This operation is extended so that it returns Printer attributes defined 2602 in this document. 2604 A Printer MUST support this extension to this operation. 2606 In addition to the requirements of [ipp-mod] section 3.2.5, a Printer 2607 MUST support the following additional values for the "requested- 2608 attributes" Operation attribute in this operation and return such 2609 attributes in the Printer Object Attributes group of its response. 2611 1. Subscription Template Attributes: Each supported attribute in 2612 column 2 of Table 1. 2614 2. New Printer Description Attributes: Each supported attribute in 2615 section 6. 2617 3. New Group Name: The 'subscription-template' group name, which names 2618 all supported Subscription Template Attribute in column 2 of Table 2619 1. This group name is also used in the Get-Subscription-Attributes 2620 and Get-Subscriptions operation with an analogous meaning. 2622 4. Extended Group Name: The 'all' group name, which names all Printer 2623 attributes according to [ipp-mod] section 3.2.5. In this extension 2624 'all' names all attributes specified in [ipp-mod] plus those named 2625 in items 1 and 2 of this list. 2627 11.2.3Get-Subscription-Attributes operation 2629 This operation allows a client to request the values of the attributes 2630 of a Subscription Object. 2632 A Printer MUST support this operation. 2634 This operation is almost identical to the Get-Job-Attributes operation 2635 (see [ipp-mod] section 3.3.4). The only differences are that the 2636 operation is directed at a Subscription Object rather than a Job object, 2637 and the returned attribute group contains Subscription Object attributes 2638 rather than Job object attributes. 2640 11.2.3.1 Get-Subscription-Attributes Request 2642 The following groups of attributes are part of the Get-Subscription- 2643 Attributes request: 2645 Group 1: Operation Attributes 2647 Natural Language and Character Set: 2648 The "attributes-charset" and "attributes-natural-language" 2649 attributes as described in section [ipp-mod] 3.1.4.1. 2651 Target: 2652 The "printer-uri" attribute which defines the target for this 2653 operation as described in [ipp-mod] section 3.1.5. 2655 "notify-subscription-id" (integer (1:MAX)): 2656 The client MUST supply this attribute. The Printer MUST support 2657 this attribute. This attribute specifies the Subscription Object 2658 from which the client is requesting attributes. If the client omits 2659 this attribute, the Printer MUST reject this request with the 2660 'client-error-bad-request' status code. 2662 Requesting User Name: 2663 The "requesting-user-name" attribute SHOULD be supplied by the 2664 client as described in [ipp-mod] section 8.3. 2666 "requested-attributes" (1setOf keyword): 2667 The client OPTIONALLY supplies this attribute. The Printer MUST 2668 support this attribute. This attribute specifies the attributes of 2669 the specified Subscription Object that the Printer MUST return in 2670 the response. Each value of this attribute is either an attribute 2671 name (defined in sections 5.3 and 5.4) or an attribute group name. 2672 The attribute group names are: 2674 - 'subscription-template': all attributes that are both defined 2675 in section 5.3 and present on the specified Subscription 2676 Object (column 1 of Table 1). 2677 - 'subscription-description': all attributes that are both 2678 defined in section 5.4 and present on the specified 2679 Subscription Object (Table 2). 2680 - 'all': all attributes that are present on the specified 2681 Subscription Object. 2683 A Printer MUST support all these group names. 2685 If the client omits this attribute, the Printer MUST respond as if 2686 this attribute had been supplied with a value of 'all'. 2688 11.2.3.2 Get-Subscription-Attributes Response 2690 The Printer returns the following sets of attributes as part of the Get- 2691 Subscription-Attributes Response: 2693 Group 1: Operation Attributes 2695 Status Message: 2696 Same as [ipp-mod]. 2698 Natural Language and Character Set: 2699 The "attributes-charset" and "attributes-natural-language" 2700 attributes as described in [ipp-mod] section 3.1.4.2. The 2701 "attributes-natural-language" MAY be the natural language of the 2702 Subscription Object, rather than the one requested. 2704 Group 2: Unsupported Attributes 2706 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2707 Attributes. 2709 The response NEED NOT contain the "requested-attributes" operation 2710 attribute with any supplied values (attribute keywords) that were 2711 requested by the client but are not supported by the Printer. If 2712 the Printer does return unsupported attributes referenced in the 2713 "requested-attributes" operation attribute and that attribute 2714 included group names, such as 'all', the unsupported attributes 2715 MUST NOT include attributes described in the standard but not 2716 supported by the implementation. 2718 Group 3: Subscription Attributes 2720 This group contains a set of attributes with their current values. 2721 Each attribute in this group: 2723 a)MUST be specified by the "requested-attributes" attribute in the 2724 request, AND 2726 b)MUST be present on the specified Subscription Object AND 2728 c)MUST NOT be restricted by the security policy in force. For 2729 example, a Printer MAY prohibit a client who is not the creator 2730 of a Subscription Object from seeing some or all of its 2731 attributes. See [ipp-mod] section 8. 2733 The Printer can return the attributes of the Subscription Object in 2734 any order. The client MUST accept the attributes in any order. 2736 11.2.4Get-Subscriptions operation 2738 This operation allows a client to retrieve the values of attributes of 2739 all Subscription Objects belonging to a Job or Printer. 2741 A Printer MUST supported this operation. 2743 This operation is similar to the Get-Subscription-Attributes operation, 2744 except that this Get-Subscriptions operation returns attributes from 2745 possibly more than one object. 2747 This operation is similar to the Get-Jobs operation (see [ipp-mod] 2748 section 3.2.6), except that the operation returns Subscription Objects 2749 rather than Job objects. 2751 11.2.4.1 Get-Subscriptions Request 2753 The following groups of attributes are part of the Get-Subscriptions 2754 request: 2756 Group 1: Operation Attributes 2758 Natural Language and Character Set: 2759 The "attributes-charset" and "attributes-natural-language" 2760 attributes as described in [ipp-mod] section 3.1.4.1. 2762 Target: 2763 The "printer-uri" attribute which defines the target for this 2764 operation as described in [ipp-mod] section 3.1.5. 2766 Requesting User Name: 2767 The "requesting-user-name" attribute SHOULD be supplied by the 2768 client as described in [ipp-mod] section 8.3. 2770 "notify-job-id" (integer(1:MAX)): 2771 If the client specifies this attribute, the Printer returns the 2772 specified attributes of all Per-Job Subscription Objects associated 2773 with the Job whose "job-id" attribute value equals the value of 2774 this attribute. If the client does not specify this attribute, the 2775 Printer returns the specified attributes of all Per-Printer 2776 Subscription Objects. Note: there is no way to get all Per-Job 2777 Subscriptions. 2779 "limit" (integer(1:MAX)): 2780 The client OPTIONALLY supplies this attribute. The Printer MUST 2781 support this attribute. It is an integer value that determines the 2782 maximum number of Subscription Objects that a client will receive 2783 from the Printer even if the "my-subscriptions" attribute 2784 constrains which Subscription Objects are returned. The limit is a 2785 "stateless limit" in that if the value supplied by the client is 2786 'N', then only the first 'N' Subscription Objects are returned in 2787 the Get-Subscriptions Response. There is no mechanism to allow for 2788 the next 'M' Subscription Objects after the first 'N' Subscription 2789 Objects. If the client does not supply this attribute, the Printer 2790 responds with all applicable Subscription Objects. 2792 "requested-attributes" (1setOf type2 keyword): 2793 The client OPTIONALLY supplies this attribute. The Printer MUST 2794 support this attribute. This attribute specifies the attributes of 2795 the specified Subscription Objects that the Printer MUST return in 2796 the response. Each value of this attribute is either an attribute 2797 name (defined in sections 5.3 and 5.4) or an attribute group name 2798 (defined in section 11.2.3.1). If the client omits this attribute, 2799 the Printer MUST respond as if the client had supplied this 2800 attribute with the one value: 'notify-subscription-id'. 2802 "my-subscriptions" (boolean): 2803 The client OPTIONALLY supplies this attribute. The Printer MUST 2804 support this attribute. If the value is 'false', the Printer MUST 2805 consider the Subscription Objects from all users as candidates. If 2806 the value is 'true', the Printer MUST return the Subscription 2807 Objects created by the requesting user of this request. If the 2808 client does not supply this attribute, the Printer MUST respond as 2809 if the client had supplied the attribute with a value of 'false'. 2810 The means for authenticating the requesting user and matching the 2811 Subscription Objects is similar to that for Jobs which is described 2812 in [ipp-mod] section 8. 2814 11.2.4.2 Get-Subscriptions Response 2816 The Printer returns the following sets of attributes as part of the Get- 2817 Subscriptions Response: 2819 Group 1: Operation Attributes 2821 Status Message: 2822 Same as [ipp-mod]. 2824 Natural Language and Character Set: 2825 The "attributes-charset" and "attributes-natural-language" 2826 attributes as described in [ipp-mod] section 3.1.4.2. 2828 Group 2: Unsupported Attributes 2830 Same as for Get-Subscription-Attributes. 2832 Groups 3 to N: Subscription Attributes 2834 The Printer responds with one Subscription Attributes Group for 2835 each requested Subscription Object (see the "notify-job-id" 2836 attribute in the Operation Attributes Group of this operation). 2838 The Printer returns Subscription Objects in any order. 2840 If the "limit" attribute is present in the Operation Attributes 2841 group of the request, the number of Subscription Attributes Groups 2842 in the response MUST NOT exceed the value of the "limit" attribute. 2844 It there are no Subscription Objects associated with the specified 2845 Job or Printer, the Printer MUST return zero Subscription 2846 Attributes Groups and it MUST NOT treat this case as an error, 2847 i.e., the status-code MUST be 'successful-ok' unless something else 2848 causes the status code to have some other value. 2850 See the Group 3 response (Subscription Attributes Group) of the 2851 Get-Subscription-Attributes operation (section 11.2.3.2) for the 2852 attributes that a Printer returns in this group. 2854 11.2.5Renew-Subscription operation 2856 This operation allows a client to request the Printer to extend the 2857 lease on a Per-Printer Subscription Object. 2859 The Printer MUST support this operation. 2861 The Printer MUST accept this request for a Per-Printer Subscription 2862 Object in any of the target Printer's states, i.e., 'idle', 2863 'processing', or 'stopped', but MUST NOT change the Printer's "printer- 2864 state" attribute. 2866 The Printer MUST reject this request for a Per-Job Subscription Object 2867 because it has no lease (see section 5.4.3). The status code returned 2868 MUST be 'client-error-not-possible'. 2870 Access Rights: The authenticated user (see [IPP-MOD] section 8.3) 2871 performing this operation MUST either be the owner of the Per-Printer 2872 Subscription Object or have Operator or Administrator access rights for 2873 the Printer (see [IPP-MOD] sections 1 and 8.5). Otherwise, the Printer 2874 MUST reject the operation and return: the 'client-error-forbidden', 2875 'client-error-not-authenticated', or 'client-error-not-authorized' 2876 status code as appropriate. 2878 11.2.5.1 Renew-Subscription Request 2880 The following groups of attributes are part of the Renew-Subscription 2881 Request: 2883 Group 1: Operation Attributes 2885 Natural Language and Character Set: 2886 The "attributes-charset" and "attributes-natural-language" 2887 attributes as described in [ipp-mod] section 3.1.4.1. 2889 Target: 2890 The "printer-uri" attribute which defines the target for this 2891 operation as described in [ipp-mod] section 3.1.5. 2893 "notify-subscription-id" (integer (1:MAX)): 2894 The client MUST supply this attribute. The Printer MUST support 2895 this attribute. This attribute specifies the Per-Printer 2896 Subscription Object whose lease the Printer MUST renew. If the 2897 client omits this attribute, the Printer MUST reject this request 2898 with the 'client-error-bad-request' status code. 2900 Requesting User Name: 2901 The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied 2902 by the client as described in [ipp-mod] section 8.3. 2904 Group 2: Subscription Template Attributes 2906 "notify-lease-duration" (integer(0:MAX)): 2907 The client MAY supply this attribute. It indicates the number of 2908 seconds to renew the lease for the specified Subscription Object. 2909 A value of 0 requests an infinite lease (which MAY require Operator 2910 access rights). If the client omits this attribute, the Printer 2911 MUST use the value of the Printer's "notify-lease-duration-default" 2912 attribute. See section 5.3.7 for more details. 2914 11.2.5.2 Renew-Subscription Response 2916 The Printer returns the following sets of attributes as part of the 2917 Renew-Subscription Response: 2919 Group 1: Operation Attributes 2921 Status Message: 2922 Same as [ipp-mod]. 2924 The following are some of the status codes returned: 2926 successful-ok: The operation successfully renewed the lease on the 2927 Subscription Object for the requested duration.. 2928 successful-ok-ignored-or-substituted-attributes: The operation 2929 successfully renewed the lease on the Subscription Object for 2930 some duration other than the amount requested. 2931 client-error-not-possible: The operation failed because the 2932 "notify-subscription-id" Operation attribute identified a Per- 2933 Job Subscription Object. 2934 client-error-not-found: The operation failed because the "notify- 2935 subscription-id" Operation attribute identified a non-existent 2936 Subscription Object. 2938 Natural Language and Character Set: 2939 The "attributes-charset" and "attributes-natural-language" 2940 attributes as described in [ipp-mod] section 3.1.4.2. The 2941 "attributes-natural-language" MAY be the natural language of the 2942 Subscription Object, rather than the one requested. 2944 Group 2: Unsupported Attributes 2946 See [ipp-mod] section 3.1.7 for details on returning Unsupported 2947 Attributes. 2949 Group 3: Subscription Attributes 2951 The Printer MUST return the following Subscription Attribute: 2953 "notify-lease-duration" (integer(0:MAX)): 2954 The value of this attribute MUST be the number of seconds that the 2955 Printer has granted for the lease of the Subscription Object (see 2956 section 5.3.7 for details, such as the value of this attribute when 2957 the Printer doesn't support the requested value). 2959 11.2.6Cancel-Subscription operation 2961 This operation allows a client to delete a Subscription Object and stop 2962 the Printer from sending more Event Notifications. Once performed, 2963 there is no way to reference the Subscription Object. 2965 A Printer MUST supported this operation. 2967 The Printer MUST accept this request in any of the target Printer's 2968 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 2969 the Printer's "printer-state" attribute. 2971 If the specified Subscription Object is a Per-Job Subscription Object, 2972 the Printer MUST accept this request in any of the target Job's states, 2973 but MUST NOT change the Job's "job-state" attribute or affect the Job. 2975 Access Rights: The authenticated user (see [IPP-MOD] section 8.3) 2976 performing this operation MUST either be the owner of the Subscription 2977 Object or have Operator or Administrator access rights for the Printer 2978 (see [IPP-MOD] sections 1 and 8.5). Otherwise, the Printer MUST reject 2979 the operation and return: the 'client-error-forbidden', 'client-error- 2980 not-authenticated', or 'client-error-not-authorized' status code as 2981 appropriate. 2983 Note: There is no way to change any attributes on a Subscription 2984 Object, except the "notify-lease-duration" attribute (using the Renew- 2985 Subscription operation). In order to change other attributes, a client 2986 performs a Subscription Creation Operation and Cancel-Subscription 2987 operation on the old Subscription Object. If the client wants to avoid 2988 missing Event Notifications, it performs the Subscription Creation 2989 Operation first. If this order would create too many Subscription 2990 Objects on the Printer, the client reverses the order. 2992 11.2.6.1 Cancel-Subscription Request 2994 The following groups of attributes are part of the Cancel-Subscription 2995 Request: 2997 Group 1: Operation Attributes 2999 Natural Language and Character Set: 3000 The "attributes-charset" and "attributes-natural-language" 3001 attributes as described in [ipp-mod] section 3.1.4.1. 3003 Target: 3004 The "printer-uri" attribute which defines the target for this 3005 operation as described in [ipp-mod] section 3.1.5. 3007 "notify-subscription-id" (integer (1:MAX)): 3008 The client MUST supply this attribute. The Printer MUST support 3009 this attribute. This attribute specifies the Subscription Object 3010 that the Printer MUST cancel. If the client omits this attribute, 3011 the Printer MUST reject this request with the 'client-error-bad- 3012 request' status code. 3014 Requesting User Name: 3015 The "requesting-user-name" attribute SHOULD be supplied by the 3016 client as described in [ipp-mod] section 8.3. 3018 11.2.6.2 Cancel-Subscription Response 3020 The Printer returns the following sets of attributes as part of the 3021 Cancel-Subscription Response: 3023 Group 1: Operation Attributes 3025 Status Message: 3026 Same as [ipp-mod]. 3028 The following are some of the status codes returned: 3030 successful-ok: The operation successfully canceled (deleted) the 3031 Subscription Object.. 3032 client-error-not-found: The operation failed because the "notify- 3033 subscription-id" Operation attribute identified a non-existent 3034 Subscription Object. 3036 Natural Language and Character Set: 3037 The "attributes-charset" and "attributes-natural-language" 3038 attributes as described in [ipp-mod] section 3.1.4.2. The 3039 "attributes-natural-language" MAY be the natural language of the 3040 Subscription Object, rather than the one requested. 3042 Group 2: Unsupported Attributes 3044 See [ipp-mod] section 3.1.7 for details on returning Unsupported 3045 Attributes. 3047 12 Conformance Requirements 3049 It is OPTIONAL to implement this Event Notification specification. 3051 If this Event Notification specification is implemented, Printers MUST: 3053 1.meet the Conformance Requirements detailed in section 5 of [ipp-mod]. 3055 2.support the Subscription Template Attributes Group in requests and 3056 the Subscription Attributes Group in responses. 3058 3.support all of the following attributes: 3060 a.REQUIRED Subscription Object attributes in section 5. 3062 b.REQUIRED Printer Description object attributes in section 6. 3064 c.REQUIRED attributes in Event Notification content in section 8. 3066 4.send Event Notifications that conform to the requirements of the 3067 Delivery Method Document for each supported Delivery Method (the 3068 conformance requirements for Delivery Method Documents is specified 3069 in section 10). 3071 5.support all operations as described in Table 16: 3073 Table 16 - Conformance Requirements for Operations 3075 Operation Conformance requirements 3077 Create-Printer-Subscriptions REQUIRED 3078 (section 11.1.2) 3080 Create-Job-Subscriptions (section OPTIONAL 3081 11.1.1) 3083 Get-Subscription-Attributes (section REQUIRED 3084 11.2.2) 3086 Get-Subscriptions (section 11.2.4) REQUIRED 3088 Renew-Subscription (section 11.2.5) REQUIRED 3090 Cancel-Subscription (section 11.2.6) REQUIRED 3092 13 IANA Considerations 3094 This section describes the procedures for registering Event Notification 3095 Delivery Method proposals with IANA to be used with this document. Such 3096 Delivery Method proposals can be IETF standards track documents or 3097 vendor-defined documents. In either case, they will be registered with 3098 IANA using procedures that extend those defined in [ipp-mod] section 6 3099 and 11. 3101 These extension procedures are aligned with the guidelines as set forth 3102 by the IESG [IANA-CON]. Section 13.1 defines the format and content for 3103 new registrations for consideration. IANA will reject registration 3104 proposals that leave out required information or do not follow the 3105 appropriate format described in Section 13.1. 3107 Implementers can, at any time, define new Event Notification Delivery 3108 Methods by proposing the complete specification to IANA: 3110 iana@iana.org 3112 or by filling out the appropriate form on the IANA web pages 3113 (http://www.iana.org). 3115 IANA will forward the registration proposal to the IPP Designated Expert 3116 who will review the proposal with a mailing list that the Designated 3117 Expert keeps for this purpose. Initially, that list will be the mailing 3118 list used by the IPP WG: 3120 ipp@pwg.org 3122 even after the IPP WG is disbanded as permitted by [IANA-CON]. The IPP 3123 Designated Expert is appointed by the IESG Area Director responsible for 3124 IPP, according to [IANA-CON]. 3126 When a Delivery Method Document is approved, the IPP Designated Expert 3127 becomes the point of contact for any future maintenance that might be 3128 required for that registration. 3130 13.1Format and Requirements for IPP Delivery Method Registration 3131 Proposals 3133 This section defines the format and requirements for an IPP Event 3134 Notification Delivery Method Registration Proposal. A Delivery Method 3135 Registration Proposal: 3137 1.MUST contain the following information: 3139 Type of registration: IPP Event Notification Delivery Method 3140 Name of this delivery method: 3141 Proposed URL scheme name of this delivery method: 3142 Name of proposer: 3143 Address of proposer: 3144 Email address of proposer: 3145 Is this delivery method REQUIRED or OPTIONAL for conformance to the 3146 IPP Event Notification Specification document: 3147 Is this delivery method defining Machine Consumable and/or Human 3148 Consumable content: 3150 2.MUST meet the conformance requirements for Delivery Method Documents 3151 specified in section 10. 3153 14 Internationalization Considerations 3155 This IPP Notification specification continues support for the 3156 internationalization of [ipp-mod] of attributes containing text strings 3157 and names. Allowing a Subscribing Client to specify a different natural 3158 language and charset for each Subscription Object increases the 3159 internationalization support. 3161 The Printer MUST be able to localize the content of Human Consumable 3162 Event Notifications and to localize the value of "notify-text" attribute 3163 in Machine Consumable Event Notifications that it sends to Notification 3164 Recipients. For localization, the Printer MUST use the value of the 3165 "notify-charset" attribute and the "notify-natural-language" attribute 3166 in the Subscription Object supplied by the Subscribing Client. 3168 15 Security Considerations 3170 By far the biggest security concern is the abuse of notification: 3171 sending unwanted Event Notifications to third parties (i.e., spam). The 3172 problem is made worse by notification addresses that may be 3173 redistributed to multiple parties (e.g., mailing lists). There exist 3174 scenarios where third party notification is required (see Scenario #2 3175 and #3 in [ipp-not-req]). The fully secure solution would require 3176 active agreement of all recipients before sending out anything. 3177 However, requirement #9 in [ipp-req] ("There is no requirement for IPP 3178 Printer receiving the print request to validate the identity of an Event 3179 recipient") argues against this. Certain systems may decide to disallow 3180 third party Event Notifications (a traditional fax model). 3182 Clients submitting Notification requests to the IPP Printer has the same 3183 security issues as submitting an IPP/1.1 print job request. The same 3184 mechanisms used by IPP/1.1 can therefore be used by the client 3185 Notification submission. Operations that require authentication can use 3186 the HTTP authentication. Operations that require privacy can use the 3187 HTTP/TLS privacy. 3189 The Notification access control model should be similar to the IPP 3190 access control model for Jobs. Creating a Per-Printer Subscription 3191 Object is associated with a user. Only the creator or an Operator can 3192 cancel the Subscription Object. The system may limit the listing of 3193 items to only those items owned by the user. Some Subscription Objects 3194 (e.g., those that have a lifetime longer than a job) can be done only by 3195 privileged users (users having Operator and/or Administrator access 3196 rights), if that is the authorization policy. 3198 The standard security concerns (delivery to the right user, privacy of 3199 content, tamper proof content) apply to the Delivery Method. IPP should 3200 use the security mechanism of the Delivery Method used. Some delivery 3201 mechanisms are more secure than others. Therefore, sensitive Event 3202 Notifications should use the Delivery Method that has the strongest 3203 security. 3205 16 Status Codes 3207 The following status codes are defined as extensions for Notification 3208 and are returned as the value of the "status-code" parameter in the 3209 Operation Attributes Group of a response (see [ipp-mod] section 3210 3.1.6.1). Operations in this document can also return the status codes 3211 defined in section 13 of [ipp-mod]. The 'successful-ok' status code is 3212 an example of such a status code. 3214 16.1successful-ok-ignored-subscriptions (0x0003) 3216 The Subscription Creation Operation was unable to create all requested 3217 Subscription Objects. 3219 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3220 operation, this status code means that the Printer created one or more 3221 Subscription Objects, but not all requested Subscription Objects. 3223 For a Job Creation operation, this status code means that the Printer 3224 created the Job along with zero or more Subscription Objects. The 3225 Printer returns this status code even if other job attributes are 3226 unsupported or in conflict. That is, if an IPP Printer finds a warning 3227 that would allow it to return 'successful-ok-ignored-subscriptions' and 3228 either 'successful-ok-ignored-or-substituted-attributes' and/or 3229 'successful-ok-conflicting-attributes', it MUST return 'successful-ok- 3230 ignored-subscriptions'. 3232 16.2client-error-ignored-all-subscriptions (0x0414) 3234 This status code is the same as 'successful-ok-ignored-subscriptions' 3235 except that only the Create-Job-Subscriptions and Create-Printer- 3236 Subscriptions operation return it. They return this status code only 3237 when the Printer creates zero Subscription Objects. 3239 17 Status Codes in Subscription Attributes Groups 3241 This section contains values of the "notify-status-code" attribute that 3242 the Printer returns in a Subscription Attributes Group in a response 3243 when the corresponding Subscription Object: 3245 1. is not created or 3247 2. is created and some of the client-supplied attributes are not 3248 supported. 3250 The following sections are ordered in decreasing order of importance of 3251 the status-codes. 3253 17.1client-error-uri-scheme-not-supported (0x040C) 3255 This status code is defined in [ipp-mod]. This document extends its 3256 meaning and allows it to be in a Subscription Attributes Group of a 3257 response. 3259 The scheme of the client-supplied URI in a "notify-recipient-uri" 3260 Subscription Template Attribute in a Subscription Creation Operation is 3261 not supported. See section 5.3.1. 3263 17.2client-error-too-many-subscriptions (0x0415) 3265 The number of Subscription Objects supported by the Printer would be 3266 exceeded if this Subscription Object were created (see section 5.2). 3268 17.3successful-ok-too-many-events (0x0005) 3270 The client supplied more Events in the "notify-events" operation 3271 attribute of a Subscription Creation Operation than the Printer 3272 supports, as indicated in its "notify-max-events-supported" Printer 3273 attribute (see section 5.3.2). 3275 17.4successful-ok-ignored-or-substituted-attributes (0x0001) 3277 This status code is defined in [ipp-mod]. This document extends its 3278 meaning to include unsupported Subscription Template Attributes and it 3279 can appear in a Subscription Attributes Group. 3281 18 Encodings of Additional Attribute Tags 3283 This section assigns values to two attributes tags as extensions to the 3284 encoding defined in [ipp-pro]). 3286 The "subscription-attributes-tag" delimits Subscription Template 3287 Attributes Groups in requests and Subscription Attributes Groups in 3288 responses. 3290 The "event-notification-attributes-tag" delimits Event Notifications in 3291 Delivery Methods that use an IPP-like encoding. 3293 The following table specifies the values for the delimiter tags: 3295 Tag Value (Hex) Meaning 3297 0x06 "subscription-attributes-tag" 3298 0x07 "event-notification-attributes-tag" 3300 19 References 3302 [IANA-CON] 3303 Narte, T. and Alvestrand, H.T.: Guidelines for Writing an IANA 3304 Considerations Section in RFCs, Work in Progress, draft-iesg-iana- 3305 considerations-04.txt, May 21, 1998. 3307 [ipp-mod] 3308 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3309 "Internet Printing Protocol/1.1: Model and Semantics", , work in progress, May 22, 2000. 3312 [ipp-not-req] 3313 deBry, R., Lewis, H., Hastings, T., "Internet Printing 3314 Protocol/1.1: Requirements for IPP Notifications", , work in progress, July 6, 2000. 3317 [ipp-pro] 3318 Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing 3319 Protocol/1.1: Encoding and Transport", , work in progress, May 30, 2000. 3322 [ipp-prog] 3323 Hastings, T., Bergman, R., Lewis, H., "IPP: Job Progress 3324 Attributes", work in 3325 progress, July 6, 2000. 3327 [ipp-set] 3328 Kugler, C., Hastings, T., Herriot, R., Lewis, H, "Internet Printing 3329 Protocol (IPP): Job and Printer Set Operations", , work in progress, March 23, 2000. 3332 [RFC2026] 3333 S. Bradner, "The Internet Standards Process -- Revision 3", RFC 3334 2026, October 1996. 3336 [RFC2119] 3337 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3338 Levels", RFC 2119 , March 1997 3340 [RFC2566] 3341 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3342 "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, 3343 April 1999. 3345 [RFC2567] 3346 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3347 2567, April 1999. 3349 [RFC2568] 3350 Zilles, S., "Rationale for the Structure and Model and Protocol for 3351 the Internet Printing Protocol", RFC 2568, April 1999. 3353 [RFC2569] 3354 Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between 3355 LPD and IPP Protocols", RFC 2569, April 1999. 3357 20 Author's Addresses 3359 Robert Herriot 3360 Xerox Corporation 3361 3400 Hillview Ave., Bldg #1 3362 Palo Alto, CA 94304 3364 Phone: 650-813-7696 3365 Fax: 650-813-6860 3366 Email: robert.herriot@pahv.xerox.com 3368 Tom Hastings 3369 Xerox Corporation 3370 737 Hawaii St. ESAE 231 3371 El Segundo, CA 90245 3373 Phone: 310-333-6413 3374 Fax: 310-333-5514 3375 e-mail: hastings@cp10.es.xerox.com 3377 Scott A. Isaacson 3378 Novell, Inc. 3379 122 E 1700 S 3380 Provo, UT 84606 3382 Phone: 801-861-7366 3383 Fax: 801-861-2517 3384 e-mail: sisaacson@novell.com 3386 Roger deBry 3387 Utah Valley State College 3388 Orem, UT 84058 3390 Phone: (801) 222-8000 3391 EMail: debryro@uvsc.edu 3393 Jay Martin 3394 Underscore Inc. 3395 9 Jacqueline St. 3396 Hudson, NH 03051-5308 3397 603-889-7000 3398 fax: 775-414-0245 3399 e-mail: jkm@underscore.com 3401 Michael Shepherd 3402 Xerox Corporation 3403 800 Phillips Road MS 128-51E 3404 Webster, NY 14450 3406 Phone: 716-422-2338 3407 Fax: 716-265-8871 3408 e-mail: mshepherd@crt.xerox.com 3409 Ron Bergman 3410 Hitachi Koki Imaging Solutions 3411 1757 Tapo Canyon Road 3412 Simi Valley, CA 93063-3394 3414 Phone: 805-578-4421 3415 Fax: 805-578-4001 3416 Email: rbergma@hitachi-hkis.com 3418 A. Appendix - Model for Notification with Cascading Printers 3420 With this model (see Figure 2), there is an intervening Print server 3421 between the human user and the output-device. So the system effectively 3422 has two Printers. There are two cases to consider. 3424 1. When the Printer 1 (in the server) generates Events, the system 3425 behaves like the client and Printer in Figure 1. In this case, 3426 Printer 1 sends Event Notifications that are shown as Event 3427 Notifications (A) of Figure 2,. 3429 2. When the Printer 2 (in the output-device) generates Events, there 3430 are two possible system configurations: 3432 a)Printer 1 forwards the client-supplied Subscription Creation 3433 Operations to the downstream Printer 2 and lets Printer 2 send 3434 the Event Notifications directly to the Notification Recipients 3435 supplied by the Client (Event Notifications(C) in the diagram). 3437 b)Printer 1 performs the client-supplied Subscription Creation 3438 Operations and also forwards the Subscription Creation 3439 Operations to Printer 2 with the Notification Recipient changed 3440 to be the Printer 1. When an Event occurs in Printer 2, Printer 3441 2 sends the Event Notification (B) to Notification Recipient of 3442 Printer 1, which relays the received Event Notification (B) to 3443 the client-supplied Notification Recipient (as Event 3444 Notifications(A) in the diagram). Note, when a client performs a 3445 Subscription Creation Operation, Printer 1 need not forward the 3446 Subscription Creation Operation to Printer 2 if it would create 3447 a duplicate Subscription Object on Printer 2. 3449 Note: when Printer 1 is forwarding Subscription Creation Operations to 3450 Printer 2, it may request Printer 2 to create additional Subscription 3451 Objects (called "piggy-backing"). Piggy-backing is useful when: 3453 . Device A is configured to accept (IPP or non-IPP) requests from 3454 other servers. 3456 . Server S wants to receive Job Events that the client didn't request 3457 and Server S wants these Events for jobs it submits and not for 3458 other jobs. 3460 server S device A 3461 +------------+ +------------+ 3462 | | | | 3463 +--------+ Subscription | ###########| | ###########| 3464 | client |--Creation ----># Printer #| Subscription | # Printer #| 3465 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 3466 | ###|#######| Operation | ####|#|####| 3467 +----|---^---+ +-----|-|----+ 3468 +--------+ Event | | | | 3469 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 3470 |ation Re|<-------------Event Notifications(C)-----------------+ 3471 |cipient | 3472 +--------+ 3474 Figure 2 - Model for Notification with Cascading Printers 3476 B. Appendix - Distributed Model for Notification 3478 A Printer implementation could use some other remote notification 3479 service to provide some or most of the service. For example, the remote 3480 notification service could send Event Notifications using Delivery 3481 Methods that are not directly supported by the output device or server. 3482 Or, the remote notification service could store Subscription Objects 3483 (passed to it from the output device in response to Subscription 3484 Creation requests), accept Events, format the Event Notification in the 3485 natural language of the Notification Recipient, and send the Event 3486 Notifications to the Notification Recipient(s). 3488 Figure 3 shows this partitioning. The interface between the output 3489 device (or server) and the remote notification service is outside the 3490 scope of this document and is intended to be transparent to the client 3491 and this document. The combination of the output device (or server) and 3492 the notification service together constitute an IPP Printer conforming 3493 to this Notification document. 3495 *********************** 3496 * 3497 * Printer (including 3498 * the distributed 3499 * Notification Service) 3500 * 3501 * output device or server 3502 * +---------------+ 3503 PDA, desktop, or server * + ########### + 3504 +--------+ * | # partial # | 3505 | client |---IPP Subscription--------># Printer # | 3506 +--------+ Creation operation * | # Object # | 3507 * | #####|##### | 3508 * +-------|-------+ 3509 * | Subscriptions 3510 * | OR Event 3511 +------------+ * | Notifications 3512 |Notification| IPP-defined * +------v--------+ 3513 |Recipient |<--Event Notifications---| Notification | 3514 +------------+ * | Service | 3515 * +---------------+ 3516 * 3517 ************************* 3518 *** = Implementation configuration opaque boundary 3520 Figure 3 - Opaque Use of a Notification Service Transparent to the 3521 Client 3523 C. Appendix - Extended Notification Recipient 3525 The model allows for an extended Notification Recipient that is itself a 3526 notification service that forwards each Event Notification to another 3527 recipient (called the Ultimate Notification Recipient in this section). 3528 The Delivery Method to the Ultimate Recipient is probably different from 3529 the Delivery Method used by the Printer to the extended Notification 3530 Recipient. 3532 This extended Notification Recipient is transparent to the Printer but 3533 not to the client. 3535 When a client performs a Subscription Creation Operation, it specifies 3536 the extended Notification Recipient as it would any Notification 3537 Recipient. In addition, the client specifies the Ultimate Notification 3538 Recipient in the Subscription Creation Operation in a manner specified 3539 by the extended Notification Recipient. Typically, it is either some 3540 bytes in the value of "notify-user-data" or some additional parameter in 3541 the value of "notify-recipient-uri". The client also subscribes directly 3542 with the extended Notification Recipient (by means outside this 3543 document), since it is a notification service in its own right. 3545 The IPP Printer treats the extended Notification Recipient like any 3546 other Notification Recipient and the IPP Printer is not aware of the 3547 forwarding. The Delivery Method that the extended Notification Recipient 3548 uses for delivering the Event Notification to the Ultimate Notification 3549 Recipient is beyond the scope of this document and is transparent to the 3550 IPP Printer. 3552 Examples of this extended Notification Recipient are paging, immediate 3553 messaging services, general notification services, and NOS vendors' 3554 infrastructure. Figure 4 shows this approach. 3556 PDA, desktop, or server server or output device 3557 +---------------+ 3558 +--------+ | ########### | 3559 | client |---Subscription Creation -----------># Printer # | 3560 +--------+ Operation | # Object # | 3561 | #####|##### | 3562 +------------+ +------------+ IPP-defined +-------|-------+ 3563 |Ultimate | any |Notification|<--Event Notifications----+ 3564 |Notification|<----|Recipient | 3565 |Recipient | +------------+ 3566 +------------+ (Notification Service) 3568 Figure 4 - Use of an Extended Notification Recipient transparent to the 3569 Printer 3571 D. Appendix - Details about Conformance Terminology 3573 The following paragraph provide more details about conformance 3574 terminology. 3576 REQUIRED - an adjective used to indicate that a conforming IPP 3577 Printer implementation MUST support the indicated operation, 3578 object, attribute, attribute value, status code, or out-of-band 3579 value in requests and responses. See [ipp-mod] "Appendix A - 3580 Terminology for a definition of "support". Since support of this 3581 entire Notification specification is OPTIONAL for conformance to 3582 IPP/1.0 or IPP/1.1, the use of the term REQUIRED in this document 3583 means "REQUIRED if this OPTIONAL Notification specification is 3584 implemented". 3586 RECOMMENDED - an adjective used to indicate that a conforming IPP 3587 Printer implementation is recommended to support the indicated 3588 operation, object, attribute, attribute value, status code, or out- 3589 of-band value in requests and responses. Since support of this 3590 entire Notification specification is OPTIONAL for conformance to 3591 IPP/1.0 or IPP/1.1, the use of the term RECOMMENDED in this 3592 document means "RECOMMENDED if this OPTIONAL Notification 3593 specification is implemented". 3595 OPTIONAL - an adjective used to indicate that a conforming IPP 3596 Printer implementation MAY, but is NOT REQUIRED to, support the 3597 indicated operation, object, attribute, attribute value, status 3598 code, or out-of-band value in requests and responses. 3600 E. Appendix - Object Model for Notification 3602 This section describes the Notification object model that adds a 3603 Subscription Object which together with the Job and Printer object 3604 provide the complete Notification semantics. 3606 The object relationships can be seen pictorially as: 3608 Subscription Objects (Per-Printer Subscriptions) Printer object 3609 +----+ +------------+ 3610 | s1 |<--------------------------------------------->| | 3611 +----++ | | 3612 | s2 |<-------------------------------------------->| p1 | 3613 +----++ | | 3614 | s3 |<------------------------------------------->| | 3615 +----+ +------------+ 3616 Job objects 3617 +---------+ 3618 | | 3619 +----+ | j1 | 3620 | s4 |<------->| | 3621 +----+ | | 3622 | | s4 is a Per-Job Subscription Object 3623 ++--------++ 3624 | | 3625 +----+ | j2 | 3626 | s5 |<------>| | 3627 +----++ | | 3628 | s6 |<----->| | s5 and s6 are Per-Job Subscription 3629 +----+ ++--------++ Objects 3630 | | 3631 | j3 | 3632 | | 3633 | | <----> indicates association 3634 +---------+ 3636 Figure 5 - Object Model for Notification 3638 s1, s2, and s3 are Per-Printer Subscription Objects and can 3639 identify Printer and/or Job Events. 3640 s4, s5, and s6 are Per-Job Subscription Objects and can identify 3641 Printer and/or Job Events. 3643 E.1 Appendix - Object relationships 3645 This sub-section defines the object relationships between the Printer, 3646 Job, and Subscription Objects by example. Whether Per-Printer 3647 Subscription Objects are actually contained in a Printer object or are 3648 just bi-directionally associated with them in some way is IMPLEMENTATION 3649 DEPENDENT and is transparent to the client. Similarly, whether Per-Job 3650 Subscription Objects are actually contained in a Job object or are just 3651 bi-directionally associated with them in some way is IMPLEMENTATION 3652 DEPENDENT and is transparent to the client. The object relationships 3653 are defined as follows: 3655 E.2 Printer Object and Per-Printer Subscription Objects 3657 1. The Printer object contains (is associated with) zero or more Per- 3658 Printer Subscription Objects (p1 contains s1-s3 Per-Printer 3659 Subscription Objects). 3661 2. Each Per-Printer Subscription Object (s1, s2, and s3) is contained 3662 in (or is associated with) exactly one Printer object (p1). 3664 E.3 Job Object and Per-Job Subscription Objects 3666 1. A Job object (j1, j2, j3) is associated with zero or more Per-Job 3667 Subscription Objects (s4-s6). Job j1 is associated with Per-Job 3668 Subscription Object s4, Job j2 is associated with Per-Job 3669 Subscription Objects s5 and s6, and Job j3 is not associated with 3670 any Per-Job Subscription Object. 3672 2. Each Per-Job Subscription Object is associated with exactly one Job 3673 object. 3675 F. Appendix - Per-Job versus Per-Printer Subscription Objects 3677 Per-Job and Per-Printer Subscription Objects are quite similar. Either 3678 type of Subscription Object can subscribe to Job Events, Printer Events, 3679 or both. Both types of Subscription Objects can be queried using the 3680 Get-Subscriptions and Get-Subscription-Attributes operations and 3681 canceled using the Cancel-Subscription operation. Both types of 3682 Subscription Objects create Subscription Objects which have the same 3683 Subscription Object attributes defined. However, there are some 3684 semantic differences between Per-Job Subscription Objects and Per- 3685 Printer Subscription Objects. A Per-Job Subscription Object is 3686 established by the client when submitting a job and after creating the 3687 job using the Create-Job-Subscriptions operation by specifying the "job- 3688 id" of the Job with the "notify-job-id" attribute. A Per-Printer 3689 Subscription Object is established between a client and a Printer using 3690 the Create-Printer-Subscriptions operation. Some specific differences 3691 are: 3693 1.A client usually creates one or more Per-Job Subscription Objects as 3694 part of the Job Creation operations (Create-Job, Print-Job, and 3695 Print-URI), rather than using the OPTIONAL Create-Job-Subscriptions 3696 operation, especially since Printer implementations NEED NOT support 3697 the Create-Job-Subscriptions operation, since it is OPTIONAL. 3699 2.For Per-Job Subscription Objects, the Subscription Object is only 3700 valid while the job is "not-complete" (see sections 5.4.3) while for 3701 the Per-Printer Subscription Objects, the Subscription Object is 3702 valid until the time (in seconds) that the Printer returned in the 3703 "notify-lease-expiration-time" operation attribute. 3705 3.Job Events in a Per-Job Subscription Object apply only to "one job" 3706 (the Job created by the Job Creation operation or references by the 3707 Create-Job-Subscriptions operation) while Job Events in a Per-Printer 3708 Subscription Object apply to ALL jobs contained in the IPP Printer. 3710 G. Appendix: Full Copyright Statement 3712 Copyright (C) The Internet Society (1998,1999,2000). All Rights Reserved 3714 This document and translations of it may be copied and furnished to 3715 others, and derivative works that comment on or otherwise explain it or 3716 assist in its implementation may be prepared, copied, published and 3717 distributed, in whole or in part, without restriction of any kind, 3718 provided that the above copyright notice and this paragraph are included 3719 on all such copies and derivative works. However, this document itself 3720 may not be modified in any way, such as by removing the copyright notice 3721 or references to the Internet Society or other Internet organizations, 3722 except as needed for the purpose of developing Internet standards in 3723 which case the procedures for copyrights defined in the Internet 3724 Standards process must be followed, or as required to translate it into 3725 languages other than English. 3727 The limited permissions granted above are perpetual and will not be 3728 revoked by the Internet Society or its successors or assigns. 3730 This document and the information contained herein is provided on an "AS 3731 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 3732 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 3733 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 3734 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 3735 FITNESS FOR A PARTICULAR PURPOSE.