idnits 2.17.1 draft-ietf-ipp-not-spec-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 ([RFC2911,RFC2910], [RFC2566,RFC2565]), 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 1595 has weird spacing: '...ipients do no...' == Line 3530 has weird spacing: '...FC xxxx m.n...' == Line 3671 has weird spacing: '...FC xxxx m.n...' == Line 3686 has weird spacing: '...FC xxxx m.n...' == Line 4314 has weird spacing: '...reation opera...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Unrecognized Status in '[Target Category: standards track]', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 19, 2001) is 8192 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'IPP-IIG' is mentioned on line 4328, but not defined == Missing Reference: 'RFC2616' is mentioned on line 4355, but not defined ** Obsolete undefined reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2434 (ref. 'IANA-CON') (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2565 (Obsoleted by RFC 2910) ** Obsolete normative reference: RFC 2566 (Obsoleted by RFC 2911) ** Downref: Normative reference to an Experimental RFC: RFC 2567 ** Downref: Normative reference to an Experimental RFC: RFC 2568 ** Downref: Normative reference to an Experimental RFC: RFC 2569 ** Obsolete normative reference: RFC 2717 (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2910 (Obsoleted by RFC 8010) ** Obsolete normative reference: RFC 2911 (Obsoleted by RFC 8011) Summary: 16 errors (**), 0 flaws (~~), 11 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Printing Protocol WG R. Herriot (editor) 3 INTERNET-DRAFT T. Hastings 4 M. Shepherd 5 Updates RFC 2910 and 2911 Xerox Corporation 6 [Target Category: standards track] R. deBry 7 Expires: May 19, 2002 Utah Valley State College 8 S. Isaacson 9 Novell, Inc. 10 J. Martin 11 Underscore 12 R. Bergman 13 Hitachi Koki Imaging Solutions 14 November 19, 2001 15 Internet Printing Protocol (IPP): 16 Event Notifications and Subscriptions 18 Copyright (C) The Internet Society (2001). All Rights Reserved. 20 Status of this Memo 22 This document is an Internet-Draft and is in full conformance with 23 all provisions of Section 10 of [RFC2026]. Internet-Drafts are 24 working documents of the Internet Engineering Task Force (IETF), its 25 areas, and its working groups. Note that other groups may also 26 distribute working documents as Internet-Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress". 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt 35 The list of Internet-Draft Shadow Directories can be accessed as 36 http://www.ietf.org/shadow.html. 38 Abstract 40 This document describes an OPTIONAL extension to the Internet 41 Printing Protocol/1.0 (IPP) [RFC2566, RFC2565] and IPP/1.1 [RFC2911, 42 RFC2910]. This extension allows a client to subscribe to printing 43 related Events. Subscriptions are modeled as Subscription Objects. 44 The Subscription Object specifies that when one of the specified 45 Events occurs, the Printer sends an asynchronous Event Notification 46 to the specified Notification Recipient via the specified Delivery 47 Method (i.e., protocol). A client associates Subscription Objects 48 with a particular Job by performing the Create-Job-Subscriptions 49 operation or by submitting a Job with subscription information. A 50 client associates Subscription Objects with the Printer by performing 51 a Create-Printer-Subscriptions operation. Four other operations are 52 defined for Subscription Objects: Get-Subscriptions-Attributes, Get- 53 Subscriptions, Renew-Subscription, and Cancel-Subscription. 55 Table of Contents 57 1 Introduction.....................................................7 58 1.1 Notification Overview..........................................7 60 2 Models for Notification.........................................10 61 2.1 Model for Notification (Simple Case)..........................10 62 2.2 Model for Notification with Cascading Printers................11 63 2.3 Distributed Model for Notification............................11 64 2.4 Extended Notification Recipient...............................12 66 3 Terminology.....................................................12 67 3.1 Conformance Terminology.......................................12 68 3.2 Other Terminology.............................................13 70 4 Object Relationships............................................16 71 4.1 Printer and Per-Printer Subscription Objects..................16 72 4.2 Printer, Job and Per-Job Subscription Objects.................16 74 5 Subscription Object.............................................16 75 5.1 Rules for Support of Subscription Template Attributes.........17 76 5.2 Rules for Processing Subscription Template Attributes.........18 77 5.3 Subscription Template Attributes..............................22 78 5.3.1 notify-recipient-uri (uri) OR notify-pull-method (type2 79 keyword)...............................................25 80 5.3.1.1 notify-recipient-uri (uri)................................25 81 5.3.1.2 notify-pull-method (type2 keyword)........................25 82 5.3.2 notify-events (1setOf type2 keyword)........................26 83 5.3.2.1 Standard Values for Subscribed Events.....................26 84 5.3.2.1.1 No Events...............................................27 85 5.3.2.1.2 Subscribed Printer Events...............................27 86 5.3.2.1.3 Subscribed Job Events...................................29 87 5.3.2.2 Rules for Matching of Subscribed Events...................30 88 5.3.2.2.1 Rules for Matching of Printer Events....................30 89 5.3.2.2.2 Rules for Matching of Job Events........................31 90 5.3.2.2.3 Special Cases for Matching Rules........................31 91 5.3.3 notify-attributes (1setOf type2 keyword)....................32 92 5.3.4 notify-user-data (octetString(63))..........................34 93 5.3.5 notify-charset (charset)....................................34 94 5.3.6 notify-natural-language (naturalLanguage)...................35 95 5.3.7 notify-lease-duration (integer(0:67108863)).................35 96 5.3.8 notify-time-interval (integer(0:MAX)).......................36 97 5.4 Subscription Description Attributes...........................38 98 5.4.1 notify-subscription-id (integer (1:MAX))...................38 99 5.4.2 notify-sequence-number (integer (0:MAX))....................39 100 5.4.3 notify-lease-expiration-time (integer(0:MAX))...............39 101 5.4.4 notify-printer-up-time (integer(1:MAX)).....................40 102 5.4.5 notify-printer-uri (uri)....................................41 103 5.4.6 notify-job-id (integer(1:MAX))..............................41 104 5.4.7 notify-subscriber-user-name (name(MAX)).....................42 106 6 Printer Description Attributes Related to Notification..........42 107 6.1 printer-state-change-time (integer(1:MAX))....................43 108 6.2 printer-state-change-date-time (dateTime).....................43 110 7 New Values for Existing Printer Description Attributes..........43 111 7.1 operations-supported (1setOf type2 enum)......................43 113 8 Attributes Only in Event Notifications..........................44 114 8.1 notify-subscribed-event (type2 keyword).......................44 115 8.2 notify-text (text(MAX)).......................................45 117 9 Event Notification Content......................................45 118 9.1 Content of Machine Consumable Event Notifications.............48 119 9.1.1 Event Notification Content Common to All Events.............48 120 9.1.2 Additional Event Notification Content for Job Events........50 121 9.1.3 Additional Event Notification Content for Printer Events....51 122 9.2 Content of Human Consumable Event Notification................51 123 9.2.1 Event Notification Content Common to All Events.............52 124 9.2.2 Additional Event Notification Content for Job Events........54 125 9.2.3 Additional Event Notification Content for Printer Events....55 127 10 Delivery Methods...............................................56 129 11 Operations for Notification....................................58 130 11.1 Subscription Creation Operations.............................58 131 11.1.1 Create-Job-Subscriptions Operation.........................59 132 11.1.1.1 Create-Job-Subscriptions Request.........................59 133 11.1.1.2 Create-Job-Subscriptions Response........................60 134 11.1.2 Create-Printer-Subscriptions operation.....................61 135 11.1.2.1 Create-Printer-Subscriptions Request.....................62 136 11.1.2.2 Create-Printer-Subscriptions Response....................62 137 11.1.3 Job Creation Operations - Extensions for Notification......62 138 11.1.3.1 Job Creation Request.....................................63 139 11.1.3.2 Job Creation Response....................................64 140 11.2 Other Operations.............................................65 141 11.2.1 Restart-Job Operation - Extensions for Notification........65 142 11.2.2 Validate-Job Operation - Extensions for Notification.......65 143 11.2.3 Get-Printer-Attributes - Extensions for Notification.......66 144 11.2.4 Get-Subscription-Attributes operation......................66 145 11.2.4.1 Get-Subscription-Attributes Request......................67 146 11.2.4.2 Get-Subscription-Attributes Response.....................68 147 11.2.5 Get-Subscriptions operation................................69 148 11.2.5.1 Get-Subscriptions Request................................69 149 11.2.5.2 Get-Subscriptions Response...............................71 150 11.2.6 Renew-Subscription operation...............................72 151 11.2.6.1 Renew-Subscription Request...............................72 152 11.2.6.2 Renew-Subscription Response..............................73 153 11.2.7 Cancel-Subscription operation..............................74 154 11.2.7.1 Cancel-Subscription Request..............................75 155 11.2.7.2 Cancel-Subscription Response.............................75 157 12 Conformance Requirements.......................................76 159 13 IANA Considerations............................................77 160 13.1 Attribute Registrations......................................78 161 13.2 Additional Enum Attribute Value Registrations for the 162 "operations-supported" Printer Attribute..........................79 163 13.3 Operation Registrations......................................79 164 13.4 Status code Registrations....................................80 165 13.5 Attribute Group tag Registrations............................80 166 13.6 Registration of Events.......................................80 167 13.7 Registration of Event Notification Delivery Methods..........81 168 13.7.1 Requirements for Registration of Event Notification Delivery 169 Methods................................................81 170 13.7.1.1 Required Characteristics.................................81 171 13.7.1.2 Naming Requirements......................................82 172 13.7.1.3 Functionality Requirements...............................82 173 13.7.1.4 Usage and Implementation Requirements....................82 174 13.7.1.5 Publication Requirements.................................83 175 13.7.2 Registration Procedure.....................................83 176 13.7.2.1 Present the proposal to the Community....................83 177 13.7.2.2 Delivery Method Reviewer.................................83 178 13.7.2.3 IANA Registration........................................84 179 13.7.3 Delivery Method Document Registrations.....................84 180 13.7.4 Registration Template......................................84 182 14 Internationalization Considerations............................85 184 15 Security Considerations........................................85 186 16 Status Codes...................................................86 187 16.1 successful-ok-ignored-subscriptions (0x0003).................86 188 16.2 client-error-ignored-all-subscriptions (0x0414)..............87 190 17 Status Codes in Subscription Attributes Groups.................87 191 17.1 client-error-uri-scheme-not-supported (0x040C)...............87 192 17.2 client-error-attributes-or-values-not-supported (0x040B).....87 193 17.3 client-error-too-many-subscriptions (0x0415).................88 194 17.4 successful-ok-too-many-events (0x0005).......................88 195 17.5 successful-ok-ignored-or-substituted-attributes (0x0001).....88 197 18 Encodings of Additional Attribute Tags.........................88 198 19 References.....................................................89 200 20 Author's Addresses.............................................90 202 A. Appendix - Model for Notification with Cascading Printers......92 204 B. Appendix - Distributed Model for Notification..................93 206 C. Appendix - Extended Notification Recipient.....................94 208 D. Appendix - Details about Conformance Terminology...............95 210 E. Appendix - Object Model for Notification.......................96 211 E.1 Appendix - Object relationships..............................97 212 E.2 Printer Object and Per-Printer Subscription Objects..........98 213 E.3 Job Object and Per-Job Subscription Objects..................98 215 F. Appendix - Per-Job versus Per-Printer Subscription Objects.....98 217 G. Appendix - Description of the base IPP documents...............99 219 H. Appendix - Full Copyright Statement...........................100 221 Tables 222 Table 1 - Subscription Template Attributes........................24 223 Table 2 - Subscription Description Attributes.....................38 224 Table 3 - Printer Description Attributes Associated with Notification 225 ..............................................................42 226 Table 4 - Operation-id assignments................................44 227 Table 5 - Attributes in Event Notification Content................49 228 Table 6 - Additional Event Notification Content for Job Events....50 229 Table 7 - Combinations of Events and Subscribed Events for "job- 230 impressions-completed" ........................................51 231 Table 8 - Additional Event Notification Content for Printer Events51 232 Table 9 - Printer Name in Event Notification Content..............53 233 Table 10 - Event Name in Event Notification Content...............53 234 Table 11 - Event Time in Event Notification Content...............54 235 Table 12 - Job Name in Event Notification Content.................54 236 Table 13 - Job State in Event Notification Content................55 237 Table 14 - Printer State in Event Notification Content............56 238 Table 15 - Information about the Delivery Method..................57 239 Table 16 - Printer Conformance Requirements for Operations........77 241 Figures 242 Figure 1 - Model for Notification.................................11 243 Figure 2 - Model for Notification with Cascading Printers.........93 244 Figure 3 - Opaque Use of a Notification Service Transparent to the 245 Client ........................................................94 247 Figure 4 - Use of an Extended Notification Recipient transparent to 248 the Printer ...................................................95 249 Figure 5 - Object Model for Notification..........................97 251 1 Introduction 253 This IPP notification specification is an OPTIONAL extension to 254 Internet Printing Protocol/1.0 (IPP) [RFC2566, RFC2565] and IPP/1.1 255 [RFC2911, RFC2910]. See Appendix G for a description of the base IPP 256 documents. This document in combination with the following documents 257 is intended to meet the notification requirements described in [ipp- 258 not-req]: 260 Internet Printing Protocol (IPP): "Job Progress Attributes" 261 [ipp-prog] 262 One or more Delivery Method Documents registered with IANA (see 263 section 10). 265 Note: this document does not define any Delivery Methods, but it does 266 define the rules for conformance for Delivery Method Documents. 267 Delivery Method Documents are in preparation (see section 10) and 268 will be registered with IANA (see section 13.7.3). 270 Refer to the Table of Contents for the layout of this document. 272 1.1 Notification Overview 274 This document defines operations that a client can perform in order 275 to create Subscription Objects in a Printer and carry out other 276 operations on them. A Subscription Object represents a Subscription 277 abstraction. The Subscription Object specifies that when one of the 278 specified Events occurs, the Printer sends an asynchronous Event 279 Notification to the specified Notification Recipient via the 280 specified Delivery Method (i.e., protocol). 282 When a client (called a Subscribing Client) performs an operation 283 that creates a Subscription Object, the operation contains one or 284 more Subscription Template Attributes Groups. Each such group holds 285 information used by the Printer to initialize a newly created 286 Subscription Object. The Printer creates one Subscription Object for 287 each Subscription Template Attributes Group in the operation. This 288 group is like the Job Template Attributes group defined in [RFC2911]. 289 The following is an example of the information included in a 290 Subscription Template Attributes Group (see section 5 for details on 291 the Subscription Object attributes): 293 1.The names of Subscribed Events that are of interest to the 294 Notification Recipient. 295 2.The address (URL) of one Notification Recipient for a Push 296 Delivery Method or the method for a Pull Delivery Method. 297 3.The Delivery Method (i.e., the protocol) which the Printer uses 298 to send the Event Notification. 299 4.Some opaque data that the Printer sends to the Notification 300 Recipient in the Event Notification. The Notification Recipient 301 might use this opaque data as a forwarding address for the Event 302 Notification. 303 5.The charset to use in text fields within an Event Notification 304 6.The natural language to use in the text fields of the Event 305 Notification 306 7.The requested lease time in seconds for the Subscription Object 307 An operation that creates a Subscription Object is called a 308 Subscription Creation Operation. These operations include the 309 following operations (see section 11.1 for further details): 311 - Job Creation operation: When a client performs such an 312 operation (Print-Job, Print-URI, and Create-Job), a client can 313 include zero or more Subscription Template Attributes Groups in 314 the request. The Printer creates one Subscription Object for 315 each Subscription Template Attributes Group in the request, and 316 the Printer associates each such Subscription Object with the 317 newly created Job. This document extends these operations' 318 definitions in [RFC2911] by adding Subscription Template 319 Attributes Groups in the request and Subscription Attributes 320 Groups in the response. 322 - Create-Job-Subscriptions operation: A client can include one or 323 more Subscription Template Attributes Groups in the request. 324 The Printer creates one Subscription Object for each 325 Subscription Template Attributes Group and associates each with 326 the job that is the target of this operation. 328 - Create-Printer-Subscriptions operation: A client can include 329 one or more Subscription Template Attributes Groups in the 330 request. The Printer creates one Subscription Object for each 331 Subscription Template Attributes Group and associates each with 332 the Printer that is the target of this operation. 334 For each of the above operations: 336 - the Printer associates a Subscription Object with the Printer 337 or a specific Job. When a Subscription Object is associated 338 with a Job Object, it is called a Per-Job Subscription Object. 339 When a Subscription Object is associated with a Printer Object, 340 it is called a Per-Printer Subscription Object. 342 - the response contains one Subscription Attributes Group for 343 each Subscription Template Attributes Group in the request and 344 in the same order. When the Printer successfully creates a 345 Subscription Object, its corresponding Subscription Attributes 346 Group contains the "notify-subscription-id" attribute. This 347 attribute uniquely identifies the Subscription Object and is 348 analogous to a "job-id" for a Job object. Some operations 349 described below use the "notify-subscription-id" to identify 350 the target Subscription Object. 352 This document defines the following additional operations (see 353 section 11.2 for further details): 355 - Restart-Job operation: When a client performs the Restart-Job 356 operation [RFC2911], the Printer re-uses the same Job and its 357 Subscription Objects. 359 - Validate-Job operation: When a client performs this operation, 360 a client can include zero or more Subscription Template 361 Attributes Groups in the request. The Printer determines if it 362 could create one Subscription Object for each Subscription 363 Template Attributes Group in the request. This document extends 364 this operation's definition in [RFC2911] by adding Subscription 365 Template Attributes Groups in the request and Subscription 366 Attributes Groups in the response. 368 - Get-Subscription-Attributes operation: This operation allows a 369 client to obtain the specified attributes of a target 370 Subscription Object. 372 - Get-Subscriptions operation: This operation allows a client to 373 obtain the specified attributes of all Subscription Objects 374 associated with the Printer or a specified Job. 376 - Renew-Subscription operation: This operation renews the lease 377 on the target Per-Printer Subscription Object before it 378 expires. A newly created Per-Printer Subscription Object 379 receives an initial lease. It is the duty of the client to use 380 this operation frequently enough to preserve a Per-Printer 381 Subscription Object. The Printer deletes a Per-Printer 382 Subscription Object when its lease expires. A Per-Job 383 Subscription Object last exactly as long as its associated Job 384 Object and thus doesn't have a lease. 386 - Cancel-Subscription operation: This operation (1) cancels the 387 lease on the specified Per-Printer Subscription Object and 388 thereby deletes the Per-Printer Subscription Object or (2) 389 deletes the Per-Job Subscription Object. 391 When an Event occurs, the Printer finds all Subscription Objects 392 listening for the Event (see section 9 for details on finding such 393 Subscription Objects). For each such Subscription Object, the 394 Printer: 396 a)generates an Event Notification with information specified in 397 section 9, AND 398 b)either: 399 i) If the Delivery Method is a Push Delivery Method as 400 indicated by the presence of the Subscription Object's 401 "notify-recipient-uri" attribute, delivers the Event 402 Notification using the Delivery Method and target address 403 identified in the Subscription Object's "notify-recipient- 404 uri" attribute, OR 405 ii) If the Delivery Method is a Pull Delivery Method as 406 indicated by the presence of the Subscription Object's 407 "notify-pull-method" attribute, saves Event Notification 408 for a time period called the Event Life defined by the 409 Delivery Method, i.e., the Notification Recipient is 410 expected to fetch the Event Notifications. 412 2 Models for Notification 414 2.1 Model for Notification (Simple Case) 416 As part of a Subscription Creation Operation, an IPP Printer (i.e., 417 located in an output device or a server) creates one or more 418 Subscription Objects. In a Subscription Creation Operation, the 419 client specifies the Notification Recipient to which the Printer is 420 to deliver Event Notifications. A Notification Recipient can be the 421 Subscribing Client or a third party. 423 Figure 1 shows the Notification model for a simple Client-Printer 424 relationship. 426 embedded printer: 427 output device or server 428 PDA, desktop, or server +---------------+ 429 +--------+ | ########### | 430 | client |-----Subscription ---------># Printer # | 431 +--------+ Creation Operation | # Object # | 432 +------------+ | #####|##### | 433 |Notification| +-------|-------+ 434 |Recipient |<----IPP Event Notifications----+ 435 +------------+ (Job and/or Printer Events) 437 Figure 1 - Model for Notification 439 2.2 Model for Notification with Cascading Printers 441 With this model, there is an intervening Print server between the 442 human user and the Printer in the output device. If the Printer in 443 the output device generates an Event, the system can be configured to 444 send Event Notification either 446 - directly to the Notification Recipient specified by the 447 Subscribing Client or 449 - via the Print Server to the Notification Recipient specified by 450 the Subscribing Client. 452 See Appendix A for more details. 454 2.3 Distributed Model for Notification 456 The preceding sections (2.1 and 2.2) assume that the Notification 457 software resides in the same device or Server box as the rest of the 458 Printer software. In many implementations, the assumption is correct. 459 However, the Notification model also permits a distributed 460 implementation. 462 For example, the software that supports both Subscription Creation 463 Operations and sending of Event Notifications could be on hardware 464 that is separate from the output device. To make this work, there 465 must be a symbiotic relationship between the output device software 466 and the remote Notification software. Without the remote Notification 467 software, the output device software is not a complete Printer. 469 The term "Printer" in this document includes the software on the 470 output device or server box as well as Notification software that is 471 local to or remote from the output device. 473 Appendix B describes this example in detail. 475 2.4 Extended Notification Recipient 477 The model allows for an extended Notification Recipient that is 478 itself a Notification service that forwards each Event Notification 479 to another recipient. The client contacts this Notification Recipient 480 to arrange for forwarding by means outside the scope of this 481 document. The Printer need not be aware that the Notification 482 Recipient forwards Event Notifications. 484 Appendix C describes this example in detail. 486 3 Terminology 488 This section defines terminology used throughout this document. Other 489 terminology is defined in [RFC2911]. 491 3.1 Conformance Terminology 493 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 494 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 495 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 496 12.1. If an implementation supports the extension defined in this 497 document, then these terms apply; otherwise, they do not. These 498 terms define conformance to this document only; they do not affect 499 conformance to other documents, unless explicitly stated otherwise. 500 See Appendix D for complete details. 502 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 503 the Printer implements a Delivery Method that REQUIRES the feature. 505 READ-ONLY - an adjective used in an attribute definition to indicate 506 that an IPP Printer MUST NOT allow the attribute's value to be 507 modified with the Set-Job-Attributes or Set-Printer-Attributes 508 operations (see [ipp-set]). Note: there is no Set-Subscription 509 operation so this term is not used for Subscription object 510 attributes. 512 3.2 Other Terminology 514 This document uses the same terminology as [RFC2911], such as 515 "client", "Printer", "attribute", "attribute value", "keyword", 516 "operation", "request", "response", and "support". In addition, the 517 following terms are defined for use in this document and the Delivery 518 Method Documents: 520 Administrator - A human user who establishes policy for and 521 configures the print system. 523 Operator - A human user who carries out the policy established by the 524 Administrator and controls the day to day running of the print 525 system. 527 IPP Client (or client) - The software component (PDA, desktop, or 528 server) that performs an IPP operation directed at an IPP Printer 529 (located in a server or output device). 531 Job Creation operation - One of the operations that creates a Job 532 object: Print-Job, Print-URI and Create-Job. The Restart-Job 533 operation [RFC2911] is not considered a Job Creation operation, 534 since the Printer re-uses the existing Job object. The Validate- 535 Job operation is not considered a Job Creation operation because 536 no Job object is created. Therefore, when a statement also 537 applies to either the Restart-Job and/or the Validate-Job 538 operation, they are mentioned explicitly. 540 Event - some occurrence (either expected or unexpected) within the 541 printing system of a change of state, condition, or configuration 542 of a Job or Printer object. An Event occurs only at one instant in 543 time and does not span the time the physical Event takes place. 544 For example, jam-occurred and jam-cleared are two distinct, 545 instantaneous Events, even though the jam may last for a while. 547 Event Notification - the information about an Event that the Printer 548 sends when an Event occurs. 550 Compound Event Notification - two or more Event Notifications that a 551 Printer sends together as a single entity. The Delivery Method 552 Document specifies whether the Delivery Method supports Compound 553 Event Notifications. 555 Job Event - an Event caused by some change in a particular job on the 556 Printer, e.g., 'job-completed'. 558 Printer Event - an Event caused by some change in the Printer that is 559 not specific to a job, e.g., 'printer-state-changed'. 561 Subscribed Event - an Event that the Subscribing Client expresses 562 interest in by making it a value of the "notify-events" attribute 563 on a Subscription Object. 565 Subscribed Job Event - a Subscribed Event that is a Job Event. 567 Subscribed Printer Event - a Subscribed Event that is a Printer 568 Event. 570 Notification Recipient - the entity to which the Printer sends an 571 Event Notification. 573 Delivery Method - the mechanism by which the Printer delivers the 574 Event Notification, e.g., via email or via an Event Notification 575 Delivery Method protocol defined for delivering IPP Event 576 Notifications. 578 Delivery Method Document - a document, separate from this document, 579 that defines a Delivery Method. 581 Push Delivery Method -The Printer sends the Event Notification 582 shortly after an Event occurs. For some Push Delivery Methods, the 583 Notification Recipient MUST send a response; for others it MUST 584 NOT send a response. 586 Pull Delivery Method - The Printer saves Event Notifications for some 587 event life time and expects the Notification Recipient to request 588 Event Notifications. The Printer returns the Event Notifications 589 in a response to such a request. 591 Event Life - For a Pull Delivery Method, the length of time in 592 seconds after an Event occurs during which the Printer will 593 return that Event in response to a request for Event 594 Notifications. After the Event Life expires, the Printer will 595 no longer return an Event Notification for that Event in such a 596 response. 598 Subscription Object - An object containing a set of attributes that 599 indicate: the Notification Recipient, the Delivery Method, the 600 Subscribed Events that cause the Printer to send an Event 601 Notification, and the information to send in an Event 602 Notification. 604 Per-Job Subscription Object - A Subscription Object that is 605 associated with a single Job. The Create-Job-Subscriptions 606 operation and Job Creation operations create such an object. 608 Per-Printer Subscription Object - A Subscription Object that is 609 associated with the Printer as a whole. The Create-Printer- 610 Subscriptions operation creates such an object. 612 Subscribing Client - The client that creates the Subscription Object. 614 Subscription Creation Operation - An operation that creates a 615 Subscription Object: Job Creation operations, Create-Job- 616 Subscriptions operation, Create-Printer-Subscriptions operation. 617 In the context of a Job Creation operation, a Subscription 618 Creation Operation is the part of the Job Creation operation that 619 creates a Subscription object. The Restart-Job operation 620 [RFC2911] is not considered a Subscription Creation Operation, 621 since the Printer re-uses the Job's existing Subscription Objects, 622 rather than creating any new Subscription Objects. 624 Subscription Creation Request - The request portion of a Subscription 625 Creation Operation. 627 Subscription Template Attributes - Subscription Object attributes 628 that a client can supply in a Subscription Creation Operation and 629 associated Printer Object attributes that specify supported and 630 default values for the Subscription Object attributes. 632 Subscription Description Attributes - Subscription Object attributes 633 that a Printer supplies during a Subscription Creation Operation. 635 Subscription Template Attributes Group - The attributes group in a 636 request that contains Subscription Object attributes that are 637 Subscription Template Attributes. 639 Subscription Attributes Group - The attributes group in a response 640 that contains Subscription Object attributes. 642 Human Consumable Event Notification - localized text for human 643 consumption only. There is no standardized format and thus 644 programs should not try to parse this text. 646 Machine Consumable Event Notification - bytes for program 647 consumption. The bytes are formatted according to the Delivery 648 Method document. 650 Printer - the software that supports an output device or print server 651 (see IPP/1.1 [RFC2911] which uses the terms Printer and Printer 652 object interchangeably). This document extends the IPP/1.1 Printer 653 definition to include the software that implements Subscription 654 Creation Operations and the sending of Event Notifications, even 655 if the software for such a Printer would be distributed across a 656 network (see section 2.3). 658 Notification - when not in the phrases 'Event Notification' and 659 'Notification Recipient' - the concepts of this specification, 660 i.e., Events, Subscription Objects, and Event Notifications. 662 4 Object Relationships 664 This section defines the object relationships between the Printer, 665 Job, and Subscription Objects. It does not define the 666 implementation. For an illustration of these relationships, see 667 Appendix E. 669 4.1 Printer and Per-Printer Subscription Objects 671 1.A Printer object can be associated with zero or more Per-Printer 672 Subscription Objects. 674 2.Each Per-Printer Subscription Object is associated with exactly 675 one Printer object. 677 4.2 Printer, Job and Per-Job Subscription Objects 679 1.A Printer object is associated with zero or more Job objects. 681 2.Each Job object is associated with exactly one Printer object. 683 3.A Job object is associated with zero or more Per-Job Subscription 684 Objects. 686 4.Each Per-Job Subscription Object is associated with exactly one 687 Job object. 689 5 Subscription Object 691 A Subscribing Client creates a Subscription Object with a 692 Subscription Creation Operation in order to indicate its interest in 693 certain Events. See section 11 for a description of these operations. 694 When an Event occurs, the Subscription Object specifies to the 695 Printer where to send Event Notifications, how to send them and what 696 to put in them. See section 9 for details on the contents of an Event 697 Notification. 699 Using the IPP Job Template attributes as a model (see [RFC2911] 700 section 4.2), the attributes of a Subscription Object are divided 701 into two categories: Subscription Template Attributes and 702 Subscription Description Attributes. 704 Subscription Template attributes are, in turn, like the Job Template 705 attributes, divided into 707 1.Subscription Object attributes that a client can supply in a 708 Subscription Creation Request and 710 2.their associated Printer Object attributes that specify 711 supported and default values for the Subscription Object 712 attributes 714 The remainder of this section specifies general rules for 715 Subscription Template Attributes and describes each attribute in a 716 Subscription Object. 718 5.1 Rules for Support of Subscription Template Attributes 720 Subscription Template Attributes are fundamental to the Notification 721 model described in this specification. The client supplies these 722 attributes in Subscription Creation Operations and the Printer uses 723 these attributes to populate a newly created Subscription Object. 725 Subscription Objects attributes that are Subscription Template 726 Attributes conform to the following rules: 728 1.Each attribute's name starts with the prefix string "notify-" 729 and this document calls such attributes "notify-xxx". 731 2.For each "notify-xxx" Subscription Object attribute defined in 732 column 1 of Table 1 in section 5.3, Table 1 specifies 733 corresponding Printer attributes: "notify-xxx-default", "notify- 734 xxx-supported", "yyy-supported" and "notify-max-xxx-supported" 735 defined in column 2 of Table 1. Note "xxx" stands for the same 736 string in each case and "yyy" stands for some other string. 738 3.If a Printer supports "notify-xxx" in column 1 of Table 1, then 739 the Printer MUST support all associated attributes specified in 740 column 2 of Table 1. For example, Table 1 shows that if the 741 Printer supports "notify-events", it MUST support "notify- 742 events-default", "notify-events-supported" and "notify-max- 743 events-supported". 745 4.If a Printer does not support "notify-xxx" in column 1 of Table 746 1, then the Printer MUST NOT support any associated "notify-yyy" 747 attributes specified in column 2 of Table 1. For example, Table 748 1 shows that if the Printer doesn't support "notify-events", it 749 MUST NOT support "notify-events-default", "notify-events- 750 supported" and "notify-max-events-supported". Note this rule 751 does not apply to attributes whose names do not start with the 752 string "notify-" and are thus defined in another object and used 753 by other attributes. 755 5.Most "notify-xxx" attributes have a corresponding "yyy- 756 supported" attribute that specifies the supported values for 757 "notify-xxx". Column 2 of Table 1 specifies the name of each 758 "yyy-supported" attribute. The naming rules of IPP/1.1 (see 759 [RFC2911]) are used when "yyy-supported" is "notify-xxx- 760 supported". 762 6.Some "notify-xxx" attributes have a corresponding "notify-xxx- 763 default" attribute that specifies the value for "notify-xxx" if 764 the client does not supply it. Column 2 of Table 1 specifies the 765 name of each "notify-xxx-default" attribute. The naming rules of 766 IPP/1.1 (see [RFC2911]) are used. 768 If a client wishes to present an end user with a list of supported 769 values from which to choose, the client SHOULD query the Printer for 770 its supported value attributes. The client SHOULD also query the 771 default value attributes. If the client then limits selectable 772 values to only those values that are supported, the client can 773 guarantee that the values supplied by the client in the create 774 request all fall within the set of supported values at the Printer. 775 When querying the Printer, the client MAY enumerate each attribute by 776 name in the Get-Printer-Attributes Request, or the client MAY just 777 supply the 'subscription-template' group name in order to get the 778 complete set of supported attributes (both supported and default 779 attributes - see section 11.2.3). 781 5.2 Rules for Processing Subscription Template Attributes 783 This section defines a detailed set of rules that a Printer follows 784 when it processes Subscription Template Attributes in a Subscription 785 Creation Request. These rules are similar to the rules for processing 786 Operation attributes in [RFC2911]. That is, the Printer may or may 787 not support an attribute and a client may or may not supply the 788 attribute. Some combinations of these cases are OK. Others return 789 warnings or errors, and perhaps a list of unsupported attributes. 791 A Printer MUST implement the following behavior for processing 792 Subscription Template Attributes in a Subscription Creation Request: 794 1.If a client supplies a "notify-xxx" attribute from column 1 of 795 Table 1 and the Printer supports it and its value, the Printer 796 MUST populate the attribute on the created Subscription Object. 798 2.If a client supplies a "notify-xxx" attribute from column 1 of 799 Table 1 and the Printer doesn't support it or its value, the 800 Printer MUST NOT populate the attribute on the created 801 Subscription Object with it. The Printer MUST do one of the 802 following: 804 a) If the value of the "notify-xxx" attribute is unsupported, the 805 Printer MUST return the attribute with its value in the 806 Subscription Attributes Group of the response. 808 b) If "notify-xxx" is an unsupported attribute, the Printer MUST 809 return the attribute in the Subscription Attributes Group of the 810 response with the 'unsupported' out-of-band value. 812 Note: The rules of this step are the same as for Unsupported 813 Attributes [RFC2911] section 3.1.7. except that the unsupported 814 attributes are returned in the Subscription Attributes Group 815 rather than the Unsupported Attributes Group because Subscription 816 Creation Operations can create more than one Subscription Object). 818 3.If a client is REQUIRED to supply a "notify-xxx" attribute from 819 column 1 of Table 1 and the Printer doesn't support the supplied 820 value, the Printer MUST NOT create a Subscription Object. The 821 rules for Unsupported Attributes in step #2 still apply. 823 4.If a client does not supply a "notify-xxx" attribute from column 1 824 of Table 1 and the attribute is REQUIRED for the client to supply, 825 the Printer MUST reject the Subscription Creation Operation 826 (including Job Creation operations) without creating a 827 Subscription Object, and MUST return in the response: 829 c) the status code 'client-error-bad-request' AND 831 d) no Subscription Attribute Groups. 833 5.If a client does not supply a "notify-xxx" attribute from column 1 834 of Table 1 that is OPTIONAL for the client to supply, and column 2 835 of Table 1 either: 837 a) specifies a "notify-xxx-default" attribute, the Printer MUST 838 behave as if the client had supplied the "notify-xxx-default" 839 attribute (see step #1) and populate the Subscription object 840 with the value of the "notify-xxx-default" attribute as part of 841 the Subscription Creation operation (unlike Job Template 842 attributes where the Printer does not populate the Job object 843 with defaults - see [RFC2911]) OR 845 b) does not specify a "notify-xxx-default" attribute, the Printer 846 MUST populate the "notify-xxx" attribute on the Subscription 847 Object according to the definition of the "notify-xxx" attribute 848 in a section 5.3. For some attributes, the "notify-xxx" is 849 populated with the value of some other attribute, and for 850 others, the "notify-xxx" is NOT populated on the Subscription 851 object at all. 853 6.A Printer MUST create a Subscription Object for each Subscription 854 Template Attributes group in a request unless the Printer: 856 a) encounters some attributes in a Subscription Template Attributes 857 Group that require the Printer not to create the Subscription 858 Object OR 860 b) would create a Per-Job Subscription Object when it doesn't have 861 space for another Per-Job Subscription Object OR 863 c) would create a Per-Printer Subscription Object when it doesn't 864 have space for another Per-Printer Subscription Object. 866 7.A response MUST contain one Subscription Attributes Group for each 867 Subscription Template Attributes Group in the request (and in the 868 same order) whether the Printer creates a Subscription Object from 869 the Subscription Template Attributes Group or not. However, the 870 attributes in each Subscription Attributes Group can be in any 871 order. 873 8.The Printer MUST populate each Subscription Attributes Group of 874 the response such that each contains: 876 a) the "notify-subscription-id" attribute (see section 5.4.1), if 877 and only if the Printer creates a Subscription Object. 879 b) the "notify-lease-duration" attribute (see section 5.3.7), if 880 and only if the Printer creates a Per-Printer Subscription 881 Object. The value of this attribute is the value of the 882 Subscription Object's "notify-lease-duration" attribute. This 883 value MAY be different from the client-supplied value (see 884 section 5.3.7). If a client supplies this attribute in the 885 creation of a Per-Job Subscription Object, it MUST appear in 886 this group with the out-of-band value 'unsupported' to indicate 887 that the Printer doesn't support it in this context. 889 c) all of the unsupported Subscription Template Attributes from 890 step #2. Note, they are not returned in the Unsupported 891 Attributes Group in order to separate the unsupported attributes 892 for each Subscription Object. 894 d) the "notify-status-code" attribute if the Printer does not 895 create the Subscription Object or if there are unsupported 896 attributes from step #2. The possible values of the "notify- 897 status-code" attribute are shown below (see section 17 for more 898 details). The Printer returns the first value in the list below 899 that describes the status. 901 'client-error-uri-scheme-not-supported': the Subscription 902 Object was not created because the scheme of the "notify- 903 recipient-uri" attribute is not supported. See section 17.1 904 for more details about this status code. See step #3 in 905 this section for the case that causes this error, and the 906 resulting step #6a) that causes the Printer not to create 907 the Subscription Object. 909 'client-error-attributes-or-values-not-supported': the 910 Subscription Object was not created because the method of 911 the "notify-pull-method" attribute is not supported. See 912 section 17.1 for more details about this status code. See 913 step #3 in this section for the case that causes this 914 error, and the resulting step #6a) that causes the Printer 915 not to create the Subscription Object. 917 'client-error-too-many-subscriptions': the Subscription 918 Object was not created because the Printer has no space for 919 additional Subscription Objects. The client SHOULD try 920 again later. See section 17.3 for more details about this 921 status code. See steps #6b) and #6c) in this section for 922 the cases that causes this error. 924 'successful-ok-too-many-events': the Subscription Object was 925 created without the "notify-events" values included in this 926 Subscription Attributes Group because the "notify-events" 927 attribute contains too many values. See section 17.4 for 928 more details about this status code. See step #2 in this 929 section and section 5.3.2 for the cases that cause this 930 status code. 932 'successful-ok-ignored-or-substituted-attributes' : the 933 Subscription Object was created but some supplied 934 Subscription Template Attributes are unsupported. These 935 unsupported attributes are also in the Subscription 936 Attributes Group. See section 17.5 for more details about 937 this status code. See step #2 in this section for the cases 938 that cause this status code. 940 9.The Printer MUST validate all Subscription Template Attributes and 941 MUST return all unsupported attributes and values in the 942 corresponding Subscription Attributes Group of the response (see 943 step #2) unless it determines that it could not create additional 944 Subscription Objects because of condition #6b) or condition #6c). 945 Then, the Printer NEED NOT validate these additional Subscription 946 Template Attributes and the client MUST NOT expect to find 947 unsupported attributes from step #2 in such additional 948 Subscription Attribute Groups. 950 5.3 Subscription Template Attributes 952 This section contains the Subscription Template Attributes defined 953 for the Subscription and Printer objects. 955 Table 1 below shows the Subscription Template Attributes and has two 956 columns: 958 - Attribute in Subscription Object: the name and attribute syntax 959 of each Subscription Object Attribute that is a Subscription 960 Template Attribute 962 - Default and Supported Printer Attributes: the default attribute 963 and supported Printer attributes that are associated with the 964 attribute in column 1. 966 The "notify-recipient-uri" attribute is for use with Push Delivery 967 Methods. The "notify-pull-method" attribute is for use with Pull 968 Delivery Methods. 970 For Push Delivery Methods, a Printer MUST support all attributes in 971 Table 1 below except for "notify-pull-method" and "notify-attributes" 972 (and "notify-pull-method-supported" and "notify-attributes- 973 supported"). For Pull Delivery Methods, a Printer MUST support all 974 attributes in Table 1 below except for "notify-recipient-uri" and 975 "notify-attributes" (and "notify-schemes-supported" and "notify- 976 attributes-supported"). If a Printer supports both Push and Pull 977 Delivery Methods, then it MUST support both "notify-recipient-uri" 978 and "notify-pull-method" attributes. 980 For Pull Delivery Methods, a client MUST supply "notify-recipient- 981 uri" and MAY omit any of the rest of the attributes in column 1 of 982 Table 1 in a Subscription Creation Request. For Push Delivery 983 Methods, a client MUST supply "notify-pull-method" and MAY omit any 984 of the rest of the attributes in column 1 of Table 1 in a 985 Subscription Creation Request. A client MUST NOT supply both 986 "notify-recipient-uri" and "notify-pull-method" attributes in the 987 same Subscription Creation Request. 989 Note: The Default and Supported Printer attributes listed in column 990 2 of Table 1 do not have separate sections in this specification 991 defining their semantics. Instead, the section for the corresponding 992 Subscription Object attribute (column 1 of Table 1) contains the 993 semantics of these Printer attributes. This approach follows the 994 precedence of the Job Template attributes in section 4.2 of [RFC2911] 995 where the corresponding "xxx-default" and "xxx-supported" Printer 996 attributes are defined in the same section as the "xxx" Job 997 attribute. 999 Table 1 - Subscription Template Attributes 1001 Attribute in Subscription Default and Supported Printer 1002 Object Attributes 1004 notify-recipient-uri (uri) * notify-schemes-supported (1setOf 1005 uriScheme) 1007 notify-pull-method (type2 notify-pull-method-supported (1setOf 1008 keyword) ** type2 keyword) 1010 notify-events (1setOf type2 notify-events-default (1setOf type2 1011 keyword) keyword) 1012 notify-events-supported (1setOf type2 1013 keyword) 1014 notify-max-events-supported 1015 (integer(2:MAX)) 1017 notify-attributes (1setOf notify-attributes-supported (1setOf 1018 type2 keyword) type2 keyword) 1020 notify-user-data 1021 (octetString(63)) 1023 notify-charset (charset) charset-supported (1setOf charset) 1025 notify-natural-language generated-natural-language-supported 1026 (naturalLanguage) (1setOf naturalLanguage) 1028 notify-lease-duration notify-lease-duration-default 1029 (integer(0:MAX)) (integer(0:67108863)) 1030 notify-lease-duration-supported 1031 (1setOf (integer(0: 67108863) | 1032 rangeOfInteger(0:67108863))) 1034 notify-time-interval 1035 (integer(0:MAX)) 1037 * "notify-recipient-uri" is for Push Delivery Methods only. 1038 ** "notify-pull-method" is for Pull Delivery Methods only. 1040 5.3.1 notify-recipient-uri (uri) OR notify-pull-method (type2 keyword) 1042 The "notify-recipient-uri" attribute MUST be used for Push Delivery 1043 Methods and the "notify-pull-method" attribute MUST be used for Pull 1044 Delivery Methods. 1046 5.3.1.1 notify-recipient-uri (uri) 1048 This attribute's value is a URL, which is a special case of a URI. 1049 Its value consists of a scheme and an address. The address specifies 1050 the Notification Recipient and the scheme specifies the Push Delivery 1051 Method for each Event Notification associated with this Subscription 1052 Object. 1054 If a Printer supports any Push Delivery Methods, a Printer MUST 1055 support this attribute and return the value as supplied by the client 1056 (no case conversion or other canonicalization) in any operation 1057 response that includes this attribute. 1059 For a Push Delivery Method, a client MUST supply this attribute in a 1060 Subscription Creation Operation. Thus there is no need for a default 1061 Printer attribute. 1063 The URI scheme of the value of this attribute on a Subscription 1064 object MUST be a value of the "notify-schemes-supported (1setOf 1065 uriScheme)" Printer attribute. Note: According to [RFC2396] the ":" 1066 terminates the scheme and so is not part of the scheme. Therefore, 1067 values of the "notify-schemes-supported" Printer attribute do not 1068 include the ":" character. 1070 If the client supplies an unsupported scheme in the value of this 1071 attribute, then the Printer MUST NOT create the Subscription Object 1072 and MUST return the "notify-status-code" attribute with the 'client- 1073 error-uri-scheme-not-supported' value in the Subscription Attributes 1074 Group in the response. 1076 The Printer MUST treat the address part of this attribute as opaque. 1078 5.3.1.2 notify-pull-method (type2 keyword) 1080 This attribute's value is a type2 keyword indicating which Pull 1081 Delivery Method is to be used. 1083 If a Printer supports any Pull Delivery Methods, a Printer MUST 1084 support this attribute and return the value as supplied by the client 1085 in any operation response that includes this attribute. 1087 For a Pull Delivery Method, a client MUST supply this attribute in a 1088 Subscription Creation Operation. Thus there is no need for a default 1089 Printer attribute. 1091 The keyword value of this attribute on a Subscription object MUST be 1092 a value of the "notify-pull-method-supported (1setOf type2 keyword)" 1093 Printer attribute. 1095 If the client supplies an unsupported method in the value of this 1096 attribute, then the Printer MUST NOT create the Subscription Object 1097 and MUST return the "notify-status-code" attribute with the 'client- 1098 error-attributes-or-values-not-supported' value in the Subscription 1099 Attributes Group in the response. 1101 5.3.2 notify-events (1setOf type2 keyword) 1103 This attribute contains a set of Subscribed Events. When an Event 1104 occurs and it "matches" a value of this attribute, the Printer sends 1105 an Event Notification using information in the Subscription Object. 1106 The details of "matching" are described subsection 5.3.2.2. 1108 A Printer MUST support this attribute. 1110 A client MAY supply this attribute in a Subscription Creation 1111 Operation. If the client does not supply this attribute in 1112 Subscription Creation Operation, the Printer MUST populate this 1113 attribute on the Subscription Object with its "notify-events-default" 1114 attribute value. 1116 Each keyword value of this attribute on a Subscription Object MUST be 1117 a value of the "notify-events-supported (1setOf type2 keyword)" 1118 Printer attribute. 1120 The number of values of this attribute MUST NOT exceed the value of 1121 the "notify-max-events-supported" attribute. A Printer MUST support 1122 at least 2 values per Subscription Object. If the number of values 1123 supplied by a client in a Subscription Creation Operation exceeds the 1124 value of this attribute, the Printer MUST treat extra values as 1125 unsupported values and MUST use the value of 'successful-ok-too-many- 1126 events' for the "notify-status-code" attribute in the Subscription 1127 Attributes Group of the response. 1129 5.3.2.1 Standard Values for Subscribed Events 1131 Each value of this attribute is a keyword and it specifies a 1132 Subscribed Event that represents certain changes. Some keywords 1133 represent a subset of changes of another keyword, e.g., 'job- 1134 completed' is an Event value which is a sub-value of 'job-state- 1135 change'. See section 5.3.2.2 for the case where this attribute 1136 contains both a value and a sub-value. 1138 The values in this section are divided into three categories: No 1139 Events, Job Events and Printer Events. 1141 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1142 support the Events indicated as "OPTIONAL". 1144 5.3.2.1.1 No Events 1146 The standard and only keyword value for No Events is: 1148 'none': REQUIRED - no Event Notifications for any Events. As the 1149 sole value of "notify-events-supported", this value means that the 1150 Printer does not support the sending of Event Notifications. As 1151 the sole value of "notify-events-default", this value means that a 1152 client MUST specify the "notify-events" attribute in order for a 1153 Subscription Creation Operation to succeed. If the Printer 1154 receives this value as the sole value of a Subscription Creation 1155 Operation, it does not create a Subscription Object. If a Printer 1156 receives this value with other values of a Subscription Creation 1157 Operation, the Printer MUST treat this value as an unsupported 1158 value. 1160 5.3.2.1.2 Subscribed Printer Events 1162 The standard keyword values for Subscribed Printer Events are: 1164 'printer-state-changed': REQUIRED - the Printer changed state from 1165 any state to any other state. Specifically, the value of the 1166 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1167 accepting-jobs" attributes changed. 1169 This Subscribed Event value has the following sub-values: 1170 'printer-restarted' and 'printer-shutdown'. A client can listen 1171 for any of these sub-values if it doesn't want to listen to all 1172 printer-state changes: 1174 'printer-restarted': OPTIONAL - when the printer is powered 1175 up . 1177 'printer-shutdown': OPTIONAL - when the device is being 1178 powered down . 1180 'printer-stopped: REQUIRED - when the printer stops printing, 1181 i.e. the value of the "printer-state" Printer attribute 1182 becomes 'stopped'. 1184 'printer-config-changed': OPTIONAL - when the configuration of a 1185 Printer has changed, i.e., the value of the "printer-message-from- 1186 operator" or any "configuration" Printer attribute has changed. A 1187 "configuration" Printer attribute is an attribute which can change 1188 value because of some human interaction either direct or indirect, 1189 and which is not covered by one of the other Events in this 1190 section. Examples of "configuration" Printer attributes are any of 1191 the Job Template attributes, such as "xxx-supported", "xxx-ready" 1192 and "xxx-default". Often, such a change is the result of a client 1193 performing a Set-Printer-Attributes operation (see [ipp-set]) on 1194 the Printer. The client has to perform a Get-Printer-Attributes to 1195 find out the new values of these changed attributes. This Event 1196 is useful for GUI clients and drivers to update the available 1197 printer capabilities to the user. 1199 This Event value has the following sub-values: 'printer-media- 1200 changed' and 'printer-finishings-changed'. A client can listen for 1201 any of these sub-values if it doesn't want to listen to all 1202 printer-configuration changes: 1204 'printer-media-changed': OPTIONAL - when the media loaded on 1205 a printer has been changed, i.e., the "media-ready" 1206 attribute has changed. This Event includes two cases: an 1207 input tray that goes empty and an input tray that receives 1208 additional media of the same type or of a different type. 1209 The client must check the "media-ready" Printer attribute 1210 (see [RFC2911] section 4.2.11) separately to find out what 1211 changed. 1213 'printer-finishings-changed': OPTIONAL - when the finisher on 1214 a printer has been changed, i.e., the "finishings-ready" 1215 attribute has changed. This Event includes two cases: a 1216 finisher that goes empty and a finisher that is refilled 1217 (even if it is not full). The client must check the 1218 "finishings-ready" Printer attribute separately to find out 1219 what changed. 1221 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1222 Printer's queue has changed, so that an application that is 1223 monitoring the queue can perform a Get-Jobs operation to determine 1224 the new order. This Event does not include when a job enters the 1225 queue (the 'job-created' Event covers that) and does not include 1226 when a job leaves the queue (the 'job-completed' Event covers 1227 that). 1229 5.3.2.1.3 Subscribed Job Events 1231 The standard keyword values for Subscribed Job Events are: 1233 'job-state-changed': REQUIRED - the job has changed from any state 1234 to any other state. Specifically, the Printer sends this Event 1235 whenever the value of the "job-state" attribute or "job-state- 1236 reasons" attribute changes. When a Job is removed from the Job 1237 Retention or Job History phases (see [RFC2911] section 4.3.7.1), 1238 no Event is generated. 1240 This Event value has the following sub-values: 'job-created', 1241 'job-completed' and 'job-stopped'. A client can listen for any of 1242 these sub-values if it doesn't want to listen to all 'job-state 1243 changes'. 1245 'job-created': REQUIRED - the Printer has accepted a Job 1246 Creation operation, a Restart-Job operation [RFC2911], or 1247 any job operation that creates a Job object from an 1248 existing Job object. The Printer sets the job's "time-at- 1249 creation" attribute value (see [RFC2911] section 4.3.14.1). 1250 The Printer puts the job in the 'pending', 'pending-held' 1251 or 'processing' states. 1253 'job-completed': REQUIRED - the job has reached one of the 1254 completed states, i.e., the value of the job's "job-state" 1255 attribute has changed to: 'completed', 'aborted', or 1256 'canceled'. The Job's "time-at-completed" and "date-time- 1257 at-completed" (if supported) attributes are set (see 1258 [RFC2911] section 4.3.14). When a Job completes, a 1259 Notification Recipient MAY query the Job using the Get-Job- 1260 Attributes operation. To allow such a query, the Printer 1261 retains the Job in the Job Retention and/or the Job History 1262 phases (see [RFC2911] section 4.3.7.1) for a suitable 1263 amount of time that depends on implementation and the 1264 Delivery Methods supported. The Printer also sends this 1265 Event when a Job is removed with the Purge-Job operation 1266 (see [RFC2911] section 3.2.9). In this case, the Event 1267 Notification MUST report the 'job-state' as 'canceled' and 1268 the Job object is no longer present for query. 1270 'job-stopped: OPTIONAL - when the job stops printing, i.e. 1271 the value of the "job-state" Job attribute becomes 1272 'processing-stopped'. 1274 'job-config-changed': OPTIONAL - when the configuration of a job has 1275 changed, i.e., the value of the "job-message-from-operator" or any 1276 of the "configuration" Job attributes have changed. A 1277 "configuration" Job attribute is an attribute that can change 1278 value because of some human interaction either direct or indirect. 1279 Examples of "configuration" Job attributes are any of the job 1280 template attributes and the "job-name" attribute. Often, such a 1281 change is the result of the user or the Operator performing a Set- 1282 Job-Attributes operation (see [ipp-set]) on the Job object. The 1283 client performs a Get-Job-Attributes to find out the new values of 1284 the changed attributes. This Event is useful for GUI clients and 1285 drivers to update the job information to the user. 1287 'job-progress': OPTIONAL - when the Printer has completed Printing a 1288 sheet. See the separate [ipp-prog] specification for additional 1289 attributes that a Printer MAY send in an Event Notification caused 1290 by this Event. The "notify-time-interval" attribute affects this 1291 Event by causing the Printer NOT to send an Event Notification 1292 every time a 'job-progress' Events occurs. See section 5.3.8 for 1293 full details. 1295 5.3.2.2 Rules for Matching of Subscribed Events 1297 When an Event occurs, the Printer MUST find each Subscription object 1298 whose "notify-events" attribute "matches" the Event. The rules for 1299 "matching" of Subscribed Events are described separately for Printer 1300 Events and for Job Events. This section also describes some special 1301 cases. 1303 5.3.2.2.1 Rules for Matching of Printer Events 1305 Suppose that the Printer causes Printer Event E to occur. For each 1306 Per-Job or Per-Printer Subscription S in the Printer, if E equals a 1307 value of this attribute in S or E is a sub-value of a value of this 1308 attribute in S, the Printer MUST generate an Event Notification. 1310 Consider the example. There are three Subscription Objects each with 1311 the Subscribed Printer Event 'printer-state-changed'. Subscription 1312 Object A is a Per-Printer Subscription Object. Subscription Object B 1313 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1314 is a Per-Job Subscription Object for Job 2. When the Printer enters 1315 the 'stopped' state, the Printer sends an Event Notification to the 1316 Notification Recipients of Subscription Objects A, B, and C because 1317 this is a Printer Event. Note if Job 1 has already completed, the 1318 Printer would not send an Event Notification for its Subscription 1319 Object, even if Job 1 is retained in the Job Retention and/or the Job 1320 History phases (see [RFC2911] section 4.3.7.1). 1322 5.3.2.2.2 Rules for Matching of Job Events 1324 Suppose that Job J causes Job Event E to occur. 1326 1.For each Per-Printer Subscription S in the Printer, if E equals 1327 a value of this attribute in S or E is a sub-value of a value of 1328 this attribute in S, the Printer MUST generate an Event 1329 Notification. 1331 2.For each Per-Job Subscription S associated with Job J, if E 1332 equals a value of this attribute in S or E is a sub-value of a 1333 value of this attribute in S, the Printer MUST generate an Event 1334 Notification. 1336 3.For each Per-Job Subscription S that is NOT associated Job J, if 1337 E equals a value of this attribute in S or E is a sub-value of a 1338 value of this attribute in, the Printer MUST NOT generate an 1339 Event Notification from S. 1341 Consider the example: There are three Subscription Objects listening 1342 for the Job Event 'job-completed'. Subscription Object A is a Per- 1343 Printer Subscription Object. Subscription Object B is a Per-Job 1344 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1345 Subscription Object for Job 2. In addition, Per-Printer Subscription 1346 Object D is listening for the Job Event 'job-state-changed'. When Job 1347 1 completes, the Printer sends an Event Notification to the 1348 Notification Recipient of Subscription Object A (because it is Per- 1349 Printer) and Subscription Object B because it is a Per-Job 1350 Subscription Object associated with the Job generating the Event. 1351 The Printer also sends an Event Notification to the Notification 1352 Recipient of Subscription Object D because 'job-completed' is a sub- 1353 value of 'job-state-changed' - the value that Subscription Object D 1354 is listening for. The Printer does not send an Event Notification to 1355 the Notification Recipients of Subscription Object C because it is a 1356 Per-Job Subscription Object associated with some Job other than the 1357 Job generating the Event. 1359 5.3.2.2.3 Special Cases for Matching Rules 1361 This section contains rule for special cases. 1363 If an Event matches Subscribed Events in two different Subscription 1364 Objects and the Printer would send two identical Event Notifications 1365 (except for the "notify-subscription-id" attribute) to the same 1366 Notification Recipient using the same Delivery Method, the Printer 1367 MUST send both Event Notifications. That is, the Printer MUST NOT try 1368 to consolidate seemingly identical Event Notifications that occur in 1369 separate Subscription objects. Incidentally, the Printer MUST NOT 1370 reject Subscription Creation Operations that would create this 1371 scenario. 1373 If an Event matches two values of this "notify-events" attribute in a 1374 single Subscription object (e.g., a value and its sub-value), a 1375 Printer MAY send one Event Notification for each matched value in the 1376 Subscription Object or it MAY send only one Event Notification per 1377 Subscription Object. The rules in sections 5.3.2.2.1 and 5.3.2.2.2 1378 are purposefully ambiguous about the number of Event Notification 1379 sent when Event E matches two or more values in a Subscription 1380 Object. 1382 Consider the example: There are two Per-Printer Subscription Objects 1383 when a Job completes. Subscription Object A has the Subscribed Job 1384 Event 'job-state-changed'. Subscription Object B has the Subscribed 1385 Job Events 'job-state-changed' and 'job-completed'. The Printer sends 1386 an Event Notification to the Notification Recipient of Subscription 1387 Object A with the value of 'job-state-changed' for the "notify- 1388 subscribing-event" attribute. The Printer sends either one or two 1389 Event Notifications to the Notification Recipient of Subscription 1390 Object B, depending on implementation. If it sends two Event 1391 Notifications, one has the value of 'job-state-changed' for the 1392 "notify-subscribing-event" attribute, and the other has the value of 1393 'job-completed' for the "notify-subscribing-event" attribute. If it 1394 sends one Event Notification, it has the value of either 'job-state- 1395 changed' or 'job-completed' for the "notify-subscribing-event" 1396 attribute, depending on implementation. The algorithm for choosing 1397 such a value is implementation dependent. 1399 5.3.3 notify-attributes (1setOf type2 keyword) 1401 This attribute contains a set of attribute names. When a Printer 1402 sends a Machine Consumable Event Notification, it includes a fixed 1403 set of attributes (see section 9.1). If this attribute is present 1404 and the Event Notification is Machine Consumable, the Printer also 1405 includes the attributes specified by this attribute. 1407 A Printer MAY support this attribute. 1409 A client MAY supply this attribute in a Subscription Creation 1410 Operation. If the client does not supply this attribute in 1411 Subscription Creation Operation or the Printer does not support this 1412 attribute, the Subscription Object either (1) MAY contain the 1413 "notify-attributes" attribute with a 'none' value or (2) NEED NOT 1414 contain the attribute at all. There is no "notify-attributes- 1415 default" Printer attribute. 1417 Each keyword value of this attribute on a Subscription Object MUST be 1418 a value of the "notify-attributes-supported (1setOf type2 keyword)" 1419 Printer attribute. The "notify-attributes-supported" MAY contain any 1420 Printer attribute, Job attribute or Subscription Object attribute 1421 that the Printer supports in an Event Notification. It MUST NOT 1422 contain any of the attributes in Section 9.1 that a Printer 1423 automatically puts in an Event Notification; it would be redundant. 1424 If a client supplies an attribute in Section 9.1, the Printer MUST 1425 treat it as an unsupported attribute value of the "notify-attributes" 1426 attribute. 1428 The following rules apply to each keyword value N of the "notify- 1429 attributes" attribute: If the value N names: 1431 a)a Subscription attribute, the Printer MUST use the attribute N in 1432 the Subscription Object that is being used to generate the Event 1433 Notification. 1435 b)a Job attribute and the Printer is generating an Event 1436 Notification from a Per-Job Subscription Object S, the Printer 1437 MUST use the attribute N in the Job object associated with S. 1439 c)a Job attribute and the Printer is generating an Event 1440 Notification from a Per-Printer Subscription Object and the Event 1441 is: 1443 ? a Job Event, the Printer MUST use the attribute N in the Job 1444 object that caused the Event. 1446 ? a Printer Event, the Printer MUST use the attribute N in the 1447 active Job. 1449 If a Printer supports this attribute and a Subscription Object 1450 contains this attribute and the Delivery Method generates a Machine 1451 Consumable Event Notification, the Printer MUST include in each Event 1452 Notification: 1454 a)the attributes specified in section 9.1 and 1456 b)each attribute named by this attribute. 1458 The Printer MUST NOT use this attribute to generate a Human 1459 Consumable Event Notification. 1461 5.3.4 notify-user-data (octetString(63)) 1463 This attribute contains opaque data that some Delivery Methods 1464 include in each Machine Consumable Event Notification. The opaque 1465 data might contain, for example: 1467 - the identity of the Subscriber 1469 - a path or index to some Subscriber information 1471 - a key that identifies to the Notification Recipient the 1472 ultimate recipient of the Event Notification 1474 - the id for a Notification Recipient that had previously 1475 registered with an Instant Messaging Service 1477 A Printer MUST support this attribute. 1479 A client MAY supply this attribute in a Subscription Creation 1480 Operation. If the client does not supply this attribute in the 1481 Subscription Creation Operation, the Subscription Object either (1) 1482 MAY contain the "notify-user-data" attribute with a zero length value 1483 or (2) NEED NOT contain the attribute at all. There is no "notify- 1484 user-data-default" Printer attribute. 1486 There is no "notify-user-data-supported" Printer attribute. Rather, 1487 any octetString whose length does not exceed 63 octets is a supported 1488 value. If the length exceeds 63 octets, the Printer MUST treat it as 1489 an unsupported value. 1491 5.3.5 notify-charset (charset) 1493 This attribute specifies the charset to be used in the Event 1494 Notification content sent to the Notification Recipient, whether the 1495 Event Notification content is Machine Consumable or Human Consumable. 1497 A Printer MUST support this attribute. 1499 A client MAY supply this attribute in a Subscription Creation 1500 Operation. If the client does not supply this attribute in 1501 Subscription Creation Operation or supplies an unsupported value, the 1502 Printer MUST populate this attribute in the Subscription Object with 1503 the value of the "attributes-charset" operation attribute, which is a 1504 REQUIRED attribute in all IPP requests (see [RFC2911]). If the value 1505 of the "attributes-charset" attribute is unsupported, the Printer 1506 MUST populate this attribute in the Subscription Object with the 1507 value of the Printer's "charset-configured" attribute. There is no 1508 "notify-charset-default" Printer attribute. 1510 The value of this attribute on a Subscription Object MUST be a value 1511 of the "charset-supported (1setOf charset)" Printer attribute. 1513 5.3.6 notify-natural-language (naturalLanguage) 1515 This attribute specifies the natural language to be used in any human 1516 consumable text in the Event Notification content sent to the 1517 Notification Recipient, whether the Event Notification content is 1518 Machine Consumable or Human Consumable. 1520 A Printer MUST support this attribute. 1522 A client MAY supply this attribute in a Subscription Creation 1523 Operation. If the client does not supply this attribute in 1524 Subscription Creation Operation or supplies an unsupported value, the 1525 Printer MUST populate this attribute in the Subscription Object with 1526 the value of the "attributes-natural-language" operation attribute, 1527 which is a REQUIRED attribute in all IPP requests (see [RFC2911]). If 1528 the value of the "attributes-natural-language" attribute is 1529 unsupported, the Printer MUST populate this attribute in the 1530 Subscription Object with the value of the Printer's "natural- 1531 language-configured" attribute. There is no "notify-natural-language- 1532 default" Printer attribute. 1534 The value of this attribute on a Subscription Object MUST be a value 1535 of the "generated-natural-language-supported (1setOf type2 1536 naturalLanguage)" Printer attribute. 1538 5.3.7 notify-lease-duration (integer(0:67108863)) 1540 This attribute specifies the duration of the lease (in seconds) 1541 associated with the Per-Printer Subscription Object at the time the 1542 Subscription Object was created or the lease was renewed. The 1543 duration of the lease is infinite if the value is 0, i.e., the lease 1544 never expires. See section 5.4.3 on "notify-lease-expiration-time 1545 (integer(0:MAX))" for more details. 1547 This attribute is not present on a Per-Job Subscription Object 1548 because the Subscription Object lasts exactly as long as the 1549 associated Job object. See discussion of the 'job-completed' event 1550 in section 5.3.2.1.3 about retention of the Job object after 1551 completion. 1553 A Printer MUST support this attribute. 1555 For a Subscription Object Creation operation of a Per-Job 1556 Subscription Object, the client MUST NOT supply this attribute. If 1557 the client does supply this attribute, the Printer MUST treat it as 1558 an unsupported attribute. 1560 For a Subscription Creation Operation of a Per-Printer Subscription 1561 Object or a Renew-Subscription operation, a client MAY supply this 1562 attribute. If the client does not supply this attribute, the Printer 1563 MUST populate this attribute with its "notify-lease-duration-default" 1564 (0:67108863) attribute value. If the client supplies this attribute 1565 with an unsupported value, the Printer MUST populate this attribute 1566 with a supported value, and this value SHOULD be as close as possible 1567 to the value requested by the client. Note: this rule implies that a 1568 Printer doesn't assign the value of 0 (infinite) unless the client 1569 requests it. 1571 After the Printer has populated this attribute with a supported 1572 value, the value represents the "granted duration" of the lease in 1573 seconds and the Printer sets the value of the Subscription Object's 1574 "notify-lease-expiration-time" attribute as specified in section 1575 5.4.3. 1577 The value of this attribute on a Subscription Object MUST be a value 1578 of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) 1579 | rangeOfInteger(0:67108863))) Printer attribute. 1581 A Printer MAY require authentication in order to return the value of 1582 0 (the lease never expires) as one of the values of "notify-lease- 1583 duration-supported", and to allow 0 as a value of the "notify-lease- 1584 duration" attribute. 1586 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1587 1 and is about 2 years in seconds. The value is considerably less 1588 than MAX so that there is virtually no chance of an overflow when it 1589 is added to "printer-up-time" to produce "notify-lease-expiration- 1590 time". 1592 5.3.8 notify-time-interval (integer(0:MAX)) 1594 The 'job-progress' Event occurs each time that a Printer completes a 1595 sheet. Some Notification Recipients do not want to receive an Event 1596 Notification every time this Event occurs. This attribute allows a 1597 Subscribing Client to request how often it wants to receive Event 1598 Notifications for 'job-progress' Events. The value of this attribute 1599 MAY be any nonnegative integer (0,MAX) indicating the minimum number 1600 of seconds between 'job-progress' Event Notifications. 1602 The Printer MUST support this attribute if and only if the Printer 1603 supports the 'job-progress' Event. 1605 A client MAY supply this attribute in a Subscription Creation 1606 Operation. If the client does not supply this attribute in the 1607 Subscription Creation Operation, the Subscription Object either (1) 1608 MAY contain the "notify-time-interval" attribute with a '0' value or 1609 (2) NEED NOT contain this attribute at all. There is no "notify- 1610 time-interval-default" Printer attribute. 1612 There is no "notify-time-interval-supported" Printer attribute. 1614 If the 'job-progress' Event occurs and a Subscription Object contains 1615 the 'job-progress' Event as a value of the 'notify-events' attribute, 1616 there are two cases to consider: 1618 1.This attribute is not present on the Subscription Object or has 1619 the value of 0. The Printer MUST generate and send an Event 1620 Notification (as is the case with other Events). 1622 2.This attribute is present with a nonzero value of N: 1624 a)If the Printer has not sent an Event Notification for the 'job- 1625 progress' Event for the associated Subscription Object within 1626 the past N seconds, the Printer MUST send an Event Notification 1627 for the Event that just occurred. Note when the Printer 1628 completes the first page of a Job, this rule implies that the 1629 Printer sends an Event Notification for a Per-Job Subscription 1630 Object. 1632 b)Otherwise, the Printer MUST NOT generate or send an Event 1633 Notification for the associated Subscription Object. The Printer 1634 MUST NOT increase the value of the "notify-sequence-number" 1635 Subscription Object attribute (i.e., the sequence of values of 1636 the "notify-sequence-number" attribute counts the Event 1637 Notifications that the Printer sent and not the Events that do 1638 not cause an Event Notification to be sent). 1640 It is RECOMMENDED that a Subscribing Client use this attribute when 1641 it subscribes to the 'job-progress' Event, and that the value be 1642 sufficiently large to limit the frequency with which the Printer 1643 sends Event Notifications requests. 1645 This attribute MUST NOT effect any Events other than 'job-progress'. 1647 5.4 Subscription Description Attributes 1649 Subscription Description Attributes are those attributes that a 1650 Printer adds to a Subscription Object at the time of its creation. 1652 A Printer MUST support all attributes in this Table 2. 1654 A client MUST NOT supply the attributes in Table 2 in a Subscription 1655 Template Attributes Group of a Subscription Creation Operation. If 1656 the client supplies them, the Printer MUST NOT set them and MUST 1657 treat them as unsupported attributes. There are no corresponding 1658 default or supported attributes. 1660 Table 2 - Subscription Description Attributes 1662 Subscription Object attributes: 1664 notify-subscription-id (integer(1:MAX)) 1666 notify-sequence-number (integer(0:MAX)) 1668 notify-lease-expiration-time (integer(0:MAX)) 1670 notify-printer-up-time (integer(1:MAX)) 1672 notify-printer-uri (uri) 1674 notify-job-id (integer(1:MAX)) 1676 notify-subscriber-user-name (name(MAX)) 1678 5.4.1 notify-subscription-id (integer (1:MAX)) 1680 This attribute identifies a Subscription Object instance with a 1681 number that is unique within the context of the Printer. The Printer 1682 generates this value at the time it creates the Subscription Object. 1684 A Printer MUST support this attribute. 1686 The Printer MAY assign the value of this attribute sequentially as it 1687 creates Subscription Objects. However, if there is no security on 1688 Subscription objects, sequential assignment exposes the system to a 1689 passive traffic monitoring threat. 1691 The Printer SHOULD avoid re-using recent values of this attribute 1692 during continuous operation of the Printer as well as across power 1693 cycles. Then a Subscribing Client is unlikely to find that a stale 1694 reference accesses a new Subscription Object. 1696 The 0 value is not permitted in order to allow for compatibility with 1697 "job-id" and with SNMP index values, which also cannot be 0. 1699 5.4.2 notify-sequence-number (integer (0:MAX)) 1701 The value of this attribute indicates the number of times that the 1702 Printer has generated and attempted to send an Event Notification for 1703 this Subscription object. When an Event Notification contains this 1704 attribute, the Notification Recipient can determine whether it missed 1705 some Event Notifications (i.e., numbers skipped) or received 1706 duplicates (i.e., same number twice). 1708 A Printer MUST support this attribute. 1710 When the Printer creates a Subscription Object, it MUST set the value 1711 of this attribute to 0. This value indicates that the Printer has not 1712 sent any Event Notifications for this Subscription Object. 1714 Each time the Printer sends a newly generated Event Notification, it 1715 MUST increase the value of this attribute by 1. For some Delivery 1716 Methods, the Printer MUST include this attribute in each Event 1717 Notification, and the value MUST be the value after it is increased 1718 by 1. That is, the value of this attribute in the first Event 1719 Notification after Subscription object creation MUST be 1, the second 1720 MUST be 2, etc. If a Delivery Method is defined such that the 1721 Notification Recipient returns a response, the Printer can re-try 1722 sending an Event Notification a certain number of times with the same 1723 sequence number when the Notification Recipient fails to return a 1724 response. 1726 If a Subscription Object lasts long enough to reach the value of MAX, 1727 its next value MUST be 0, i.e., it wraps. 1729 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1731 This attribute specifies the time in the future when the lease on the 1732 Per-Printer Subscription Object will expire, i.e. the "printer-up- 1733 time" value at which the lease will expire. If the value is 0, the 1734 lease never expires. 1736 A Printer MUST support this attribute. 1738 When the Printer creates a Per-Job Subscription Object, this 1739 attribute MUST NOT be present - the Subscription Object lasts exactly 1740 as long as the associated Job object. See also the discussion of the 1741 'job-completed' event in section 5.3.2.1.3 about retention of the Job 1742 object after completion so that a Notification Recipient can query 1743 the Job object after receiving the 'job-completed' Event 1744 Notification. 1746 When the Printer creates a Per-Printer Subscription Object, it 1747 populates this attribute with a value that is the sum of the values 1748 of the Printer's "printer-up-time" attribute and the Subscription 1749 Object's "notify-lease-duration" attribute with the following 1750 exception. If the value of the Subscription Object's "notify-lease- 1751 duration" attribute is 0 (i.e., no expiration time), then the value 1752 of this attribute MUST be set to 0 (i.e., no expiration time). 1754 When the Printer powers up, it MUST set the value of this attribute 1755 in each persistent Subscription Object using the algorithm in the 1756 previous paragraph. 1758 When the "printer-up-time" equals the value of this attribute, the 1759 Printer MUST delete the Subscription Object. A client can extend a 1760 lease of a Per-Printer Subscription Object with the Renew- 1761 Subscription operation (see section 11.2.6). 1763 Note: In order to compute the number of seconds remaining in a lease 1764 for a Per-Printer Subscription Object, a client can subtract the 1765 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1766 from the Subscription's "notify-lease-expiration-time" attribute. 1768 5.4.4 notify-printer-up-time (integer(1:MAX)) 1770 This attribute is an alias for the Printer's "printer-up-time" 1771 attribute " (see [RFC2911] section 4.4.29). In other words, when 1772 this attribute is queried with the Get-Subscriptions or Get- 1773 Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), 1774 the value returned is the current value of the Printer's "printer-up- 1775 time" attribute, rather than the time at which the Subscription 1776 Object was created. 1778 A Printer MUST support this attribute. 1780 When the Printer creates a Per-Job Subscription Object, this 1781 attribute MUST NOT be present. When the Printer creates a Per-Printer 1782 Subscription Object, this attribute MUST be present. 1784 Note: this attribute exists in a Per-Printer Subscription Object so 1785 that a client using the Get-Subscription-Attributes or Get- 1786 Subscription operations can convert the Per-Printer Subscription's 1787 "notify-lease-expiration-time" attribute to wall clock time with one 1788 request. If the value of the "notify-lease-expiration-time" attribute 1789 is not 0 (i.e., no expiration time), then the difference between the 1790 "notify-lease-expiration-time" attribute and the "notify-printer-up- 1791 time" is the remaining number of seconds on the lease from the 1792 current time. 1794 5.4.5 notify-printer-uri (uri) 1796 This attribute identifies the Printer object that created this 1797 Subscription Object. 1799 A Printer MUST support this attribute. 1801 During a Subscription Creation Operation, the Printer MUST populate 1802 this attribute with the value of the "printer-uri" operation 1803 attribute in the request. From the Printer URI, the client can, for 1804 example, determine what security scheme was used. 1806 5.4.6 notify-job-id (integer(1:MAX)) 1808 This attribute specifies whether the containing Subscription Object 1809 is a Per-Job or Per-Printer Subscription Object, and for Per-Job 1810 Subscription Objects, it specifies the associated Job. 1812 A Printer MUST support this attribute. 1814 If this attribute is not present, the Subscription Object MUST be a 1815 Per-Printer Subscription. If this attribute is present, the 1816 Subscription Object MUST be a Per-Job Subscription Object and this 1817 attribute MUST identify the Job with which the Subscription Object is 1818 associated. 1820 Note: This attribute could be useful to a Notification Recipient that 1821 receives an Event Notification generated from a Per-Job Subscription 1822 Object and caused by a Printer Event. The Event Notification gives 1823 access to the Printer and the Subscription Object. The Event 1824 Notification gives access to the associated Job only via this 1825 attribute. See discussion of the 'job-completed' event in section 1826 5.3.2.1.3 about retention of the Job object after completion so that 1827 a Notification Recipient can query the Job object after receiving the 1828 'job-completed' Event Notification. 1830 5.4.7 notify-subscriber-user-name (name(MAX)) 1832 This attribute contains the name of the user who performed the 1833 Subscription Creation Operation. 1835 A Printer MUST support this attribute. 1837 The Printer sets this attribute to the most authenticated printable 1838 name that it can obtain from the authentication service over which 1839 the Subscription Creation Operation was received. The Printer uses 1840 the same mechanism for determining the value of this attribute as it 1841 does for a Job's "job-originating-user-name" (see [RFC2911] section 1842 4.3.6). 1844 Note: To help with authentication, a Subscription Object may have 1845 additional private attributes about the user, e.g., a credential of a 1846 principal. Such private attributes are implementation-dependent and 1847 not defined in this document. 1849 6 Printer Description Attributes Related to Notification 1851 This section defines the Printer Description attributes that are 1852 related to Notification. Table 3 lists the Printer Description 1853 attributes, indicates the Printer support required for conformance, 1854 and whether or not the attribute is READ-ONLY (see section 3.1): 1856 Table 3 - Printer Description Attributes Associated with Notification 1858 Printer object attributes: REQUIRED READ-ONLY 1860 printer-state-change-time (integer(1:MAX)) No Yes 1862 printer-state-change-date-time (dateTime) No Yes 1864 6.1 printer-state-change-time (integer(1:MAX)) 1866 This OPTIONAL attribute records the most recent time at which the 1867 'printer-state-changed' Printer Event occurred whether or not any 1868 Subscription objects were listening for this event. This attribute 1869 helps a client or operator to determine how long the Printer has been 1870 in its current state. 1872 A Printer MAY support this attribute and if so, the attribute MUST be 1873 READ-ONLY. 1875 On power-up, the Printer MUST set the value of this attribute to be 1876 the value of its "printer-up-time" attribute, so that it always has a 1877 value. Whenever the 'printer-state-changed' Printer Event occurs, the 1878 Printer MUST set this attribute to the value of the Printer's 1879 "printer-up-time" attribute. 1881 6.2 printer-state-change-date-time (dateTime) 1883 This OPTIONAL attribute records the most recent time at which the 1884 'printer-state-changed' Printer Event occurred whether or not there 1885 were any Subscription Objects listening for this event. This 1886 attribute helps a client or operator to determine how long the 1887 Printer has been in its current state. 1889 A Printer MAY support this attribute and if so, the attribute MUST be 1890 READ-ONLY. 1892 On power-up, the Printer MUST set the value of this attribute to be 1893 the value of its "printer-current-time" attribute, so that it always 1894 has a value (see [RFC2911] section 4.4.30 on "printer-current-time"). 1895 Whenever the 'printer-state-changed' Printer Event occurs, the 1896 Printer MUST set this attribute to the value of the Printer's 1897 "printer-current-time" attribute. 1899 7 New Values for Existing Printer Description Attributes 1901 This section contains those attributes for which additional values 1902 are added. 1904 7.1 operations-supported (1setOf type2 enum) 1906 The following "operation-id" values are added in order to support the 1907 new operations defined in this document: 1909 Table 4 - Operation-id assignments 1911 Value Operation Name 1913 0x0016 Create-Printer-Subscriptions 1915 0x0017 Create-Job-Subscriptions 1917 0x0018 Get-Subscription-Attributes 1919 0x0019 Get-Subscriptions 1921 0x001A Renew-Subscription 1923 0x001B Cancel-Subscription 1925 8 Attributes Only in Event Notifications 1927 This section contains those attributes that exist only in Event 1928 Notifications and do not exist in any objects. 1930 8.1 notify-subscribed-event (type2 keyword) 1932 This attribute indicates the Subscribed Event that caused the Printer 1933 to send this Event Notification. This attribute exists only in Event 1934 Notifications. 1936 This attribute MUST contain one of the values of the "notify-events" 1937 attribute in the Subscription Object, i.e., one of the Subscribed 1938 Event values. Its value is the Subscribed Event that "matches" the 1939 Event that caused the Printer to send this Event Notification. This 1940 Subscribed Event value may be identical to the Event or the Event may 1941 be a sub-value of the Subscribed Event. For example, the 'job- 1942 completed' Event (which is a sub-event of the 'job-state-changed' 1943 event) would cause the Printer to send an Event Notification for 1944 either the 'job-completed' or 'job-state-changed' Subscribed Events 1945 and to send the 'job-completed' or 'job-state-changed' value for this 1946 attribute, respectively,. See section 5.3.2.2 for the "matching" 1947 rules of Subscribed Events and for additional examples. 1949 The Delivery Method Document specifies whether the Printer includes 1950 the value of this attribute in an Event Notification. 1952 8.2 notify-text (text(MAX)) 1954 This attribute contains a Human Consumable text message (see section 1955 9.2). This message describes the Event and is encoded as plain text, 1956 i.e., 'text/plain' with the charset specified by Subscription 1957 Object's "notify-charset" attribute. 1959 The Delivery Method Document specifies whether the Printer includes 1960 this attribute in an Event Notification. 1962 9 Event Notification Content 1964 This section defines the Event Notification content that the Printer 1965 sends when an Event occurs. 1967 When an Event occurs, the Printer MUST find each Subscription object 1968 whose "notify-events" attribute "matches" the Event. See section 1969 5.3.2.2 for details on "matching". For each matched Subscription 1970 Object, the Printer MUST create an Event Notification with the 1971 content and format that the Delivery Method Document specifies. The 1972 content contains the value of attributes specified by the Delivery 1973 Method Document. The Printer obtains the values immediately after the 1974 Event occurs. For example, if the "printer-state" attribute changes 1975 from 'idle' to 'processing', the Event 'printer-state-changed' occurs 1976 and the Printer puts various attributes into the Event Notification, 1977 including "printer-up-time" and "printer-state" with the values that 1978 they have immediately after the Event occurs, i.e., the value of 1979 "printer-state" is 'processing'. 1981 Event Notification Ordering: 1983 When a Printer sends Event Notifications, the Event Notifications 1984 from any given Subscription Object MUST be in time stamp order, i.e., 1985 in order of increasing "printer-up-time" attribute value in the Event 1986 Notification (see Table 5). These Event Notifications MAY be 1987 interleaved with those from other Subscription Objects, as long as 1988 those others are also in time stamp order. The Printer MUST observe 1989 these ordering requirements whether sending multiple pending Events 1990 as multiple separate Event Notifications or together in a single 1991 Compound Event Notification. 1993 If a Subscribing Client wants the Printer to send certain Event 1994 Notifications in time stamp order, the Subscribing Client uses a 1995 single Subscription Object. Even so, depending on the underlying 1996 transport, the actual order that a Notification Recipient receives 1997 separate Event Notifications may differ from the order sent by the 1998 Printer (e.g., email). 2000 Example: Consider two Per-Printer Subscription Objects: SO1 and SO2. 2001 SO1 requests 'job-state-changed' events and SO2 requests 'printer- 2002 state-changed' events. The number in parens is the time stamp. The 2003 following Event Notification sequences are the only ones that conform 2004 to the ordering requirements for the Printer to send the Event 2005 Notifications: 2007 (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 'job- 2008 completed' (1009), SO2: 'printer-stopped' (1005) 2010 (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2: 2011 'printer-stopped' (1005), SO1: 'job-completed' (1009) 2013 (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1: 2014 'job-stopped' (1005), SO1: 'job-completed' (1009) 2016 (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1: 2017 'job-stopped' (1005), SO1: 'job-completed' (1009) 2019 Examples (b) and (c) are interleaved; examples (a) and (d) are not 2020 interleaved and are not appropriate for some Delivery Methods. 2022 If two different Events occur simultaneously, or nearly so (e.g., 2023 "printer-up-time" has the same value for both), the Printer MUST 2024 create a separate Event Notification for each Event, even if the 2025 associated Subscription Object is the same for both Events. However, 2026 the Printer MAY combine these distinct Event Notifications into a 2027 single Compound Event Notification if the Delivery Method supports 2028 Compound Event Notifications. For example, suppose that two nearly- 2029 simultaneously Events represent two successive 'printer-state- 2030 changed' Events, one from 'idle' to 'processing' and another from 2031 'processing' to 'stopped'. These two Events have the same name but 2032 are different instances of the Event. Then the Printer MUST create a 2033 separate Event Notification for each Event and SHOULD accurately 2034 report the "printer-state" of the first Event as 'processing' and the 2035 second Event as 'stopped'. 2037 If a Subscription Object contains more than one Subscribed Event, and 2038 several Events occur in quick succession each matching a different 2039 Subscribed Event in the Subscription Object, the Printer MUST NOT 2040 generate a single Event Notification from several of these Events, 2041 but MAY combine distinct Event Notifications into a single Compound 2042 Event Notification if the Delivery Method supports Compound Event 2043 Notifications. 2045 After the Printer has created the Event Notification, the Printer 2046 delivers it via either a: 2048 Push Delivery Method: The Printer sends the Event Notification 2049 shortly after an Event occurs. For some Push Delivery Methods, 2050 the Notification Recipient MUST send a response; for others it 2051 MUST NOT send a response. 2053 Pull Delivery Method: The Printer saves Event Notifications for 2054 some Event Life and expects the Notification Recipient to 2055 request Event Notifications. The Printer returns the Event 2056 Notifications in a response to such a request. 2058 If an error that meets the following conditions occurs, the Printer 2059 MUST cancel the Subscription Object. 2061 a)the error occurs during the sending of an Event Notification 2062 generated from Subscription Object S AND 2064 b)the error would continue to occur every time the Printer sends an 2065 Event Notification generated from Subscription Object S in the 2066 future. 2068 For example, if the address of the "notify-recipient-uri" of 2069 Subscription Object A references a non-existent target and the 2070 Printer determines this fact, it MUST delete Subscription Object A. 2072 The next two sections describe the values that a Printer sends in the 2073 content of Machine Consumable and Human Consumable Event 2074 Notifications, respectively. 2076 The tables in the sub-sections of this section contain the following 2077 columns: 2079 a)Source Value: the name of the attribute that supplies the value 2080 for the Event Notification. Asterisks in this field refer to a 2081 note below the table. 2083 b)Sends: if the Printer supports the value (column 1) on the 2084 Source Object (column 3) the Delivery Method MUST specify: 2086 MUST: that the Printer MUST send the value. 2088 SHOULD: either that the Printer MUST send the value or that 2089 the value is incompatible with the Delivery Method. 2091 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 2092 or NEED NOT send the value. The Delivery Method specifies the 2093 level of conformance for the Printer. 2095 c)Source Object: the object from which the source value comes. If 2096 the object is "Event Notification", the Printer fabricates the 2097 value when it sends the Event Notification. See section 8. 2099 9.1 Content of Machine Consumable Event Notifications 2101 This section defines the attributes that a Delivery Method MUST 2102 mention in a Delivery Method Document when specifying the Machine 2103 Consumable Event Notification's contents. 2105 This document does not define the order of attributes in Event 2106 Notifications. However, Delivery Method Documents MAY define the 2107 order of some or all of the attributes. 2109 A Delivery Method Document MUST specify additional attributes (if 2110 any) that a Printer implementation sends in a Machine Consumable 2111 Event Notification. 2113 Notification Recipients MUST be able to accept Event Notifications 2114 containing attributes they do not recognize. What a Notification 2115 Recipient does with an unrecognized attribute is implementation- 2116 dependent. Notification Recipients MAY attempt to display 2117 unrecognized attributes anyway or MAY ignore them. 2119 The next three sections define the attributes in Event Notification 2120 Contents that are: 2122 1.for all Events 2124 2.for Job Events only 2126 3.for Printer Events only 2128 9.1.1 Event Notification Content Common to All Events 2130 This section lists the attributes that a Delivery Method Document 2131 MUST specify for all Events. 2133 Table 5 lists potential values in each Event Notification. 2135 Table 5 - Attributes in Event Notification Content 2137 Source Value Sends Source Object 2139 notify-subscription-id (integer(1:MAX)) MUST Subscription 2141 notify-printer-uri (uri) MUST Subscription 2143 notify-subscribed-event (type2 keyword) MUST Event 2144 Notification 2146 printer-up-time (integer(MIN:MAX)) MUST Printer 2148 printer-current-time (dateTime) * MUST Printer 2150 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 2152 notify-charset (charset) SHOULD Subscription 2154 notify-natural-language (naturalLanguage) SHOULD Subscription 2156 notify-user-data (octetString(63)) ** SHOULD Subscription 2158 notify-text (text) SHOULD Event 2159 Notification 2161 attributes from the "notify-attributes" MAY Printer 2162 attribute *** 2164 attributes from the "notify-attributes" MAY Job 2165 attribute *** 2167 attributes from the "notify-attributes" MAY Subscription 2168 attribute *** 2170 *A Printer MUST send this value only if and only if it supports the 2171 Printer's "printer-current-time" attribute. 2173 ** If the Subscription Object does not contain a "notify-user-data" 2174 attribute and the Delivery Method Document REQUIRES the Printer to 2175 send the "notify-user-data" source value in the Event Notification, 2176 the Printer MUST send an octet-string of length 0. 2178 *** The last three rows represent additional attributes that a client 2179 MAY request via the "notify-attributes" attribute. A Printer MAY 2180 support the "notify-attributes" attribute. The Delivery Method MUST 2181 say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED 2182 NOT support the "notify-attributes" attribute and specific values of 2183 this attribute. The Delivery Method MAY say that support for the 2184 "notify-attributes" is conditioned on support of the attribute by the 2185 Printer or it MAY say that Printer MUST support the "notify- 2186 attributes" attribute if the Printer supports the Delivery Method. 2188 9.1.2 Additional Event Notification Content for Job Events 2190 This section lists the additional attributes that a Delivery Method 2191 Document MUST specify for Job Events. See Table 6. 2193 Table 6 - Additional Event Notification Content for Job Events 2195 Source Value Sends Source Object 2197 job-id (integer(1:MAX)) MUST Job 2199 job-state (type1 enum) MUST Job 2201 job-state-reasons (1setOf type2 keyword) MUST Job 2203 job-impressions-completed (integer(0:MAX)) * MUST Job 2205 * The Printer MUST send the "job-impressions-completed" attribute in 2206 an Event Notification only for the combinations of Events and 2207 Subscribed Events shown in Table 7. 2209 Table 7 - Combinations of Events and Subscribed Events for "job- 2210 impressions-completed" 2212 Job Event Subscribed Job Event 2214 'job-progress' 'job-progress' 2216 'job-completed' 'job-completed' 2218 'job-completed' 'job-state-changed' 2220 9.1.3 Additional Event Notification Content for Printer Events 2222 This section lists the additional attributes that a Delivery Method 2223 Document MUST specify for Printer Events. See Table 8. 2225 Table 8 - Additional Event Notification Content for Printer Events 2227 Source Value Sends Source Object 2229 printer-state (type1 enum) MUST Printer 2231 printer-state-reasons (1setOf type2 keyword) MUST Printer 2233 printer-is-accepting-jobs (boolean) MUST Printer 2235 9.2 Content of Human Consumable Event Notification 2237 This section defines the information that a Delivery Method MUST 2238 mention in a Delivery Method Document when specifying the Human 2239 Consumable Event Notifications contents or the value of the "notify- 2240 text" attribute. 2242 Such a Delivery Method MUST specify the following information and a 2243 Printer SHOULD send it: 2245 a)the Printer name (see Table 9) 2246 b)the time of the Event (see Table 11) 2247 c)for Printer Events only: 2248 i) the Event (see Table 10) and/or Printer state information 2249 (see Table 14) 2250 d)for Job Events only: 2251 i) the job identity (see Table 12) 2252 ii) the Event (see Table 10) and/or Job state information (see 2253 Table 13) 2255 The subsections of this section specify the attributes that a Printer 2256 MUST use to obtain this information. 2258 A Delivery Method Document MUST specify additional information (if 2259 any) that a Printer implementation sends in a Human Consumable Event 2260 Notification or in the "notify-text" attribute. 2262 A client MUST NOT request additional attributes via the "notify- 2263 attributes" attribute because this attribute works only for Machine 2264 Consumable Event Notifications. 2266 Notification Recipients MUST NOT expect to be able to parse the Human 2267 Consumable Event Notification contents or the value of the "notify- 2268 text" attribute. 2270 The next three sections define the attributes in Event Notification 2271 Contents that are: 2273 a) for all Events 2274 b) for Job Events only 2275 c) for Printer Events only 2277 9.2.1 Event Notification Content Common to All Events 2279 This section lists the source of the information that a Delivery 2280 Method MUST specify for all Events. 2282 There is a separate table for each piece of information. Each row in 2283 the table represents a source value for the information and the 2284 values are listed in order of preference, with the first one being 2285 the preferred one. An implementation SHOULD use the source value from 2286 the earliest row in each table. It MAY use the source value from 2287 another row instead, or it MAY combine the source values from several 2288 rows. An implementation is free to determine the best way to present 2289 this information. 2291 In all tables of this section, all rows contain a "MAY" in order to 2292 state that the Delivery Method specifies the conformance. 2294 Table 9 lists the source of the information for the Printer Name. The 2295 "printer-name" is more user-friendly unless the Notification 2296 Recipient is in a place where the Printer name is not meaningful. For 2297 example, an implementation could have the intelligence to send the 2298 value of the "printer-name" attribute to a Notification Recipient 2299 that can access the Printer via value of the "printer-name" attribute 2300 and otherwise send the value of the "notify-printer-uri" attribute. 2302 Table 9 - Printer Name in Event Notification Content 2304 Source Value Sends Source Object 2306 printer-name (name(127)) MAY Printer 2308 notify-printer-uri (uri) MAY Subscription 2310 Table 10 lists the source of the information for the Event name. A 2311 Printer MAY combine this information with state information described 2312 for Jobs in Table 13 or for Printers in Table 14. 2314 Table 10 - Event Name in Event Notification Content 2316 Source Value Sends Source Object 2318 notify-subscribed-event (type2 keyword) MAY Subscription 2320 Table 11 lists the source of the information for the time that the 2321 Event occurred. A Printer can send this value only if it supports the 2322 Printer's "printer-current-time" attribute. If a Printer does not 2323 support the "printer-current-time" attribute, it MUST NOT send the 2324 "printer-up-time" value instead, since it is not an allowed option 2325 for human consumable information. 2327 Table 11 - Event Time in Event Notification Content 2329 Source Value Sends Source Object 2331 printer-current-time (dateTime) MAY Printer 2333 9.2.2 Additional Event Notification Content for Job Events 2335 This section lists the source of the additional information that a 2336 Delivery Method MUST specify for Job Events. 2338 Table 12 lists the source of the information for the job name. The 2339 "job-name" is likely more meaningful to a user than "job-id". 2341 Table 12 - Job Name in Event Notification Content 2343 Source Value Sends Source Object 2345 job-name (name(MAX)) MAY Job 2347 job-id (integer(1:MAX)) MAY Job 2349 Table 13 lists the source of the information for the job state. If a 2350 Printer supports the "job-state-message" and "job-detailed-state- 2351 message" attributes, it SHOULD use those attributes for the job state 2352 information, otherwise, it should fabricate such information from the 2353 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2354 combine this information with Event information. 2356 Table 13 - Job State in Event Notification Content 2358 Source Value Sends Source 2359 Object 2361 job-state-message (text(MAX)) MAY Job 2363 job-detailed-status-messages (1setOf text(MAX)) MAY Job 2365 job-state (type1 enum) MAY Job 2367 job-state-reasons (1setOf type2 keyword) MAY Job 2369 9.2.3 Additional Event Notification Content for Printer Events 2371 This section lists the source of the additional information that a 2372 Delivery Method MUST specify for Printer Events. 2374 Table 14 lists the source of the information for the printer state. 2375 If a Printer supports the "printer-state-message", it SHOULD use that 2376 attribute for the job state information, otherwise it SHOULD 2377 fabricate such information from the "printer-state" and "printer- 2378 state-reasons". For some Events, a Printer MAY combine this 2379 information with Event information. 2381 Table 14 - Printer State in Event Notification Content 2383 Source Value Sends Source 2384 Object 2386 printer-state-message (text(MAX)) MAY Printer 2388 printer-state (type1 enum) MAY Printer 2390 printer-state-reasons (1setOf type2 keyword) MAY Printer 2392 printer-is-accepting-jobs (boolean) MAY Printer 2394 10 Delivery Methods 2396 A Delivery Method is the mechanism, i.e., protocol, by which the 2397 Printer delivers an Event Notification to a Notification Recipient. 2398 There are several potential Delivery Methods for Event Notifications, 2399 standardized, as well as proprietary. This document does not define 2400 any of these delivery mechanisms. Each Delivery Method MUST be 2401 defined in a Delivery Method Document that is separate from this 2402 document. New Delivery Methods will be created as needed using an 2403 extension to the registration procedures defined in [RFC2911]. Such 2404 documents are registered with IANA (see section 13.7.3). 2406 The following sorts of Delivery Methods are expected: 2408 - The Notification Recipient polls for Event Notifications at 2409 intervals directed by the Printer 2411 - The Printer sends Event Notifications to the Notification 2412 Recipient using http as the transport. 2414 - The Printer sends an email message. 2416 This section specifies how to define a Delivery Method Document and 2417 what to put in such a document. 2419 A Delivery Method Document MUST contain an exact copy of the 2420 following paragraph, caption and table. In addition, column 2 of the 2421 table in the Delivery Method Document MUST contain answers to 2422 questions in column 1 for the Delivery Method. Also, the Delivery 2423 Method document MUST contain a reference to this document and call 2424 that reference [ipp-ntfy] because the table contains an [ipp-ntfy] 2425 reference. 2427 If a Printer supports this Delivery Method, the following are its 2428 characteristics. 2430 Table 15 - Information about the Delivery Method 2432 Document Method Conformance Requirement Delivery Method 2433 Realization 2435 1.What is the URL scheme name for the Push 2436 Delivery Method or the keyword method 2437 name for the Pull Delivery Method? 2439 2.Is the Delivery Method REQUIRED, 2440 RECOMMENDED, or OPTIONAL for an IPP 2441 Printer to support? 2443 3.What transport and delivery protocols 2444 does the Printer use to deliver the 2445 Event Notification Content, i.e., what 2446 is the entire network stack? 2448 4.Can several Event Notifications be 2449 combined into a Compound Event 2450 Notification? 2452 5.Is the Delivery Method initiated by the 2453 Notification Recipient (pull), or by the 2454 Printer (push)? 2456 6.Is the Event Notification content 2457 Machine Consumable or Human Consumable? 2459 7.What section in this document answers 2460 the following question? For a Machine 2461 Consumable Event Notification, what is 2462 the representation and encoding of 2463 values defined in section 9.1 of [ipp- 2464 ntfy] and the conformance requirements 2465 thereof? For a Human Consumable Event 2466 Notification, what is the representation 2467 and encoding of pieces of information 2468 defined in section 9.2 of [ipp-ntfy] and 2469 the conformance requirements thereof? 2471 8.What are the latency and reliability of 2472 the transport and delivery protocol? 2474 9.What are the security aspects of the 2475 transport and delivery protocol, e.g., 2476 how it is handled in firewalls? 2478 10. What are the content length 2479 restrictions? 2481 11. What are the additional values or 2482 pieces of information that a Printer 2483 sends in an Event Notification content 2484 and the conformance requirements 2485 thereof? 2487 12. What are the additional Subscription 2488 Template and/or Subscription Description 2489 attributes and the conformance 2490 requirements thereof? 2492 13. What are the additional Printer 2493 Description attributes and the 2494 conformance requirements thereof? 2496 11 Operations for Notification 2498 This section defines all of the operations for Notification. Section 2499 7.1 assigns the "operation-id" for each operation. The following two 2500 sub-sections define Subscription Creation Operations, and other 2501 operations. 2503 11.1 Subscription Creation Operations 2505 This section defines the Subscription Creation Operations. The first 2506 section on Create-Job-Subscriptions gives most of the information. 2507 The other Subscription Creation Operations refer to the section on 2508 Create-Job-Subscriptions, even though the Create-Job-Subscriptions 2509 operation is the only OPTIONAL operation in this document (see 2510 section 12). 2512 A Printer MUST support Create-Printer-Subscriptions and the 2513 Subscription Template Attributes Group in Job Creation operations. It 2514 MAY support Create-Job-Subscriptions operations. 2516 11.1.1 Create-Job-Subscriptions Operation 2518 The operation creates one or more Per-Job Subscription Objects. The 2519 client supplies one or more Subscription Template Attributes Groups 2520 each containing one or more of Subscription Template Attributes 2521 (defined in section 5.3). 2523 Except for errors, the Printer MUST create exactly one Per-Job 2524 Subscription Object from each Subscription Template Attributes Group 2525 in the request, even if the newly created Subscription Object would 2526 have identical behavior to some existing Subscription Object. The 2527 Printer MUST associate each newly created Per-Job Subscription Object 2528 with the target Job, which is specified by the "notify-job-id" 2529 operation attribute. 2531 The Printer MUST accept the request in any of the target job's 'not- 2532 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2533 'processing-stopped'. The Printer MUST NOT change the job's "job- 2534 state" attribute because of this operation. If the target job is in 2535 any of the 'completed' states, i.e., 'completed', 'canceled', or 2536 'aborted, then the Printer MUST reject the request and return the 2537 'client-error-not-possible' status code; the response MUST NOT 2538 contain any Subscription Attribute Groups. 2540 Access Rights: To create Per-Job Subscription Objects, the 2541 authenticated user (see [RFC2911] section 8.3) performing this 2542 operation MUST either be the job owner or have Operator or 2543 Administrator access rights for this Printer (see [RFC2911] sections 2544 1 and 8.5). Otherwise the Printer MUST reject the operation and 2545 return: the 'client-error-forbidden', 'client-error-not- 2546 authenticated', or 'client-error-not-authorized' status code as 2547 appropriate. 2549 11.1.1.1 Create-Job-Subscriptions Request 2551 The following groups of attributes are part of the Create-Job- 2552 Subscriptions Request: 2554 Group 1: Operation Attributes 2556 Natural Language and Character Set: 2557 The "attributes-charset" and "attributes-natural-language" 2558 attributes as described in [RFC2911] section 3.1.4.1. 2560 Target: 2561 The "printer-uri" attribute which defines the target for this 2562 operation as described in [RFC2911] section 3.1.5. 2564 Requesting User Name: 2565 The "requesting-user-name" attribute SHOULD be supplied by the 2566 client as described in [RFC2911] section 8.3. 2568 notify-job-id (integer(1:MAX)): 2569 The client MUST supply this attribute and it MUST specify the 2570 Job object to associate the Per-Job Subscription with. The 2571 value of "notify-job-id" MUST be the value of the "job-id" of 2572 the associated Job object. If the client does not supply this 2573 attribute, the Printer MUST reject this request with a 'client- 2574 error-bad-request' status code. 2576 Group 2-N: Subscription Template Attributes 2578 For each occurrence of this group: 2580 The client MUST supply one or more Subscription Template 2581 Attributes in any order. See section 5.3 for a description of 2582 each such attribute. See section 5.2 for details on processing 2583 these attributes. 2585 11.1.1.2 Create-Job-Subscriptions Response 2587 The Printer MUST return to the client the following sets of 2588 attributes as part of a Create-Job-Subscriptions response: 2590 Group 1: Operation Attributes 2592 Status Message: 2593 In addition to the REQUIRED status code returned in every 2594 response, the response OPTIONALLY includes a "status-message" 2595 (text(255)) and/or a "detailed-status-message" (text(MAX)) 2596 operation attribute as described in [RFC2911] sections 13 and 2597 3.1.6. 2599 In this group, the Printer can return any status codes defined 2600 in [RFC2911] and section 16. The following is a description of 2601 the important status codes: 2603 successful-ok: the Printer created all Subscription Objects 2604 requested (see [RFC2911]). 2605 successful-ok-ignored-subscriptions: the Printer created 2606 some Subscription Objects requested but some failed. The 2607 Subscription Attributes Groups with a "notify-status- 2608 code" attribute are the ones that failed (see section 2609 16.1). 2611 client-error-ignored-all-subscriptions: the Printer created 2612 no Subscription Objects requested and all failed. The 2613 Subscription Attributes Groups with a "notify-status- 2614 code" attribute are the ones that failed (see section 2615 16.2). 2616 client-error-not-possible: For this operation and other 2617 Per-Job Subscription operations, this error can occur 2618 because the specified Job has already completed (see 2619 [RFC2911], whether or not the Job is retained in the Job 2620 Retention and/or Job History phases (see [RFC2911] 2621 section 4.3.7.1). 2623 Natural Language and Character Set: 2624 The "attributes-charset" and "attributes-natural-language" 2625 attributes as described in [RFC2911] section 3.1.4.2. 2627 Group 2: Unsupported Attributes 2629 See [RFC2911] section 3.1.7 for details on returning 2630 Unsupported Attributes. This group does not contain any 2631 unsupported Subscription Template Attributes; they are returned 2632 in the Subscription Attributes Group (see below). 2634 Group 3-N: Subscription Attributes 2636 These groups MUST be returned unless the Printer is unable to 2637 interpret the entire request, e.g., the "status-code" parameter 2638 returned in Group 1 has the value: 'client-error-bad-request'. 2640 "notify-status-code" (type2 enum): 2641 Indicates the status of this subscription (see section 17 2642 for the status code definitions). Section 5.2 defines when 2643 this attribute MUST be present in this group. 2645 See section 5.2 for details on the contents of each occurrence 2646 of this group. 2648 11.1.2 Create-Printer-Subscriptions operation 2650 The operation is identical to Create-Job-Subscriptions with 2651 exceptions noted in this section. 2653 The operation creates Per-Printer Subscription Objects instead of 2654 Per-Job Subscription Objects, and associates each newly created Per- 2655 Printer Subscription Object with the Printer specified by the 2656 operation target rather than with a specific Job. 2658 The Printer MUST accept the request in any of its states, i.e., 2659 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its 2660 "printer-state" attribute because of this operation. 2662 Access Rights: To create Per-Printer Subscription Objects, the 2663 authenticated user (see [RFC2911] section 8.3) performing this 2664 operation MUST have Operator or Administrator access rights for this 2665 Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the Printer 2666 MUST reject the operation and return: the 'client-error-forbidden', 2667 'client-error-not-authenticated', or 'client-error-not-authorized' 2668 status code as appropriate. 2670 11.1.2.1 Create-Printer-Subscriptions Request 2672 The groups are identical to the Create-Job-Subscriptions (see section 2673 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2674 the "notify-job-id" attribute. If the client does supply the 2675 "notify-job-id" attribute, then the Printer MUST treat it as any 2676 other unsupported Operation attribute and MUST return it in the 2677 Unsupported Attributes group. 2679 11.1.2.2 Create-Printer-Subscriptions Response 2681 The groups are identical to the Create-Job-Subscriptions (see section 2682 11.1.1.2). 2684 11.1.3 Job Creation Operations - Extensions for Notification 2686 This document extends the Job Creation operations (see section 3.2) 2687 to create Subscription Objects as a part of the operation. 2689 The Job Creation operations are identical to Create-Job-Subscriptions 2690 operation with exceptions noted in this section. 2692 Unlike the Create-Job-Subscriptions operation, a Job Creation 2693 operation associates the newly created Subscription Objects with the 2694 Job object created by this operation. The operation succeeds if and 2695 only if the Job creation succeeds. If the Printer does not create 2696 some or all of the requested Subscription Objects, the Printer MUST 2697 return a 'successful-ok-ignored-subscriptions' status-code instead 2698 of a 'successful-ok' status-code, but the Printer MUST NOT reject the 2699 operation because of a failure to create Subscription Objects. 2701 If the Job Creation operation includes a Job Template group, the 2702 client MUST supply it after the Operation Attributes group and before 2703 the first Subscription Template Attributes Group. 2705 If a Printer does not support this Notification specification, then 2706 it MUST treat the Subscription Attributes Group like an unknown group 2707 and ignore it (see [RFC2911] section 5.2.2). Because the Printer 2708 ignores the Subscription Attributes Group, it doesn't return them in 2709 the response either, thus indicating to the client that the Printer 2710 doesn't support Notification. 2712 After completion of a successful Job Creation operation, the Printer 2713 generates a 'job-created' event (see section 5.3.2.1.3). 2715 Access Rights: To create Per-Job Subscription Objects, the 2716 authenticated user (see [RFC2911] section 8.3) performing this 2717 operation MUST either have permission to create Jobs on the Printer 2718 or have Operator or Administrator access rights for this Printer (see 2719 [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the 2720 operation and return: the 'client-error-forbidden', 'client-error- 2721 not-authenticated', or 'client-error-not-authorized' status code as 2722 appropriate. 2724 11.1.3.1 Job Creation Request 2726 The groups for this operation are sufficiently different from the 2727 Create-Job-Subscriptions operation that they are all presented here. 2728 The following groups of attributes are supplied as part of a Job 2729 Creation Request: 2731 Group 1: Operation Attributes 2733 Same as defined in [RFC2911] for Print-Job, Print-URI, and 2734 Create-Job requests. 2736 Group 2: Job Template Attributes 2738 The client OPTIONALLY supplies a set of Job Template attributes 2739 as defined in [RFC2911] section 4.2. 2741 Group 3 to N: Subscription Template Attributes 2743 The same as Group 2-N in Create-Job-Subscriptions. See section 2744 11.1.1.1. 2745 Group N+1: Document Content (Print-Job only) 2747 The client MUST supply the document data to be processed. 2749 11.1.3.2 Job Creation Response 2751 The Printer MUST return to the client the following sets of 2752 attributes as part of a Print-Job, Print-URI, and Create-Job 2753 Response: 2755 Group 1: Operation Attributes 2757 Status Message: 2759 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2760 Job requests. 2762 In this group, the Printer can return any status codes defined 2763 in [RFC2911] and section 16. The following is a description of 2764 the important status codes: 2766 successful-ok: the Printer created the Job and all 2767 Subscription Objects requested (see [RFC2911]. 2768 successful-ok-ignored-subscriptions: the Printer created 2769 the Job and not all of the Subscription Objects requested 2770 (see section 16.1). This status-code hides 'successful- 2771 ok-xxx' status-codes that could reveal problems in Job 2772 creation. The Printer MUST NOT return the 'client-error- 2773 ignored-all-subscriptions' status code for Job Creation 2774 operations because the Printer returns an error status- 2775 code only when it fails to create a Job. 2777 Natural Language and Character Set: 2778 The "attributes-charset" and "attributes-natural-language" 2779 attributes as described in [RFC2911] section 3.1.4.2. 2781 Group 2: Unsupported Attributes 2783 See [RFC2911] section 3.1.7 for details on returning 2784 Unsupported Attributes. This group does not contain any 2785 unsupported Subscription Template Attributes; they are returned 2786 in the Subscription Attributes Group (see below). 2788 Group 3: Job Object Attributes 2790 The "job-id" of the Job Object just created, etc., as defined 2791 in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. 2793 Group 4 to N: Subscription Attributes 2794 These groups MUST be returned if and only if the client 2795 supplied Subscription Template Attributes and the operation was 2796 accepted. 2797 See section 5.2 for details on the contents of each occurrence 2798 of this group. 2800 11.2 Other Operations 2802 This section defines other operations on Subscription objects. 2804 11.2.1 Restart-Job Operation - Extensions for Notification 2806 The Restart-Job operation [RFC2911] is neither a Job Creation 2807 operation nor a Subscription Creation operation (see section 3.2). 2808 For the Restart-Job operation, the client MUST NOT supply any Job 2809 Subscription Attributes Groups. The Printer MUST treat any supplied 2810 Job Subscription Attributes as unsupported attributes. 2812 For this operation, the Printer does not return a job-id or any 2813 Subscription Attributes groups because the Printer reuses the 2814 existing Job object with the same job-id and the existing Per-Job 2815 Subscription Objects with the same subscription-ids. However, after 2816 successful completion of this operation, the Printer generates a 2817 'job-created' event (see section 5.3.2.1.3). 2819 11.2.2 Validate-Job Operation - Extensions for Notification 2821 A client can test whether one or more Subscription Objects could be 2822 created using the Validate-Job operation. The client supplies one or 2823 more Subscription Template Attributes Groups (defined in section 2824 5.3), just as in a Job Creation request. 2826 A Printer MUST support this extension to this operation. 2828 The Printer MUST accept requests that are identical to the Job 2829 Creation request defined in section 11.1.3.1, except that the request 2830 MUST NOT contain document data. 2832 The Printer MUST return the same groups and attributes as the Print- 2833 Job operation (section 11.1.3.1) with the following exceptions. The 2834 Printer MUST NOT return a Job Object Attributes Group because no Job 2835 is created. The Printer MUST NOT return the "notify-subscription-id" 2836 attribute in any Subscription Attribute Group because no Subscription 2837 Object is created. 2839 If the Printer would succeed in creating a Subscription Object, the 2840 corresponding Subscription Attributes Group either has no 'status- 2841 code' attribute or a 'status-code' attribute with a value of 2842 'successful-ok-too-many-events' or 'successful-ok-ignored-or- 2843 substituted-attributes' (see sections 5.2 and 17). The status-codes 2844 have the same meaning as in Job Creation except the results state 2845 what "would happen". 2847 The Printer MUST validate Subscription Template Attributes Groups in 2848 the same manner as the Job Creation operations. 2850 11.2.3 Get-Printer-Attributes - Extensions for Notification 2852 This operation is extended so that it returns Printer attributes 2853 defined in this document. 2855 A Printer MUST support this extension to this operation. 2857 In addition to the requirements of [RFC2911] section 3.2.5, a Printer 2858 MUST support the following additional values for the "requested- 2859 attributes" Operation attribute in this operation and return such 2860 attributes in the Printer Object Attributes group of its response. 2862 1.Subscription Template Attributes: Each supported attribute in 2863 column 2 of Table 1. 2865 2.New Printer Description Attributes: Each supported attribute in 2866 section 6. 2868 3.New Group Name: The 'subscription-template' group name, which 2869 names all supported Subscription Template Attribute in column 2 2870 of Table 1. This group name is also used in the Get- 2871 Subscription-Attributes and Get-Subscriptions operation with an 2872 analogous meaning. 2874 4.Extended Group Name: The 'all' group name, which names all 2875 Printer attributes according to [RFC2911] section 3.2.5. In 2876 this extension 'all' names all attributes specified in [RFC2911] 2877 plus those named in items 1 and 2 of this list. 2879 11.2.4 Get-Subscription-Attributes operation 2881 This operation allows a client to request the values of the 2882 attributes of a Subscription Object. 2884 A Printer MUST support this operation. 2886 This operation is almost identical to the Get-Job-Attributes 2887 operation (see [RFC2911] section 3.3.4). The only differences are 2888 that the operation is directed at a Subscription Object rather than a 2889 Job object, and the returned attribute group contains Subscription 2890 Object attributes rather than Job object attributes. 2892 11.2.4.1 Get-Subscription-Attributes Request 2894 The following groups of attributes are part of the Get-Subscription- 2895 Attributes request: 2897 Group 1: Operation Attributes 2899 Natural Language and Character Set: 2900 The "attributes-charset" and "attributes-natural-language" 2901 attributes as described in section [RFC2911] 3.1.4.1. 2903 Target: 2904 The "printer-uri" attribute which defines the target for this 2905 operation as described in [RFC2911] section 3.1.5. 2907 "notify-subscription-id" (integer (1:MAX)): 2908 The client MUST supply this attribute. The Printer MUST 2909 support this attribute. This attribute specifies the 2910 Subscription Object from which the client is requesting 2911 attributes. If the client omits this attribute, the Printer 2912 MUST reject this request with the 'client-error-bad-request' 2913 status code. 2915 Requesting User Name: 2916 The "requesting-user-name" attribute SHOULD be supplied by the 2917 client as described in [RFC2911] section 8.3. 2919 "requested-attributes" (1setOf keyword): 2920 The client OPTIONALLY supplies this attribute. The Printer 2921 MUST support this attribute. This attribute specifies the 2922 attributes of the specified Subscription Object that the 2923 Printer MUST return in the response. Each value of this 2924 attribute is either an attribute name (defined in sections 5.3 2925 and 5.4) or an attribute group name. The attribute group names 2926 are: 2928 - 'subscription-template': all attributes that are both 2929 defined in section 5.3 and present on the specified 2930 Subscription Object (column 1 of Table 1). 2932 - 'subscription-description': all attributes that are both 2933 defined in section 5.4 and present on the specified 2934 Subscription Object (Table 2). 2935 - 'all': all attributes that are present on the specified 2936 Subscription Object. 2938 A Printer MUST support all these group names. 2940 If the client omits this attribute, the Printer MUST respond as 2941 if this attribute had been supplied with a value of 'all'. 2943 11.2.4.2 Get-Subscription-Attributes Response 2945 The Printer returns the following sets of attributes as part of the 2946 Get-Subscription-Attributes Response: 2948 Group 1: Operation Attributes 2950 Status Message: 2951 Same as [RFC2911]. 2953 Natural Language and Character Set: 2954 The "attributes-charset" and "attributes-natural-language" 2955 attributes as described in [RFC2911] section 3.1.4.2. The 2956 "attributes-natural-language" MAY be the natural language of 2957 the Subscription Object, rather than the one requested. 2959 Group 2: Unsupported Attributes 2961 See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on 2962 returning Unsupported Attributes. 2964 The response NEED NOT contain the "requested-attributes" 2965 operation attribute with any supplied keyword values that were 2966 requested by the client but are not supported by the IPP 2967 object. If the Printer object does return unsupported 2968 attributes referenced in the "requested-attributes" operation 2969 attribute, the values of the "requested-attributes" attribute 2970 returned MUST include only the unsupported keywords that were 2971 requested by the client. If the client had requested a group 2972 name, such as 'all', the resulting unsupported attributes 2973 returned MUST NOT include attribute keyword names described in 2974 the standard but not supported by the implementation. 2976 Group 3: Subscription Attributes 2977 This group contains a set of attributes with their current 2978 values. Each attribute in this group: 2980 a)MUST be specified by the "requested-attributes" attribute 2981 in the request, AND 2983 b)MUST be present on the specified Subscription Object AND 2985 c)MUST NOT be restricted by the security policy in force. 2986 For example, a Printer MAY prohibit a client who is not the 2987 creator of a Subscription Object from seeing some or all of 2988 its attributes. See [RFC2911] section 8. 2990 The Printer can return the attributes of the Subscription 2991 Object in any order. The client MUST accept the attributes in 2992 any order. 2994 11.2.5 Get-Subscriptions operation 2996 This operation allows a client to retrieve the values of attributes 2997 of all Subscription Objects belonging to a Job or Printer. 2999 A Printer MUST supported this operation. 3001 This operation is similar to the Get-Subscription-Attributes 3002 operation, except that this Get-Subscriptions operation returns 3003 attributes from possibly more than one object. 3005 This operation is similar to the Get-Jobs operation (see [RFC2911] 3006 section 3.2.6), except that the operation returns Subscription 3007 Objects rather than Job objects. 3009 11.2.5.1 Get-Subscriptions Request 3011 The following groups of attributes are part of the Get-Subscriptions 3012 request: 3014 Group 1: Operation Attributes 3016 Natural Language and Character Set: 3017 The "attributes-charset" and "attributes-natural-language" 3018 attributes as described in [RFC2911] section 3.1.4.1. 3020 Target: 3021 The "printer-uri" attribute which defines the target for this 3022 operation as described in [RFC2911] section 3.1.5. 3024 Requesting User Name: 3025 The "requesting-user-name" attribute SHOULD be supplied by the 3026 client as described in [RFC2911] section 8.3. 3028 "notify-job-id" (integer(1:MAX)): 3029 If the client specifies this attribute, the Printer returns the 3030 specified attributes of all Per-Job Subscription Objects 3031 associated with the Job whose "job-id" attribute value equals 3032 the value of this attribute. If the client does not specify 3033 this attribute, the Printer returns the specified attributes of 3034 all Per-Printer Subscription Objects. Note: there is no way to 3035 get all Per-Job Subscriptions known to the Printer in a single 3036 operation. A Get-Jobs operation followed by a Get- 3037 Subscriptions operation for each Job will return all Per-Job 3038 Subscriptions. 3040 "limit" (integer(1:MAX)): 3041 The client OPTIONALLY supplies this attribute. The Printer 3042 MUST support this attribute. It is an integer value that 3043 determines the maximum number of Subscription Objects that a 3044 client will receive from the Printer even if the "my- 3045 subscriptions" attribute constrains which Subscription Objects 3046 are returned. The limit is a "stateless limit" in that if the 3047 value supplied by the client is 'N', then only the first 'N' 3048 Subscription Objects are returned in the Get-Subscriptions 3049 Response. There is no mechanism to allow for the next 'M' 3050 Subscription Objects after the first 'N' Subscription Objects. 3051 If the client does not supply this attribute, the Printer 3052 responds with all applicable Subscription Objects. 3054 "requested-attributes" (1setOf type2 keyword): 3055 The client OPTIONALLY supplies this attribute. The Printer 3056 MUST support this attribute. This attribute specifies the 3057 attributes of the specified Subscription Objects that the 3058 Printer MUST return in the response. Each value of this 3059 attribute is either an attribute name (defined in sections 5.3 3060 and 5.4) or an attribute group name (defined in section 3061 11.2.4.1). If the client omits this attribute, the Printer MUST 3062 respond as if the client had supplied this attribute with the 3063 one value: 'notify-subscription-id'. 3065 "my-subscriptions" (boolean): 3066 The client OPTIONALLY supplies this attribute. The Printer 3067 MUST support this attribute. If the value is 'false', the 3068 Printer MUST consider the Subscription Objects from all users 3069 as candidates. If the value is 'true', the Printer MUST return 3070 the Subscription Objects created by the requesting user of this 3071 request. If the client does not supply this attribute, the 3072 Printer MUST respond as if the client had supplied the 3073 attribute with a value of 'false'. The means for 3074 authenticating the requesting user and matching the 3075 Subscription Objects is similar to that for Jobs which is 3076 described in [RFC2911] section 8. 3078 11.2.5.2 Get-Subscriptions Response 3080 The Printer returns the following sets of attributes as part of the 3081 Get-Subscriptions Response: 3083 Group 1: Operation Attributes 3085 Status Message: 3086 Same as [RFC2911]. 3088 Natural Language and Character Set: 3089 The "attributes-charset" and "attributes-natural-language" 3090 attributes as described in [RFC2911] section 3.1.4.2. 3092 Group 2: Unsupported Attributes 3094 Same as for Get-Subscription-Attributes. 3096 Groups 3 to N: Subscription Attributes 3098 The Printer responds with one Subscription Attributes Group for 3099 each requested Subscription Object (see the "notify-job-id" 3100 attribute in the Operation Attributes Group of this operation). 3102 The Printer returns Subscription Objects in any order. 3104 If the "limit" attribute is present in the Operation Attributes 3105 group of the request, the number of Subscription Attributes 3106 Groups in the response MUST NOT exceed the value of the "limit" 3107 attribute. 3109 It there are no Subscription Objects associated with the 3110 specified Job or Printer, the Printer MUST return zero 3111 Subscription Attributes Groups and it MUST NOT treat this case 3112 as an error, i.e., the status-code MUST be 'successful-ok' 3113 unless something else causes the status code to have some other 3114 value. 3116 See the Group 3 response (Subscription Attributes Group) of the 3117 Get-Subscription-Attributes operation (section 11.2.4.2) for 3118 the attributes that a Printer returns in this group. 3120 11.2.6 Renew-Subscription operation 3122 This operation allows a client to request the Printer to extend the 3123 lease on a Per-Printer Subscription Object. 3125 The Printer MUST support this operation. 3127 The Printer MUST accept this request for a Per-Printer Subscription 3128 Object in any of the target Printer's states, i.e., 'idle', 3129 'processing', or 'stopped', but MUST NOT change the Printer's 3130 "printer-state" attribute. 3132 The Printer MUST reject this request for a Per-Job Subscription 3133 Object because it has no lease (see section 5.4.3). The status code 3134 returned MUST be 'client-error-not-possible'. 3136 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3137 performing this operation MUST either be the owner of the Per-Printer 3138 Subscription Object or have Operator or Administrator access rights 3139 for the Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the 3140 Printer MUST reject the operation and return: the 'client-error- 3141 forbidden', 'client-error-not-authenticated', or 'client-error-not- 3142 authorized' status code as appropriate. 3144 11.2.6.1 Renew-Subscription Request 3146 The following groups of attributes are part of the Renew-Subscription 3147 Request: 3149 Group 1: Operation Attributes 3151 Natural Language and Character Set: 3152 The "attributes-charset" and "attributes-natural-language" 3153 attributes as described in [RFC2911] section 3.1.4.1. 3155 Target: 3156 The "printer-uri" attribute which defines the target for this 3157 operation as described in [RFC2911] section 3.1.5. 3159 "notify-subscription-id" (integer (1:MAX)): 3160 The client MUST supply this attribute. The Printer MUST 3161 support this attribute. This attribute specifies the Per- 3162 Printer Subscription Object whose lease the Printer MUST renew. 3163 If the client omits this attribute, the Printer MUST reject 3164 this request with the 'client-error-bad-request' status code. 3166 Requesting User Name: 3167 The "requesting-user-name" (name(MAX)) attribute SHOULD be 3168 supplied by the client as described in [RFC2911] section 8.3. 3170 Group 2: Subscription Template Attributes 3172 "notify-lease-duration" (integer(0:MAX)): 3173 The client MAY supply this attribute. It indicates the number 3174 of seconds to renew the lease for the specified Subscription 3175 Object. A value of 0 requests an infinite lease (which MAY 3176 require Operator access rights). If the client omits this 3177 attribute, the Printer MUST use the value of the Printer's 3178 "notify-lease-duration-default" attribute. See section 5.3.7 3179 for more details. 3181 11.2.6.2 Renew-Subscription Response 3183 The Printer returns the following sets of attributes as part of the 3184 Renew-Subscription Response: 3186 Group 1: Operation Attributes 3188 Status Message: 3189 Same as [RFC2911]. 3191 The following are some of the status codes returned (see 3192 [RFC2911]: 3194 successful-ok: The operation successfully renewed the lease 3195 on the Subscription Object for the requested duration. 3196 successful-ok-ignored-or-substituted-attributes: The 3197 operation successfully renewed the lease on the 3198 Subscription Object for some duration other than the 3199 amount requested. 3200 client-error-not-possible: The operation failed because the 3201 "notify-subscription-id" Operation attribute identified a 3202 Per-Job Subscription Object. 3203 client-error-not-found: The operation failed because the 3204 "notify-subscription-id" Operation attribute identified a 3205 non-existent Subscription Object. 3207 Natural Language and Character Set: 3208 The "attributes-charset" and "attributes-natural-language" 3209 attributes as described in [RFC2911] section 3.1.4.2. The 3210 "attributes-natural-language" MAY be the natural language of 3211 the Subscription Object, rather than the one requested. 3213 Group 2: Unsupported Attributes 3215 See [RFC2911] section 3.1.7 for details on returning 3216 Unsupported Attributes. 3218 Group 3: Subscription Attributes 3220 The Printer MUST return the following Subscription Attribute: 3222 "notify-lease-duration" (integer(0:MAX)): 3223 The value of this attribute MUST be the number of seconds that 3224 the Printer has granted for the lease of the Subscription 3225 Object (see section 5.3.7 for details, such as the value of 3226 this attribute when the Printer doesn't support the requested 3227 value). 3229 11.2.7 Cancel-Subscription operation 3231 This operation allows a client to delete a Subscription Object and 3232 stop the Printer from sending more Event Notifications. Once 3233 performed, there is no way to reference the Subscription Object. 3235 A Printer MUST supported this operation. 3237 The Printer MUST accept this request in any of the target Printer's 3238 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 3239 the Printer's "printer-state" attribute. 3241 If the specified Subscription Object is a Per-Job Subscription 3242 Object, the Printer MUST accept this request in any of the target 3243 Job's states, but MUST NOT change the Job's "job-state" attribute or 3244 affect the Job. 3246 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3247 performing this operation MUST either be the owner of the 3248 Subscription Object or have Operator or Administrator access rights 3249 for the Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the 3250 Printer MUST reject the operation and return: the 'client-error- 3251 forbidden', 'client-error-not-authenticated', or 'client-error-not- 3252 authorized' status code as appropriate. 3254 Note: There is no way to change any attributes on a Subscription 3255 Object, except the "notify-lease-duration" attribute (using the 3256 Renew-Subscription operation). In order to change other attributes, 3257 a client performs a Subscription Creation Operation and Cancel- 3258 Subscription operation on the old Subscription Object. If the client 3259 wants to avoid missing Event Notifications, it performs the 3260 Subscription Creation Operation first. If this order would create too 3261 many Subscription Objects on the Printer, the client reverses the 3262 order. 3264 11.2.7.1 Cancel-Subscription Request 3266 The following groups of attributes are part of the Cancel- 3267 Subscription Request: 3269 Group 1: Operation Attributes 3271 Natural Language and Character Set: 3272 The "attributes-charset" and "attributes-natural-language" 3273 attributes as described in [RFC2911] section 3.1.4.1. 3275 Target: 3276 The "printer-uri" attribute which defines the target for this 3277 operation as described in [RFC2911] section 3.1.5. 3279 "notify-subscription-id" (integer (1:MAX)): 3280 The client MUST supply this attribute. The Printer MUST 3281 support this attribute. This attribute specifies the 3282 Subscription Object that the Printer MUST cancel. If the client 3283 omits this attribute, the Printer MUST reject this request with 3284 the 'client-error-bad-request' status code. 3286 Requesting User Name: 3287 The "requesting-user-name" attribute SHOULD be supplied by the 3288 client as described in [RFC2911] section 8.3. 3290 11.2.7.2 Cancel-Subscription Response 3292 The Printer returns the following sets of attributes as part of the 3293 Cancel-Subscription Response: 3295 Group 1: Operation Attributes 3296 Status Message: 3297 Same as [RFC2911]. 3299 The following are some of the status codes returned (see 3300 [RFC2911]: 3302 successful-ok: The operation successfully canceled 3303 (deleted) the Subscription Object. 3304 client-error-not-found: The operation failed because the 3305 "notify-subscription-id" Operation attribute identified a 3306 non-existent Subscription Object. 3308 Natural Language and Character Set: 3309 The "attributes-charset" and "attributes-natural-language" 3310 attributes as described in [RFC2911] section 3.1.4.2. The 3311 "attributes-natural-language" MAY be the natural language of 3312 the Subscription Object, rather than the one requested. 3314 Group 2: Unsupported Attributes 3316 See [RFC2911] section 3.1.7 for details on returning 3317 Unsupported Attributes. 3319 12 Conformance Requirements 3321 It is OPTIONAL for IPP clients and Printers to implement this Event 3322 Notification specification. 3324 If this Event Notification specification is implemented, Printers 3325 MUST: 3327 - meet the Conformance Requirements detailed in section 5 of 3328 [RFC2911]. 3330 - support the Subscription Template Attributes Group in requests 3331 and the Subscription Attributes Group in responses. 3333 - support all of the following attributes: 3335 a.REQUIRED Subscription Object attributes in section 5. 3336 b.REQUIRED Printer Description object attributes in section 6. 3337 c.REQUIRED attributes in Event Notification content in section 3338 8. 3340 - send Event Notifications that conform to the requirements of 3341 section 9 and the requirements of the Delivery Method Document 3342 for each supported Delivery Method (the conformance 3343 requirements for Delivery Method Documents is specified in 3344 section 10). 3346 - for all of the Job Creation Operations that the Printer 3347 supports, MUST support the REQUIRED extensions for notification 3348 defined in section 11.1.3. 3350 - meet the conformance requirements for operations as described 3351 in Table 16 and meet the requirements for Printers as specified 3352 in the indicated sub-sections of section 11: 3354 Table 16 - Printer Conformance Requirements for Operations 3356 Operation Printer 3357 Conformance 3358 Requirements 3360 Create-Printer-Subscriptions (section 11.1.2) REQUIRED 3362 Create-Job-Subscriptions (section 11.1.1) OPTIONAL 3364 Get-Subscription-Attributes (section 11.2.3) REQUIRED 3366 Get-Subscriptions (section 11.2.5) REQUIRED 3368 Renew-Subscription (section 11.2.6) REQUIRED 3370 Cancel-Subscription (section 11.2.7) REQUIRED 3372 13 IANA Considerations 3374 This section contains the registration information for IANA to add to 3375 the various IPP Registries according to the procedures defined in RFC 3376 2911 [RFC2911] section 6 to cover the definitions in this document. 3377 In addition, this section defines how Events and Delivery Methods 3378 will be registered when they are defined in other documents. 3380 Note to RFC Editors: Replace RFC NNNN below with the RFC number 3381 for this document, so that it accurately reflects the content of 3382 the information for the IANA Registry. 3384 13.1 Attribute Registrations 3386 The following table lists all the attributes defined in this 3387 document. These are to be registered according to the procedures in 3388 RFC 2911 [RFC2911] section 6.2. 3390 Subscription Template attributes: Ref. Section: 3391 notify-recipient-uri (uri) RFC NNNN 5.3.1.1 3392 notify-schemes-supported (1setOf uriScheme) RFC NNNN 5.3.1.1 3393 notify-pull-method (type2 keyword) RFC NNNN 5.3.1.2 3394 notify-pull-method-supported (1setOf type2 keyword) 3395 RFC NNNN 5.3.1.2 3396 notify-events (1setOf type2 keyword) RFC NNNN 5.3.2 3397 notify-events-default (1setOf type2 keyword) RFC NNNN 5.3.2 3398 notify-events-supported (1setOf type2 keyword) RFC NNNN 5.3.2 3399 notify-max-events-supported (integer(2:MAX)) RFC NNNN 5.3.2 3400 notify-attributes (1setOf type2 keyword) RFC NNNN 5.3.3 3401 notify-attributes-supported (1setOf type2 keyword) 3402 RFC NNNN 5.3.3 3403 notify-user-data (octetString(63)) RFC NNNN 5.3.4 3404 notify-charset (charset) RFC NNNN 5.3.5 3405 notify-natural-language (naturalLanguage) RFC NNNN 5.3.6 3406 notify-lease-duration (integer(0:67108863)) RFC NNNN 5.3.7 3407 notify-lease-duration-default (integer(0:67108863)) 3408 RFC NNNN 5.3.7 3409 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 3410 rangeOfInteger(0:67108863))) RFC NNNN 5.3.7 3411 notify-time-interval (integer(0:MAX)) RFC NNNN 5.3.8 3413 Subscription Description Attributes: 3414 notify-subscription-id (integer (1:MAX))) RFC NNNN 5.4.1 3415 notify-sequence-number (integer (0:MAX))) RFC NNNN 5.4.2 3416 notify-lease-expiration-time (integer(0:MAX))) RFC NNNN 5.4.3 3417 notify-printer-up-time (integer(1:MAX))) RFC NNNN 5.4.4 3418 notify-printer-uri (uri)) RFC NNNN 5.4.5 3419 notify-job-id (integer(1:MAX))) RFC NNNN 5.4.6 3420 notify-subscriber-user-name (name(MAX))) RFC NNNN 5.4.7 3422 Printer Description Attributes: 3423 printer-state-change-time (integer(1:MAX))) RFC NNNN 6.1 3424 printer-state-change-date-time (dateTime)) RFC NNNN 6.2 3426 Attributes Only in Event Notifications 3427 notify-subscribed-event (type2 keyword) RFC NNNN 8.1 3428 notify-text (text(MAX)) RFC NNNN 8.2 3430 The resulting attribute registrations will be published in the 3431 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attributes/ 3432 area. 3434 13.2 Additional Enum Attribute Value Registrations for the "operations- 3435 supported" Printer Attribute 3437 The following table lists all the new enum attribute values defined 3438 in this document as additional type2 enum values for use with the 3439 "operations-supported" Printer Description attribute. These are to 3440 be registered according to the procedures in RFC 2911 [RFC2911] 3441 section 6.1. 3443 type2 enum Attribute Values: Value Ref. Section: 3444 Create-Printer-Subscriptions 0x0016 RFC NNNN 7.1 3445 Create-Job-Subscriptions 0x0017 RFC NNNN 7.1 3446 Get-Subscription-Attributes 0x0018 RFC NNNN 7.1 3447 Get-Subscriptions 0x0019 RFC NNNN 7.1 3448 Renew-Subscription 0x001A RFC NNNN 7.1 3449 Cancel-Subscription 0x001B RFC NNNN 7.1 3451 The resulting enum attribute value registrations will be published in 3452 the 3453 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 3454 values/operations-supported/ 3455 area. 3457 13.3 Operation Registrations 3459 The following table lists all of the operations defined in this 3460 document. These are to be registered according to the procedures in 3461 RFC 2911 [RFC2911] section 6.4. 3463 Operations: Ref. Section: 3464 Create-Job-Subscriptions Operation RFC NNNN 11.1.1 3465 Create-Printer-Subscriptions Operation RFC NNNN 11.1.2 3466 Job Creation Operations - Extensions RFC NNNN 11.1.3 3467 Validate-Job Operation - Extensions RFC NNNN 0 3468 Get-Printer-Attributes - Extensions RFC NNNN 11.2.3 3469 Get-Subscription-Attributes Operation RFC NNNN 11.2.4 3470 Get-Subscriptions Operation RFC NNNN 11.2.5 3471 Renew-Subscription Operation RFC NNNN 11.2.6 3472 Cancel-Subscription Operation RFC NNNN 11.2.7 3474 The resulting operation registrations will be published in the 3475 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/operations/ 3476 area. 3478 13.4 Status code Registrations 3480 The following table lists all the status codes defined in this 3481 document. These are to be registered according to the procedures in 3482 RFC 2911 [RFC2911] section 6.6. 3484 Status codes: Ref. Section: 3485 successful-ok-ignored-subscriptions (0x0003) RFC NNNN 16.1 3486 client-error-ignored-all-subscriptions (0x0414) RFC NNNN 16.2 3488 Status Codes in Subscription Attributes Groups: 3489 client-error-uri-scheme-not-supported (0x040C) RFC NNNN 17.1 3490 client-error-attributes-or-values-not-supported (0x040B) 3491 RFC NNNN 17.2 3492 client-error-too-many-subscriptions (0x0415) RFC NNNN 17.3 3493 successful-ok-too-many-events (0x0005) RFC NNNN 17.4 3494 successful-ok-ignored-or-substituted-attributes (0x0001) 3495 RFC NNNN 17.5 3497 The resulting status code registrations will be published in the 3498 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/status-codes/ 3499 area. 3501 13.5 Attribute Group tag Registrations 3503 The following table lists all the attribute group tags defined in 3504 this document. These are to be registered according to the 3505 procedures in RFC 2911 [RFC2911] section 6.5. 3507 Attribute Group Tags: Tag Value: Ref. Section: 3508 subscription-attributes-tag 0x06 RFC NNNN 18 3509 event-notification-attributes-tag 0x07 RFC NNNN 18 3511 The resulting attribute group tag registrations will be published in 3512 the 3513 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-group- 3514 tags/ 3515 area. 3517 13.6 Registration of Events 3519 When other document define additional type2 keywords to be used with 3520 the "notify-events" Subscription Template attribute (see section 3521 5.3.2)), these event keywords will be registered according to the 3522 procedures of [RFC2911] section 7.1 as additional attribute values 3523 for use with the "notify-events" Subscription Template attribute, 3524 i.e., the "notify-events", "notify-events-default", and "notify- 3525 events-supported" attributes. 3527 Therefore, the IPP Registry entry for an Event will be of the form: 3529 type2 enum Attribute Values: Ref. Section: 3530 RFC xxxx m.n 3532 The resulting type2 keyword attribute values will be published in the 3533 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 3534 values/notify-events/ 3535 area. 3537 13.7 Registration of Event Notification Delivery Methods 3539 This section describes the requirements and procedures for 3540 registration and publication of Event Notification Delivery Methods 3541 and for the submission of such proposals. 3543 13.7.1 Requirements for Registration of Event Notification Delivery 3544 Methods 3546 Registered IPP Event Notification Delivery Methods are expected to 3547 follow a number of requirements described below. 3549 13.7.1.1 Required Characteristics 3551 A Delivery Method Document MUST either (1) contain all of the 3552 semantics of the Delivery Method or (2) contain the IPP Delivery 3553 Method registration requirements and a profile of some other protocol 3554 that in combination is the Delivery Method (e.g., mailto). In either 3555 case, the Delivery Method Document (and any documents it requires) 3556 MUST define a URL for a Push Delivery Method or a keyword for a Pull 3557 Delivery method and be a standards track, informational, or 3558 experimental RFC that the meets the requirements of [RFC2717]. 3560 IPP Event Notification Delivery Method Documents MUST meet the 3561 requirements of this document (see sections 9 and 10). 3563 In addition, a Delivery Method Document MUST contain the following 3564 information: 3566 Type of registration: IPP Event Notification Delivery Method 3567 Name of this delivery method: 3569 Proposed URL scheme name of this Push Delivery Method or the 3570 keyword name of this Pull Delivery Method: 3571 Name of proposer: 3572 Address of proposer: 3573 Email address of proposer: 3574 Is this delivery method REQUIRED or OPTIONAL for conformance to the 3575 IPP Event Notification and Subscriptions document: 3576 Is this delivery method defining Machine Consumable and/or Human 3577 Consumable content: 3579 13.7.1.2 Naming Requirements 3581 Exactly one (URL scheme or keyword) name MUST be assigned to each 3582 Delivery Method. 3584 Each assigned name MUST uniquely identify a single Delivery Method. 3585 All Push Delivery Method names MUST conform to the rules for URL 3586 scheme names, according to [RFC2396] and [RFC2717] for schemes in the 3587 IETF tree. All Pull Delivery Method names MUST conform to the rules 3588 for keywords according to [RFC2911]. 3590 13.7.1.3 Functionality Requirements 3592 Delivery Methods MUST function as a protocol that is capable of 3593 delivering (push or pull) IPP Event Notifications to Notification 3594 Recipients. 3596 13.7.1.4 Usage and Implementation Requirements 3598 Use of a large number of Delivery Methods may hamper 3599 interoperability. However, the use of a large number of undocumented 3600 and/or unlabelled Delivery Methods hampers interoperability even 3601 more. 3603 A Delivery Method should therefore be registered ONLY if it adds 3604 significant functionality that is valuable to a large community, OR 3605 if it documents existing practice in a large community. Note that 3606 Delivery Methods registered for the second reason should be 3607 explicitly marked as being of limited or specialized use and should 3608 only be used with prior bilateral agreement. 3610 13.7.1.5 Publication Requirements 3612 Delivery Method Documents MUST be published in a standards track, 3613 informational, or experimental RFCs. 3615 13.7.2 Registration Procedure 3617 The IPP WG is developing a small number of Delivery Methods which are 3618 intended to be published as standards track RFCs. However, some 3619 parties may wish to register additional Delivery Methods in the 3620 future. This section describes the procedures for these additional 3621 Delivery Methods. 3623 13.7.2.1 Present the proposal to the Community 3625 First the Delivery Method Document MUST be an Internet-Draft with a 3626 target category of standards track, informational, or experimental. 3627 The same MUST be true for any documents that it references. 3629 Send the proposed Delivery Method Document proposal to the 3630 "ipp@pwg.org" mailing list. This mailing list has been established 3631 by [RFC2911] for reviewing proposed registrations and discussing 3632 other IPP matters. Proposed Delivery Method Documents are not 3633 formally registered and MUST NOT be used until approved. 3635 The intent of the public posting is to solicit comments and feedback 3636 on the definition and suitability of the Delivery Method and the name 3637 chosen for it over a four week period. 3639 13.7.2.2 Delivery Method Reviewer 3641 The Delivery Method Reviewer is the same person who has been 3642 appointed by the IETF Application Area Director(s) as the IPP 3643 Designated Expert according to [RFC2911] and [IANA-CON]. When the 3644 four week period is over and the IPP Designated Expert is convinced 3645 that consensus has been achieved, the IPP Designated Expert either 3646 approves the request for registration or rejects it. Rejection may 3647 occur because of significant objections raised on the list or 3648 objections raised externally. 3650 Decisions made by the Reviewer must be posted to the ipp@pwg.org 3651 mailing list within 14 days. Decisions made by the Reviewer may be 3652 appealed to the IESG. 3654 13.7.2.3 IANA Registration 3656 Provided that the Delivery Method registration proposal has either 3657 passed review or has been successfully appealed to the IESG, the IANA 3658 will register the Delivery Method and make it available to the 3659 community. 3661 13.7.3 Delivery Method Document Registrations 3663 Each Push Delivery Method Document defines a URI scheme which is 3664 registered as an additional value of the "notify-schemes-supported" 3665 Printer attribute. These uriScheme values will be registered 3666 according to the procedures of [RFC2911] section 7.1 for additional 3667 attribute values. Therefore, the IPP Registry entry for a Push 3668 Delivery Method will be of the form: 3670 uriScheme Attribute Values: Ref. Section: 3671 RFC xxxx m.n 3673 The resulting Delivery Method URI schemes will be published in the 3674 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 3675 values/notify-schemes-supported/ 3676 area. 3678 Each Pull Delivery Method Document defines a keyword method which is 3679 registered as an additional value of the "notify-pull-method- 3680 supported" Printer attribute. These keyword values will be 3681 registered according to the procedures of [RFC2911] section 7.1 for 3682 additional attribute values. Therefore, the IPP Registry entry for a 3683 Pull Delivery Method will be of the form: 3685 keyword Attribute Values: Ref. Section: 3686 RFC xxxx m.n 3688 The resulting Delivery Method URI schemes will be published in the 3689 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 3690 values/notify-pull-method-supported/ 3691 area. 3693 13.7.4 Registration Template 3695 To: ipp@pwg.org 3696 Subject: Registration of a new Delivery Method 3698 Delivery Method name: 3700 (All Push Delivery Method names must be suitable for use as the value 3701 of a URL scheme in the IETF tree and all Pull Delivery Method names 3702 must be suitable IPP keywords according to [RFC2911]) 3704 Published specification(s): 3706 (A specification for the Delivery Method must be openly available 3707 that accurately describes what is being registered.) 3709 Person & email address to contact for further information: 3711 14 Internationalization Considerations 3713 This IPP Notification specification continues support for the 3714 internationalization of [RFC2911] of attributes containing text 3715 strings and names. Allowing a Subscribing Client to specify a 3716 different natural language and charset for each Subscription Object 3717 increases the internationalization support. 3719 The Printer MUST be able to localize the content of Human Consumable 3720 Event Notifications and to localize the value of "notify-text" 3721 attribute in Machine Consumable Event Notifications that it sends to 3722 Notification Recipients. For localization, the Printer MUST use the 3723 value of the "notify-charset" attribute and the "notify-natural- 3724 language" attribute in the Subscription Object supplied by the 3725 Subscribing Client. 3727 15 Security Considerations 3729 By far the biggest security concern is the abuse of notification: 3730 sending unwanted Event Notifications to third parties (i.e., spam). 3731 The problem is made worse by notification addresses that may be 3732 redistributed to multiple parties (e.g., mailing lists). There exist 3733 scenarios where third party notification is required (see Scenario #2 3734 and #3 in [ipp-not-req]). The fully secure solution would require 3735 active agreement of all recipients before sending out anything. 3736 However, requirement #9 in [ipp-req] ("There is no requirement for 3737 IPP Printer receiving the print request to validate the identity of 3738 an Event recipient") argues against this. Certain systems may decide 3739 to disallow third party Event Notifications (a traditional fax 3740 model). 3742 Clients submitting Notification requests to the IPP Printer have the 3743 same security issues as submitting an IPP/1.1 print job request. The 3744 same mechanisms used by IPP/1.1 can therefore be used by the client 3745 Notification submission. Operations that require authentication can 3746 use the HTTP authentication. Operations that require privacy can use 3747 the HTTP/TLS privacy. As with IPP/1.1 Print Jobs, if there is no 3748 security on Subscription Objects, sequential assignment of 3749 subscription-ids exposes the system to a passive traffic monitoring 3750 threat. 3752 The Notification access control model should be similar to the IPP 3753 access control model for Jobs. Creating a Per-Printer Subscription 3754 Object is associated with a user. Only the creator or an Operator 3755 can cancel the Subscription Object. The system may limit the listing 3756 of items to only those items owned by the user. Some Subscription 3757 Objects (e.g., those that have a lifetime longer than a job) can be 3758 done only by privileged users (users having Operator and/or 3759 Administrator access rights), if that is the authorization policy. 3761 The standard security concerns (delivery to the right user, privacy 3762 of content, tamper proof content) apply to the Delivery Method. IPP 3763 should use the security mechanism of the Delivery Method used. Some 3764 delivery mechanisms are more secure than others. Therefore, 3765 sensitive Event Notifications should use the Delivery Method that has 3766 the strongest security. 3768 16 Status Codes 3770 The following status codes are defined as extensions for Notification 3771 and are returned as the value of the "status-code" parameter in the 3772 Operation Attributes Group of a response (see [RFC2911] section 3773 3.1.6.1). Operations in this document can also return the status 3774 codes defined in section 13 of [RFC2911]. The 'successful-ok' status 3775 code is an example of such a status code. 3777 16.1 successful-ok-ignored-subscriptions (0x0003) 3779 The Subscription Creation Operation was unable to create all 3780 requested Subscription Objects. 3782 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3783 operation, this status code means that the Printer created one or 3784 more Subscription Objects, but not all requested Subscription 3785 Objects. 3787 For a Job Creation operation, this status code means that the Printer 3788 created the Job along with zero or more Subscription Objects. The 3789 Printer returns this status code even if other job attributes are 3790 unsupported or in conflict. That is, if an IPP Printer finds a 3791 warning that would allow it to return 'successful-ok-ignored- 3792 subscriptions' and either 'successful-ok-ignored-or-substituted- 3793 attributes' and/or 'successful-ok-conflicting-attributes', it MUST 3794 return 'successful-ok-ignored-subscriptions'. 3796 16.2 client-error-ignored-all-subscriptions (0x0414) 3798 This status code is the same as 'successful-ok-ignored-subscriptions' 3799 except that only the Create-Job-Subscriptions and Create-Printer- 3800 Subscriptions operation return it. They return this status code only 3801 when the Printer creates zero Subscription Objects. 3803 17 Status Codes in Subscription Attributes Groups 3805 This section contains values of the "notify-status-code" (type2 enum) 3806 attribute that the Printer returns in a Subscription Attributes Group 3807 in a response when the corresponding Subscription Object: 3809 1.is not created or 3811 2.is created and some of the client-supplied attributes are not 3812 supported. 3814 The following sections are ordered in decreasing order of importance 3815 of the status-codes. 3817 17.1 client-error-uri-scheme-not-supported (0x040C) 3819 This status code is defined in [RFC2911]. This document extends its 3820 meaning and allows it to be in a Subscription Attributes Group of a 3821 response. 3823 The scheme of the client-supplied URI in a "notify-recipient-uri" 3824 Subscription Template Attribute in a Subscription Creation Operation 3825 is not supported. See section 5.3.1.1. 3827 17.2 client-error-attributes-or-values-not-supported (0x040B) 3829 This status code is defined in [RFC2911]. This document extends its 3830 meaning and allows it to be in a Subscription Attributes Group of a 3831 response. 3833 The method of the client-supplied keyword in a "notify-pull-method" 3834 Subscription Template Attribute in a Subscription Creation Operation 3835 is not supported. See section 5.3.1.2. 3837 17.3 client-error-too-many-subscriptions (0x0415) 3839 The number of Subscription Objects supported by the Printer would be 3840 exceeded if this Subscription Object were created (see section 5.2). 3842 17.4 successful-ok-too-many-events (0x0005) 3844 The client supplied more Events in the "notify-events" operation 3845 attribute of a Subscription Creation Operation than the Printer 3846 supports, as indicated in its "notify-max-events-supported" Printer 3847 attribute (see section 5.3.2). 3849 17.5 successful-ok-ignored-or-substituted-attributes (0x0001) 3851 This status code is defined in [RFC2911]. This document extends its 3852 meaning to include unsupported Subscription Template Attributes and 3853 it can appear in a Subscription Attributes Group. 3855 18 Encodings of Additional Attribute Tags 3857 This section assigns values to two attributes tags as extensions to 3858 the encoding defined in [RFC2910]). 3860 The "subscription-attributes-tag" delimits Subscription Template 3861 Attributes Groups in requests and Subscription Attributes Groups in 3862 responses. 3864 The "event-notification-attributes-tag" delimits Event Notifications 3865 in Delivery Methods that use an IPP-like encoding. 3867 The following table specifies the values for the delimiter tags: 3869 Tag Value (Hex) Meaning 3871 0x06 "subscription-attributes-tag" 3873 0x07 "event-notification-attributes-tag" 3875 19 References 3877 [IANA-CON] 3878 Narte, T. and Alvestrand, H.T.: Guidelines for Writing an IANA 3879 Considerations Section in RFCs, BCP 26, RFC 2434, October 1998. 3881 [ipp-not-req] 3882 deBry, R., Lewis, H., Hastings, T., "Internet Printing 3883 Protocol/1.1: Requirements for IPP Notifications", , work in progress, July 17, 2001. 3886 [ipp-prog] 3887 Hastings, T., Bergman, R., Lewis, H., "IPP: Job Progress 3888 Attributes", work in 3889 progress, July 17, 2001. 3891 [ipp-set] 3892 Kugler, C., Hastings, T., Herriot, R., Lewis, H, "Internet Printing 3893 Protocol (IPP): Job and Printer Set Operations", , work in progress, July 17, 2001. 3896 [RFC2026] 3897 S. Bradner, "The Internet Standards Process -- Revision 3", RFC 3898 2026, October 1996. 3900 [RFC2119] 3901 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3902 Levels", RFC 2119 , March 1997 3904 [RFC2396] 3905 Berners-Lee, T., Fielding, R., Masinter, L., "Uniform Resource 3906 Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 3908 [RFC2565] 3909 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3910 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 3911 1999. 3913 [RFC2566] 3914 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3915 "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, 3916 April 1999. 3918 [RFC2567] 3919 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3920 2567, April 1999. 3922 [RFC2568] 3923 Zilles, S., "Rationale for the Structure and Model and Protocol for 3924 the Internet Printing Protocol", RFC 2568, April 1999. 3926 [RFC2569] 3927 Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between 3928 LPD and IPP Protocols", RFC 2569, April 1999. 3930 [RFC2717] 3931 R. Petke and I. King, "Registration Procedures for URL Scheme 3932 Names", RFC 2717, November 1999. 3934 [RFC2910] 3935 Herriot, R., Butler, S., Moore, P., Turner, R., "Internet Printing 3936 Protocol/1.1: Encoding and Transport", RFC 2910, September 2000. 3938 [RFC2911] 3939 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., 3940 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 3941 September 2000. 3943 20 Author's Addresses 3945 Robert Herriot 3946 2066 Byron St. 3947 Palo Alto, CA 94301 3949 Phone: 650-326-8279 3950 Fax: 650-327-4466 3951 Email: bob@herriot.com 3953 Tom Hastings 3954 Xerox Corporation 3955 737 Hawaii St. ESAE 231 3956 El Segundo, CA 90245 3958 Phone: 310-333-6413 3959 Fax: 310-333-5514 3960 e-mail: hastings@cp10.es.xerox.com 3962 Scott A. Isaacson 3963 Novell, Inc. 3964 122 E 1700 S 3965 Provo, UT 84606 3967 Phone: 801-861-7366 3968 Fax: 801-861-2517 3969 e-mail: sisaacson@novell.com 3971 Roger deBry 3972 Utah Valley State College 3973 Orem, UT 84058 3975 Phone: (801) 222-8000 3976 EMail: debryro@uvsc.edu 3978 Jay Martin 3979 Underscore Inc. 3980 9 Jacqueline St. 3981 Hudson, NH 03051-5308 3982 603-889-7000 3983 fax: 775-414-0245 3984 e-mail: jkm@underscore.com 3986 Michael Shepherd 3987 Xerox Corporation 3988 800 Phillips Road MS 128-51E 3989 Webster, NY 14450 3991 Phone: 716-422-2338 3992 Fax: 716-265-8871 3993 e-mail: mshepherd@crt.xerox.com 3995 Ron Bergman 3996 Hitachi Koki Imaging Solutions 3997 1757 Tapo Canyon Road 3998 Simi Valley, CA 93063-3394 4000 Phone: 805-578-4421 4001 Fax: 805-578-4001 4002 Email: rbergma@hitachi-hkis.com 4003 IPP Web Page: http://www.pwg.org/ipp/ 4004 IPP Mailing List: ipp@pwg.org 4006 To subscribe to the ipp mailing list, send the following email: 4007 1) send it to majordomo@pwg.org 4008 2) leave the subject line blank 4009 3) put the following two lines in the message body: 4010 subscribe ipp 4011 end 4013 Implementers of this specification document are encouraged to join 4014 the IPP Mailing List in order to participate in any discussions of 4015 clarification issues and review of registration proposals for 4016 additional attributes and values. In order to reduce spam the 4017 mailing list rejects mail from non-subscribers, so you must subscribe 4018 to the mailing list in order to send a question or comment to the 4019 mailing list. 4021 A. Appendix - Model for Notification with Cascading Printers 4023 With this model (see Figure 2), there is an intervening Print server 4024 between the human user and the output-device. So the system 4025 effectively has two Printers. There are two cases to consider. 4027 1.When the Printer 1 (in the server) generates Events, the system 4028 behaves like the client and Printer in Figure 1. In this case, 4029 Printer 1 sends Event Notifications that are shown as Event 4030 Notifications (A) of Figure 2,. 4032 2.When the Printer 2 (in the output-device) generates Events, there 4033 are two possible system configurations: 4035 a)Printer 1 forwards the client-supplied Subscription Creation 4036 Operations to the downstream Printer 2 and lets Printer 2 send 4037 the Event Notifications directly to the Notification Recipients 4038 supplied by the Client (Event Notifications(C) in the diagram). 4040 b)Printer 1 performs the client-supplied Subscription Creation 4041 Operations and also forwards the Subscription Creation 4042 Operations to Printer 2 with the Notification Recipient changed 4043 to be the Printer 1. When an Event occurs in Printer 2, Printer 4044 2 sends the Event Notification (B) to Notification Recipient of 4045 Printer 1, which relays the received Event Notification (B) to 4046 the client-supplied Notification Recipient (as Event 4047 Notifications(A) in the diagram). Note, when a client performs a 4048 Subscription Creation Operation, Printer 1 need not forward the 4049 Subscription Creation Operation to Printer 2 if it would create 4050 a duplicate Subscription Object on Printer 2. 4052 Note: when Printer 1 is forwarding Subscription Creation Operations 4053 to Printer 2, it may request Printer 2 to create additional 4054 Subscription Objects (called "piggy-backing"). Piggy-backing is 4055 useful when: 4057 - Device A is configured to accept (IPP or non-IPP) requests from 4058 other servers. 4060 - Server S wants to receive Job Events that the client didn't 4061 request and Server S wants these Events for jobs it submits and 4062 not for other jobs. 4064 server S device A 4065 +------------+ +------------+ 4066 | | | | 4067 +--------+ Subscription | ###########| | ###########| 4068 | client |--Creation ----># Printer #| Subscription | # Printer #| 4069 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 4070 | ###|#######| Operation | ####|#|####| 4071 +----|---^---+ +-----|-|----+ 4072 +--------+ Event | | | | 4073 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 4074 |ation Re|<-------------Event Notifications(C)-----------------+ 4075 |cipient | 4076 +--------+ 4078 Figure 2 - Model for Notification with Cascading Printers 4080 B. Appendix - Distributed Model for Notification 4082 A Printer implementation could use some other remote notification 4083 service to provide some or most of the service. For example, the 4084 remote notification service could send Event Notifications using 4085 Delivery Methods that are not directly supported by the output device 4086 or server. Or, the remote notification service could store 4087 Subscription Objects (passed to it from the output device in response 4088 to Subscription Creation requests), accept Events, format the Event 4089 Notification in the natural language of the Notification Recipient, 4090 and send the Event Notifications to the Notification Recipient(s). 4092 Figure 3 shows this partitioning. The interface between the output 4093 device (or server) and the remote notification service is outside the 4094 scope of this document and is intended to be transparent to the 4095 client and this document. The combination of the output device (or 4096 server) and the notification service together constitute an IPP 4097 Printer conforming to this Notification document. 4099 *********************** 4100 * 4101 * Printer (including 4102 * the distributed 4103 * Notification Service) 4104 * 4105 * output device or server 4106 * +---------------+ 4107 PDA, desktop, or server * + ########### + 4108 +--------+ * | # partial # | 4109 | client |---IPP Subscription--------># Printer # | 4110 +--------+ Creation operation * | # Object # | 4111 * | #####|##### | 4112 * +-------|-------+ 4113 * | Subscriptions 4114 * | OR Event 4115 +------------+ * | Notifications 4116 |Notification| IPP-defined * +------v--------+ 4117 |Recipient |<--Event Notifications---| Notification | 4118 +------------+ * | Service | 4119 * +---------------+ 4120 * 4121 ************************* 4122 *** = Implementation configuration opaque boundary 4124 Figure 3 - Opaque Use of a Notification Service Transparent to the 4125 Client 4127 C. Appendix - Extended Notification Recipient 4129 The model allows for an extended Notification Recipient that is 4130 itself a notification service that forwards each Event Notification 4131 to another recipient (called the Ultimate Notification Recipient in 4132 this section). The Delivery Method to the Ultimate Recipient is 4133 probably different from the Delivery Method used by the Printer to 4134 the extended Notification Recipient. 4136 This extended Notification Recipient is transparent to the Printer 4137 but not to the client. 4139 When a client performs a Subscription Creation Operation, it 4140 specifies the extended Notification Recipient as it would any 4141 Notification Recipient. In addition, the client specifies the 4142 Ultimate Notification Recipient in the Subscription Creation 4143 Operation in a manner specified by the extended Notification 4144 Recipient. Typically, it is either some bytes in the value of 4145 "notify-user-data" or some additional parameter in the value of 4146 "notify-recipient-uri". The client also subscribes directly with the 4147 extended Notification Recipient (by means outside this document), 4148 since it is a notification service in its own right. 4150 The IPP Printer treats the extended Notification Recipient like any 4151 other Notification Recipient and the IPP Printer is not aware of the 4152 forwarding. The Delivery Method that the extended Notification 4153 Recipient uses for delivering the Event Notification to the Ultimate 4154 Notification Recipient is beyond the scope of this document and is 4155 transparent to the IPP Printer. 4157 Examples of this extended Notification Recipient are paging, 4158 immediate messaging services, general notification services, and NOS 4159 vendors' infrastructure. Figure 4 shows this approach. 4161 PDA, desktop, or server server or output device 4162 +---------------+ 4163 +--------+ | ########### | 4164 | client |---Subscription Creation -----------># Printer # | 4165 +--------+ Operation | # Object # | 4166 | #####|##### | 4167 +------------+ +------------+ IPP-defined +-------|-------+ 4168 |Ultimate | any |Notification|<--Event Notifications----+ 4169 |Notification|<----|Recipient | 4170 |Recipient | +------------+ 4171 +------------+ (Notification Service) 4173 Figure 4 - Use of an Extended Notification Recipient transparent to 4174 the Printer 4176 D. Appendix - Details about Conformance Terminology 4178 The following paragraphs provide more details about conformance 4179 terminology. 4181 REQUIRED - an adjective used to indicate that a conforming IPP 4182 Printer implementation MUST support the indicated operation, 4183 object, attribute, attribute value, status code, or out-of-band 4184 value in requests and responses. See [RFC2911] "Appendix A - 4185 Terminology for a definition of "support". Since support of this 4186 entire Notification specification is OPTIONAL for conformance to 4187 IPP/1.0 or IPP/1.1, the use of the term REQUIRED in this document 4188 means "REQUIRED if this OPTIONAL Notification specification is 4189 implemented". 4191 RECOMMENDED - an adjective used to indicate that a conforming IPP 4192 Printer implementation is recommended to support the indicated 4193 operation, object, attribute, attribute value, status code, or 4194 out-of-band value in requests and responses. Since support of 4195 this entire Notification specification is OPTIONAL for conformance 4196 to IPP/1.0 or IPP/1.1, the use of the term RECOMMENDED in this 4197 document means "RECOMMENDED if this OPTIONAL Notification 4198 specification is implemented". 4200 OPTIONAL - an adjective used to indicate that a conforming IPP 4201 Printer implementation MAY, but is NOT REQUIRED to, support the 4202 indicated operation, object, attribute, attribute value, status 4203 code, or out-of-band value in requests and responses. 4205 E. Appendix - Object Model for Notification 4207 This section describes the Notification object model that adds a 4208 Subscription Object which together with the Job and Printer object 4209 provide the complete Notification semantics. 4211 The object relationships can be seen pictorially as: 4213 Subscription Objects (Per-Printer Subscriptions) Printer object 4214 +----+ +------------+ 4215 | s1 |<--------------------------------------------->| | 4216 +----++ | | 4217 | s2 |<-------------------------------------------->| p1 | 4218 +----++ | | 4219 | s3 |<------------------------------------------->| | 4220 +----+ +------------+ 4221 Job objects 4222 +---------+ 4223 | | 4224 +----+ | j1 | 4225 | s4 |<------->| | 4226 +----+ | | 4227 | | s4 is a Per-Job Subscription Object 4228 ++--------++ 4229 | | 4230 +----+ | j2 | 4231 | s5 |<------>| | 4232 +----++ | | 4233 | s6 |<----->| | s5 and s6 are Per-Job Subscription 4234 +----+ ++--------++ Objects 4235 | | 4236 | j3 | 4237 | | 4238 | | <----> indicates association 4239 +---------+ 4241 Figure 5 - Object Model for Notification 4243 s1, s2, and s3 are Per-Printer Subscription Objects and can 4244 identify Printer and/or Job Events. 4245 s4, s5, and s6 are Per-Job Subscription Objects and can identify 4246 Printer and/or Job Events. 4248 E.1 Appendix - Object relationships 4250 This sub-section defines the object relationships between the 4251 Printer, Job, and Subscription Objects by example. Whether Per- 4252 Printer Subscription Objects are actually contained in a Printer 4253 object or are just bi-directionally associated with them in some way 4254 is IMPLEMENTATION DEPENDENT and is transparent to the client. 4255 Similarly, whether Per-Job Subscription Objects are actually 4256 contained in a Job object or are just bi-directionally associated 4257 with them in some way is IMPLEMENTATION DEPENDENT and is transparent 4258 to the client. The object relationships are defined as follows: 4260 E.2 Printer Object and Per-Printer Subscription Objects 4262 1.The Printer object contains (is associated with) zero or more 4263 Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer 4264 Subscription Objects). 4266 2.Each Per-Printer Subscription Object (s1, s2, and s3) is 4267 contained in (or is associated with) exactly one Printer object 4268 (p1). 4270 E.3 Job Object and Per-Job Subscription Objects 4272 1.A Job object (j1, j2, j3) is associated with zero or more Per- 4273 Job Subscription Objects (s4-s6). Job j1 is associated with 4274 Per-Job Subscription Object s4, Job j2 is associated with Per- 4275 Job Subscription Objects s5 and s6, and Job j3 is not associated 4276 with any Per-Job Subscription Object. 4278 2.Each Per-Job Subscription Object is associated with exactly one 4279 Job object. 4281 F. Appendix - Per-Job versus Per-Printer Subscription Objects 4283 Per-Job and Per-Printer Subscription Objects are quite similar. 4284 Either type of Subscription Object can subscribe to Job Events, 4285 Printer Events, or both. Both types of Subscription Objects can be 4286 queried using the Get-Subscriptions and Get-Subscription-Attributes 4287 operations and canceled using the Cancel-Subscription operation. 4288 Both types of Subscription Objects create Subscription Objects which 4289 have the same Subscription Object attributes defined. However, there 4290 are some semantic differences between Per-Job Subscription Objects 4291 and Per-Printer Subscription Objects. A Per-Job Subscription Object 4292 is established by the client when submitting a job and after creating 4293 the job using the Create-Job-Subscriptions operation by specifying 4294 the "job-id" of the Job with the "notify-job-id" attribute. A Per- 4295 Printer Subscription Object is established between a client and a 4296 Printer using the Create-Printer-Subscriptions operation. Some 4297 specific differences are: 4299 1.A client usually creates one or more Per-Job Subscription 4300 Objects as part of the Job Creation operations (Create-Job, 4301 Print-Job, and Print-URI), rather than using the OPTIONAL 4302 Create-Job-Subscriptions operation, especially since Printer 4303 implementations NEED NOT support the Create-Job-Subscriptions 4304 operation, since it is OPTIONAL. 4306 2.For Per-Job Subscription Objects, the Subscription Object is 4307 only valid while the job is "not-complete" (see sections 5.4.3) 4308 while for the Per-Printer Subscription Objects, the Subscription 4309 Object is valid until the time (in seconds) that the Printer 4310 returned in the "notify-lease-expiration-time" operation 4311 attribute. 4313 3.Job Events in a Per-Job Subscription Object apply only to "one 4314 job" (the Job created by the Job Creation operation or 4315 references by the Create-Job-Subscriptions operation) while Job 4316 Events in a Per-Printer Subscription Object apply to ALL jobs 4317 contained in the IPP Printer. 4319 G. Appendix - Description of the base IPP documents 4321 The base set of IPP documents includes: 4323 Design Goals for an Internet Printing Protocol [RFC2567] 4324 Rationale for the Structure and Model and Protocol for the Internet 4325 Printing Protocol [RFC2568] 4326 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 4327 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 4328 Internet Printing Protocol/1.1: Implementer's Guide [IPP-IIG] 4329 Mapping between LPD and IPP Protocols [RFC2569] 4331 The "Design Goals for an Internet Printing Protocol" document takes a 4332 broad look at distributed printing functionality, and it enumerates 4333 real-life scenarios that help to clarify the features that need to be 4334 included in a printing protocol for the Internet. It identifies 4335 requirements for three types of users: end users, operators, and 4336 administrators. It calls out a subset of end user requirements that 4337 are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator 4338 operations have been added to IPP/1.1 [RFC2911, RFC2910]. 4340 The "Rationale for the Structure and Model and Protocol for the 4341 Internet Printing Protocol" document describes IPP from a high level 4342 view, defines a roadmap for the various documents that form the suite 4343 of IPP specification documents, and gives background and rationale 4344 for the IETF IPP working group's major decisions. 4346 The "Internet Printing Protocol/1.1: Model and Semantics" document 4347 describes a simplified model with abstract objects, their attributes, 4348 and their operations. The model introduces a Printer and a Job. The 4349 Job supports multiple documents per Job. The model document also 4350 addresses how security, internationalization, and directory issues 4351 are addressed. 4353 The "Internet Printing Protocol/1.1: Encoding and Transport" document 4354 is a formal mapping of the abstract operations and attributes defined 4355 in the model document onto HTTP/1.1 [RFC2616]. It also defines the 4356 encoding rules for a new Internet MIME media type called 4357 "application/ipp". This document also defines the rules for 4358 transporting over HTTP a message body whose Content-Type is 4359 "application/ipp". This document defines the 'ipp' scheme for 4360 identifying IPP printers and jobs. 4362 The "Internet Printing Protocol/1.1: Implementer's Guide" document 4363 gives insight and advice to implementers of IPP clients and IPP 4364 objects. It is intended to help them understand IPP/1.1 and some of 4365 the considerations that may assist them in the design of their client 4366 and/or IPP object implementations. For example, a typical order of 4367 processing requests is given, including error checking. Motivation 4368 for some of the specification decisions is also included. 4370 The "Mapping between LPD and IPP Protocols" document gives some 4371 advice to implementers of gateways between IPP and LPD (Line Printer 4372 Daemon) implementations. 4374 H. Appendix - Full Copyright Statement 4376 Copyright (C) The Internet Society (1998,1999,2000,2001). All Rights 4377 Reserved 4379 This document and translations of it may be copied and furnished to 4380 others, and derivative works that comment on or otherwise explain it 4381 or assist in its implementation may be prepared, copied, published 4382 and distributed, in whole or in part, without restriction of any 4383 kind, provided that the above copyright notice and this paragraph are 4384 included on all such copies and derivative works. However, this 4385 document itself may not be modified in any way, such as by removing 4386 the copyright notice or references to the Internet Society or other 4387 Internet organizations, except as needed for the purpose of 4388 developing Internet standards in which case the procedures for 4389 copyrights defined in the Internet Standards process must be 4390 followed, or as required to translate it into languages other than 4391 English. 4393 The limited permissions granted above are perpetual and will not be 4394 revoked by the Internet Society or its successors or assigns. 4396 This document and the information contained herein is provided on an 4397 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4398 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4399 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4400 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4401 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4403 Acknowledgement 4405 Funding for the RFC Editor function is currently provided by the 4406 Internet Society.