idnits 2.17.1 draft-ietf-ipp-not-spec-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 7 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 3860 has weird spacing: '...reation opera...' == Line 4243 has weird spacing: '...FC xxxx m.n...' == Line 4258 has weird spacing: '...FC xxxx m.n...' == 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 (February 21, 2003) is 7728 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: 'RFCNNNN' is mentioned on line 4100, but not defined ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2717 (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2910 (Obsoleted by RFC 8010) ** Obsolete normative reference: RFC 2911 (Obsoleted by RFC 8011) ** Obsolete normative reference: RFC 3381 (Obsoleted by RFC 8011) -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. 'IANA-CON') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 2565 (Obsoleted by RFC 2910) -- Obsolete informational reference (is this intentional?): RFC 2566 (Obsoleted by RFC 2911) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 8 errors (**), 0 flaws (~~), 8 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Printing Protocol WG R. Herriot 3 INTERNET-DRAFT consultant 4 T. Hastings 5 Updates RFC 2910 and 2911 Xerox Corporation 6 [Target Category: standards track] February 21, 2003 7 Expires: August 21, 2003 9 Internet Printing Protocol (IPP): 10 Event Notifications and Subscriptions 12 Copyright (C) The Internet Society (2003). All Rights Reserved. 14 Status of this Memo 16 This document is an Internet-Draft and is in full conformance with 17 all provisions of Section 10 of RFC 2026. Internet-Drafts are 18 working documents of the Internet Engineering Task Force (IETF), its 19 areas, and its working groups. Note that other groups may also 20 distribute working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress". 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.html 29 The list of Internet-Draft Shadow Directories can be accessed as 30 http://www.ietf.org/shadow.html. 32 Abstract 34 This document describes an OPTIONAL extension to the Internet 35 Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). 36 This extension allows a client to subscribe to printing related 37 Events. Subscriptions are modeled as Subscription Objects. The 38 Subscription Object specifies that when one of the specified Events 39 occurs, the Printer delivers an asynchronous Event Notification to 40 the specified Notification Recipient via the specified Push or Pull 41 Delivery Method (i.e., protocol). 43 A client associates Subscription Objects with a particular Job by 44 performing the Create-Job-Subscriptions operation or by submitting a 45 Job with subscription information. A client associates Subscription 46 Objects with the Printer by performing a Create-Printer-Subscriptions 47 operation. Four other operations are defined for Subscription 48 Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- 49 Subscription, and Cancel-Subscription. 51 Table of Contents 53 1 Introduction.....................................................7 54 1.1 Notification Overview..........................................7 56 2 Models for Notification.........................................10 57 2.1 Model for Simple Notification (Normative).....................10 58 2.2 Additional Models for Notification (Informative)..............11 60 3 Terminology.....................................................11 61 3.1 Conformance Terminology.......................................11 62 3.2 Other Terminology.............................................11 64 4 Object Relationships............................................14 65 4.1 Printer and Per-Printer Subscription Objects..................14 66 4.2 Printer, Job and Per-Job Subscription Objects.................14 68 5 Subscription Object.............................................15 69 5.1 Rules for Support of Subscription Template Attributes.........15 70 5.2 Rules for Processing Subscription Template Attributes.........16 71 5.3 Subscription Template Attributes..............................20 72 5.3.1 notify-recipient-uri (uri)..................................22 73 5.3.1.1 notify-schemes-supported (1setOf uriScheme)..............23 74 5.3.2 notify-pull-method (type2 keyword)..........................23 75 5.3.2.1 notify-pull-method-supported (1setOf type2 keyword).......24 76 5.3.3 notify-events (1setOf type2 keyword)........................24 77 5.3.3.1 notify-events-default (1setOf type2 keyword)..............24 78 5.3.3.2 notify-events-supported (1setOf type2 keyword)............25 79 5.3.3.3 notify-max-events-supported (integer(2:MAX))..............25 80 5.3.3.4 Standard Values for Subscribed Events.....................25 81 5.3.3.4.1 No Events...............................................25 82 5.3.3.4.2 Subscribed Printer Events...............................26 83 5.3.3.4.3 Subscribed Job Events...................................27 84 5.3.3.5 Rules for Matching of Subscribed Events...................28 85 5.3.3.5.1 Rules for Matching of Printer Events....................29 86 5.3.3.5.2 Rules for Matching of Job Events........................29 87 5.3.3.5.3 Special Cases for Matching Rules........................30 88 5.3.4 notify-attributes (1setOf type2 keyword)....................31 89 5.3.4.1 notify-attributes-supported (1setOf type2 keyword)........32 90 5.3.5 notify-user-data (octetString(63))..........................32 91 5.3.6 notify-charset (charset)....................................33 92 5.3.7 notify-natural-language (naturalLanguage)...................33 93 5.3.8 notify-lease-duration (integer(0:67108863)).................34 94 5.3.8.1 notify-lease-duration-default (integer(0:67108863)).......35 95 5.3.8.2 notify-lease-duration-supported (1setOf (integer(0: 67108863) 96 | rangeOfInteger(0:67108863)))....................................35 97 5.3.9 notify-time-interval (integer(0:MAX)).......................35 98 5.4 Subscription Description Attributes...........................36 99 5.4.1 notify-subscription-id (integer (1:MAX))...................37 100 5.4.2 notify-sequence-number (integer (0:MAX))....................37 101 5.4.3 notify-lease-expiration-time (integer(0:MAX))...............38 102 5.4.4 notify-printer-up-time (integer(1:MAX)).....................39 103 5.4.5 notify-printer-uri (uri)....................................39 104 5.4.6 notify-job-id (integer(1:MAX))..............................40 105 5.4.7 notify-subscriber-user-name (name(MAX)).....................40 107 6 Printer Description Attributes Related to Notification..........41 108 6.1 printer-state-change-time (integer(1:MAX))....................41 109 6.2 printer-state-change-date-time (dateTime).....................41 111 7 New Values for Existing Printer Description Attributes..........42 112 7.1 operations-supported (1setOf type2 enum)......................42 114 8 Attributes Only in Event Notifications..........................42 115 8.1 notify-subscribed-event (type2 keyword).......................43 116 8.2 notify-text (text(MAX)).......................................43 118 9 Event Notification Content......................................43 119 9.1 Content of Machine Consumable Event Notifications.............46 120 9.1.1 Event Notification Content Common to All Events.............47 121 9.1.2 Additional Event Notification Content for Job Events........49 122 9.1.3 Additional Event Notification Content for Printer Events....50 123 9.2 Content of Human Consumable Event Notification................50 124 9.2.1 Event Notification Content Common to All Events.............51 125 9.2.2 Additional Event Notification Content for Job Events........53 126 9.2.3 Additional Event Notification Content for Printer Events....54 128 10 Delivery Methods...............................................54 130 11 Operations for Notification....................................57 131 11.1 Subscription Creation Operations.............................57 132 11.1.1 Create-Job-Subscriptions Operation.........................57 133 11.1.1.1 Create-Job-Subscriptions Request.........................58 134 11.1.1.1.1 notify-job-id (integer(1:MAX)).........................58 135 11.1.1.2 Create-Job-Subscriptions Response........................59 136 11.1.2 Create-Printer-Subscriptions operation.....................60 137 11.1.2.1 Create-Printer-Subscriptions Request.....................60 138 11.1.2.2 Create-Printer-Subscriptions Response....................61 139 11.1.3 Job Creation Operations - Extensions for Notification......61 140 11.1.3.1 Job Creation Request.....................................62 141 11.1.3.2 Job Creation Response....................................62 142 11.2 Other Operations.............................................63 143 11.2.1 Restart-Job Operation - Extensions for Notification........63 144 11.2.2 Validate-Job Operation - Extensions for Notification.......64 145 11.2.3 Get-Printer-Attributes - Extensions for Notification.......64 146 11.2.4 Get-Subscription-Attributes operation......................65 147 11.2.4.1 Get-Subscription-Attributes Request......................65 148 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)).............66 149 11.2.4.1.2 "requested-attributes" (1setOf keyword)................66 150 11.2.4.2 Get-Subscription-Attributes Response.....................66 151 11.2.5 Get-Subscriptions operation................................68 152 11.2.5.1 Get-Subscriptions Request................................68 153 11.2.5.1.1 "notify-job-id" (integer(1:MAX)).......................69 154 11.2.5.1.2 "limit" (integer(1:MAX))...............................69 155 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword)..........69 156 11.2.5.1.4 "my-subscriptions" (boolean)...........................70 157 11.2.5.2 Get-Subscriptions Response...............................70 158 11.2.6 Renew-Subscription operation...............................71 159 11.2.6.1 Renew-Subscription Request...............................71 160 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)).............72 161 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX))...............72 162 11.2.6.2 Renew-Subscription Response..............................72 163 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX))...............73 164 11.2.7 Cancel-Subscription operation..............................73 165 11.2.7.1 Cancel-Subscription Request..............................74 166 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)).............74 167 11.2.7.2 Cancel-Subscription Response.............................75 169 12 Status Codes...................................................75 170 12.1 successful-ok-ignored-subscriptions (0x0003).................75 171 12.2 client-error-ignored-all-subscriptions (0x0414)..............76 173 13 Status Codes in Subscription Attributes Groups.................76 174 13.1 client-error-uri-scheme-not-supported (0x040C)...............76 175 13.2 client-error-attributes-or-values-not-supported (0x040B).....77 176 13.3 client-error-too-many-subscriptions (0x0415).................77 177 13.4 successful-ok-too-many-events (0x0005).......................77 178 13.5 successful-ok-ignored-or-substituted-attributes (0x0001).....77 180 14 Encodings of Additional Attribute Tags.........................77 182 15 Conformance Requirements.......................................78 183 15.1 Conformance requirements for clients.........................78 184 15.2 Conformance requirements for Printers........................78 186 16 Appendix A - Model for Notification with Cascading Printers 187 (Informative).....................................................79 189 17 Appendix B - Distributed Model for Notification (Informative)..81 191 18 Appendix C - Extended Notification Recipient (Informative).....82 193 19 Appendix D - Details about Conformance Terminology (Normative).83 195 20 Appendix E - Object Model for Notification (Normative).........83 196 20.1 Object relationships.........................................84 197 20.2 Printer Object and Per-Printer Subscription Objects..........85 198 20.3 Job Object and Per-Job Subscription Objects..................85 200 21 Appendix F - Per-Job versus Per-Printer Subscription Objects 201 (Normative).......................................................85 203 22 Normative References...........................................86 205 23 Informative References.........................................87 207 24 IANA Considerations............................................87 208 24.1 Attribute Registrations......................................88 209 24.2 Additional Enum Attribute Value Registrations................89 210 24.3 Operation Registrations......................................89 211 24.4 Status code Registrations....................................90 212 24.5 Attribute Group tag Registrations............................90 213 24.6 Registration of Events.......................................90 214 24.7 Registration of Event Notification Delivery Methods..........91 215 24.7.1 Requirements for Registration of Event Notification Delivery 216 Methods................................................91 217 24.7.1.1 Required Characteristics.................................91 218 24.7.1.2 Naming Requirements......................................92 219 24.7.1.3 Functionality Requirements...............................92 220 24.7.1.4 Usage and Implementation Requirements....................92 221 24.7.1.5 Publication Requirements.................................93 222 24.7.2 Registration Procedure.....................................93 223 24.7.2.1 Present the proposal to the Community....................93 224 24.7.2.2 Delivery Method Reviewer.................................93 225 24.7.2.3 IANA Registration........................................94 226 24.7.3 Delivery Method Document Registrations.....................94 227 24.7.4 Registration Template......................................95 229 25 Intellectural Property.........................................95 231 26 Internationalization Considerations............................96 233 27 Security Considerations........................................96 234 27.1 Client access rights.........................................96 235 27.2 Printer security threats.....................................98 236 27.3 Notification Recipient security threats......................98 238 28 Contributors...................................................99 240 29 Author's Addresses............................................100 242 30 Appendix G - Description of the base IPP documents (Informative) 243 101 245 31 Appendix H - Full Copyright Statement (Informative)...........102 247 Tables 248 Table 1 - Subscription Template Attributes........................22 249 Table 2 - Subscription Description Attributes.....................37 250 Table 3 - Printer Description Attributes Associated with Notification 251 ..............................................................41 252 Table 4 - Operation-id assignments................................42 253 Table 5 - Attributes in Event Notification Content................48 254 Table 6 - Additional Event Notification Content for Job Events....49 255 Table 7 - Combinations of Events and Subscribed Events for "job- 256 impressions-completed" ........................................49 257 Table 8 - Additional Event Notification Content for Printer Events50 258 Table 9 - Printer Name in Event Notification Content..............52 259 Table 10 - Event Name in Event Notification Content...............52 260 Table 11 - Event Time in Event Notification Content...............52 261 Table 12 - Job Name in Event Notification Content.................53 262 Table 13 - Job State in Event Notification Content................53 263 Table 14 - Printer State in Event Notification Content............54 264 Table 15 - Information about the Delivery Method..................55 265 Table 16 - Printer Conformance Requirements for Operations........79 267 Figures 268 Figure 1 - Model for Notification.................................10 269 Figure 2 - Model for Notification with Cascading Printers.........80 270 Figure 3 - Opaque Use of a Notification Server Transparent to the 271 Client ........................................................81 272 Figure 4 - Use of an Extended Notification Recipient transparent to 273 the Printer ...................................................82 274 Figure 5 - Object Model for Notification..........................84 276 1 Introduction 278 This IPP notification specification is an OPTIONAL extension to 279 Internet Printing Protocol/1.1: Model and Semantics [RFC2911, 280 RFC2910]. See Appendix 30 for a description of the base IPP 281 documents. This document in combination with the following documents 282 is intended to meet the most important notification requirements 283 described in [ipp-not-req]: 285 Internet Printing Protocol (IPP): "Job Progress Attributes" 286 [RFC3381] 287 Internet Printing Protocol (IPP): "The 'ippget' Delivery Method 288 for Event Notifications" [ipp-get-method] 290 This specification REQUIRES that clients and Printers support the 291 'ippget' Pull Delivery Method [ipp-get-method]. Conforming client 292 and Printer implementations MAY support additional Push or Pull 293 Delivery Methods as well. Note: this document does not define any 294 Delivery Methods itself, but it does define the rules for conformance 295 for Delivery Method Documents and their registration with IANA (see 296 section 24.7.3). 298 Refer to the Table of Contents for the layout of this document. 300 1.1 Notification Overview 302 This document defines operations that a client can perform in order 303 to create Subscription Objects in a Printer and carry out other 304 operations on them. A Subscription Object represents a Subscription 305 abstraction. The Subscription Object specifies that when one of the 306 specified Events occurs, the Printer delivers an asynchronous Event 307 Notification to the specified Notification Recipient via the 308 specified Delivery Method (i.e., protocol). 310 When a client (called a Subscribing Client) performs an operation 311 that creates a Subscription Object, the operation contains one or 312 more Subscription Template Attributes Groups. Each such group holds 313 information used by the Printer to initialize a newly created 314 Subscription Object. The Printer creates one Subscription Object for 315 each Subscription Template Attributes Group in the operation. This 316 group is like the Job Template Attributes group defined in [RFC2911]. 317 The following is an example of the information included in a 318 Subscription Template Attributes Group (see section 5 for details on 319 the Subscription Object attributes): 321 1.The names of Subscribed Events that are of interest to the 322 Notification Recipient. 324 2.The address (URL) of one Notification Recipient for a Push 325 Delivery Method or the method for a Pull Delivery Method. 326 3.The Delivery Method (i.e., the protocol) which the Printer uses 327 to deliver the Event Notification. 328 4.Some opaque data that the Printer delivers to the Notification 329 Recipient in the Event Notification. For example, the 330 Notification Recipient might use this opaque data as a 331 forwarding address for the Event Notification. 332 5.The charset to use in text fields within an Event Notification 333 6.The natural language to use in the text fields of the Event 334 Notification 335 7.The requested lease time in seconds for the Subscription Object 336 An operation that creates a Subscription Object is called a 337 Subscription Creation Operation. These operations include the 338 following operations (see section 11.1 for further details): 340 - Job Creation operation: When a client performs such an 341 operation (Print-Job, Print-URI, and Create-Job), a client can 342 include zero or more Subscription Template Attributes Groups in 343 the request. The Printer creates one Subscription Object for 344 each Subscription Template Attributes Group in the request, and 345 the Printer associates each such Subscription Object with the 346 newly created Job. This document extends these operations' 347 definitions in [RFC2911] by adding Subscription Template 348 Attributes Groups in the request and Subscription Attributes 349 Groups in the response. 351 - Create-Job-Subscriptions operation: A client can include one or 352 more Subscription Template Attributes Groups in the request. 353 The Printer creates one Subscription Object for each 354 Subscription Template Attributes Group and associates each with 355 the job that is the target of this operation. 357 - Create-Printer-Subscriptions operation: A client can include 358 one or more Subscription Template Attributes Groups in the 359 request. The Printer creates one Subscription Object for each 360 Subscription Template Attributes Group and associates each with 361 the Printer that is the target of this operation. 363 For each of the above operations: 365 - the Printer associates a Subscription Object with the Printer 366 or a specific Job. When a Subscription Object is associated 367 with a Job Object, it is called a Per-Job Subscription Object. 368 When a Subscription Object is associated with a Printer Object, 369 it is called a Per-Printer Subscription Object. 371 - the response contains one Subscription Attributes Group for 372 each Subscription Template Attributes Group in the request and 373 in the same order. When the Printer successfully creates a 374 Subscription Object, its corresponding Subscription Attributes 375 Group contains the "notify-subscription-id" attribute. This 376 attribute uniquely identifies the Subscription Object and is 377 analogous to a "job-id" for a Job object. Some operations 378 described below use the "notify-subscription-id" to identify 379 the target Subscription Object. 381 This document defines the following additional operations (see 382 section 11.2 for further details): 384 - Restart-Job operation: When a client performs the Restart-Job 385 operation [RFC2911], the Printer re-uses the same Job and its 386 Subscription Objects. 388 - Validate-Job operation: When a client performs this operation, 389 a client can include zero or more Subscription Template 390 Attributes Groups in the request. The Printer determines if it 391 could create one Subscription Object for each Subscription 392 Template Attributes Group in the request. This document 393 extends this operation's definition in [RFC2911] by adding 394 Subscription Template Attributes Groups in the request and 395 Subscription Attributes Groups in the response. 397 - Get-Subscription-Attributes operation: This operation allows a 398 client to obtain the specified attributes of a target 399 Subscription Object. 401 - Get-Subscriptions operation: This operation allows a client to 402 obtain the specified attributes of all Subscription Objects 403 associated with the Printer or a specified Job. 405 - Renew-Subscription operation: This operation renews the lease 406 on the target Per-Printer Subscription Object before it 407 expires. A newly created Per-Printer Subscription Object 408 receives an initial lease. It is the duty of the client to use 409 this operation frequently enough to preserve a Per-Printer 410 Subscription Object. The Printer deletes a Per-Printer 411 Subscription Object when its lease expires. A Per-Job 412 Subscription Object last exactly as long as its associated Job 413 Object and thus doesn't have a lease. 415 - Cancel-Subscription operation: This operation (1) cancels the 416 lease on the specified Per-Printer Subscription Object and 417 thereby deletes the Per-Printer Subscription Object or (2) 418 deletes the Per-Job Subscription Object. 420 When an Event occurs, the Printer finds all Subscription Objects 421 listening for the Event (see section 9 for details on finding such 422 Subscription Objects). For each such Subscription Object, the 423 Printer: 425 a)generates an Event Notification with information specified in 426 section 9, AND 427 b)either: 428 i) If the Delivery Method is a Push Delivery Method as 429 indicated by the presence of the Subscription Object's 430 "notify-recipient-uri" attribute, delivers the Event 431 Notification using the Delivery Method and target address 432 identified in the Subscription Object's "notify-recipient- 433 uri" attribute, OR 434 ii) If the Delivery Method is a Pull Delivery Method as 435 indicated by the presence of the Subscription Object's 436 "notify-pull-method" attribute, saves Event Notification 437 for a time period called the Event Life defined by the 438 Delivery Method, i.e., the Notification Recipient is 439 expected to fetch the Event Notifications. 441 2 Models for Notification 443 2.1 Model for Simple Notification (Normative) 445 As part of a Subscription Creation Operation, an IPP Printer (i.e., 446 located in an output device or a server) creates one or more 447 Subscription Objects. In a Subscription Creation Operation, the 448 client specifies the Notification Recipient to which the Printer is 449 to deliver Event Notifications. A Notification Recipient can be the 450 Subscribing Client or a third party. 452 Figure 1 shows the Notification model for a simple Client-Printer 453 relationship. 455 embedded printer: 456 output device or server 457 PDA, desktop, or server +---------------+ 458 +--------+ | ########### | 459 | client |-----Subscription ---------># Printer # | 460 +--------+ Creation Operation | # Object # | 461 +------------+ | #####|##### | 462 |Notification| +-------|-------+ 463 |Recipient |<----IPP Event Notifications----+ 464 +------------+ (Job and/or Printer Events) 466 Figure 1 - Model for Notification 468 2.2 Additional Models for Notification (Informative) 470 Additional models have been proposed (see Appendices 16, 17, and 18). 472 3 Terminology 474 This section defines terminology used throughout this document. 475 Other terminology is defined in [RFC2911]. 477 3.1 Conformance Terminology 479 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 480 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 481 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 482 12.1. If an implementation supports the extension defined in this 483 document, then these terms apply; otherwise, they do not. These 484 terms define conformance to this document only; they do not affect 485 conformance to other documents, unless explicitly stated otherwise. 486 See Appendix 19 for complete details. 488 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 489 the Printer implements a Delivery Method that REQUIRES the feature. 491 READ-ONLY - an adjective used in an attribute definition to indicate 492 that an IPP Printer MUST NOT allow the attribute's value to be 493 modified. 495 3.2 Other Terminology 497 This document uses the same terminology as [RFC2911], such as 498 "client", "Printer", "attribute", "attribute value", "keyword", 499 "operation", "request", "response", "administrator", "operator", and 500 "support". In addition, the following terms are defined for use in 501 this document and the Delivery Method Documents: 503 Compound Event Notification - two or more Event Notifications that a 504 Printer delivers together as a single request or response. The 505 Delivery Method Document specifies whether the Delivery Method 506 supports Compound Event Notifications. 508 Delivery Method - the mechanism by which the Printer delivers an 509 Event Notification. 511 Delivery Method Document - a document, separate from this document, 512 that defines a Delivery Method. 514 Event - some occurrence (either expected or unexpected) within the 515 printing system of a change of state, condition, or configuration of 516 a Job or Printer object. An Event occurs only at one instant in time 517 and does not span the time the physical Event takes place. For 518 example, jam-occurred and jam-cleared are two distinct, instantaneous 519 Events, even though the jam may last for a while. 521 Event Life - For a Pull Delivery Method, the length of time in 522 seconds after an Event occurs during which the Printer will retain 523 that Event for delivery in an Event Notification. After the Event 524 Life expires, the Printer will no longer deliver an Event 525 Notification for that Event in such a response. 527 Event Notification - the information about an Event that the Printer 528 delivers when an Event occurs. 530 Event Notification Attributes Group - The attributes group which is 531 used to deliver an Event Notification in a request (Push 532 Delivery Methods) or a response (Pull Delivery Methods). 534 Human Consumable Event Notification - localized text for human 535 consumption only. There is no standardized format and thus programs 536 should not try to parse this text. 538 Job Creation operation - One of the operations that creates a Job 539 object: Print-Job, Print-URI and Create-Job. The Restart-Job 540 operation [RFC2911] is not considered a Job Creation operation, since 541 the Printer re-uses the existing Job object. The Validate-Job 542 operation is not considered a Job Creation operation because no Job 543 object is created. Therefore, when a statement also applies to 544 either the Restart-Job and/or the Validate-Job operation, they are 545 mentioned explicitly. 547 Job Event - an Event caused by some change in a particular job on the 548 Printer, e.g., 'job-completed'. 550 Machine Consumable Event Notification - bytes for program 551 consumption. The bytes are formatted according to the Delivery 552 Method document. 554 Notification - when not in the phrases 'Event Notification' and 555 'Notification Recipient' - the concepts of this specification, i.e., 556 Events, Subscription Objects, and Event Notifications. 558 Notification Recipient - the entity to which the Printer delivers an 559 Event Notification. For Push Delivery Methods, the IPP Printer sends 560 the Notifications to a Notification Recipient. For Pull Delivery 561 Methods, the Notification Recipient is acting in the role of an IPP 562 client and requests Event Notifications and so the terms "client" and 563 "Notification Recipient" are used interchangeably with such Delivery 564 Methods. For example, see [ipp-get-method]. 566 Per-Job Subscription Object - A Subscription Object that is 567 associated with a single Job. The Create-Job-Subscriptions operation 568 and Job Creation operations create such an object. 570 Per-Printer Subscription Object - A Subscription Object that is 571 associated with the Printer as a whole. The Create-Printer- 572 Subscriptions operation creates such an object. 574 Printer Event - an Event caused by some change in the Printer that is 575 not specific to a job, e.g., 'printer-state-changed'. 577 Pull Delivery Method - The Printer saves Event Notifications for some 578 event life time and expects the Notification Recipient to request 579 Event Notifications. The Printer delivers the Event Notifications in 580 a response to such a request. 582 Push Delivery Method -The Printer delivers the Event Notification 583 shortly after an Event occurs. 585 Subscribed Event - an Event that the Subscribing Client expresses 586 interest in by making it a value of the "notify-events" attribute on 587 a Subscription Object. 589 Subscribed Job Event - a Subscribed Event that is a Job Event. 591 Subscribed Printer Event - a Subscribed Event that is a Printer 592 Event. 594 Subscribing Client - The client that creates the Subscription Object. 596 Subscription Attributes Group - The attributes group in a response 597 that contains Subscription Object attributes. 599 Subscription Creation Operation - An operation that creates a 600 Subscription Object: Job Creation operations, Create-Job- 601 Subscriptions operation, Create-Printer-Subscriptions operation. In 602 the context of a Job Creation operation, a Subscription Creation 603 Operation is the part of the Job Creation operation that creates one 604 or more Subscription objects. The Restart-Job operation [RFC2911] is 605 not considered a Subscription Creation Operation, since the Printer 606 re-uses the Job's existing Subscription Objects, rather than creating 607 any new Subscription Objects. 609 Subscription Creation Request - The request portion of a Subscription 610 Creation Operation. 612 Subscription Description Attributes - Subscription Object attributes 613 that a Printer supplies during a Subscription Creation Operation. 615 Subscription Object - An object containing a set of attributes that 616 indicate: the Notification Recipient (for Push Delivery Method 617 only), the Delivery Method, the Subscribed Events that cause the 618 Printer to deliver an Event Notification, and the information to 619 include in an Event Notification. 621 Subscription Template Attributes - Subscription Object attributes 622 that a client can supply in a Subscription Creation Operation and 623 associated Printer Object attributes that specify supported and 624 default values for the Subscription Object attributes. 626 Subscription Template Attributes Group - The attributes group in a 627 request that contains Subscription Object attributes that are 628 Subscription Template Attributes. 630 4 Object Relationships 632 This section defines the object relationships between the Printer, 633 Job, and Subscription Objects. It does not define the 634 implementation. For an illustration of these relationships, see 635 Appendix 20. 637 4.1 Printer and Per-Printer Subscription Objects 639 1.A Printer object can be associated with zero or more Per-Printer 640 Subscription Objects. 642 2.Each Per-Printer Subscription Object is associated with exactly 643 one Printer object. 645 4.2 Printer, Job and Per-Job Subscription Objects 647 1.A Printer object is associated with zero or more Job objects. 649 2.Each Job object is associated with exactly one Printer object. 651 3.A Job object is associated with zero or more Per-Job Subscription 652 Objects. 654 4.Each Per-Job Subscription Object is associated with exactly one 655 Job object. 657 5 Subscription Object 659 A Subscribing Client creates a Subscription Object with a 660 Subscription Creation Operation in order to indicate its interest in 661 certain Events. See section 11 for a description of these 662 operations. When an Event occurs, the Subscription Object specifies 663 to the Printer where to deliver Event Notifications for Push Delivery 664 Methods only, how to deliver them, and what to include in them. See 665 section 9 for details on the contents of an Event Notification. 667 Using the IPP Job Template attributes as a model (see [RFC2911] 668 section 4.2), the attributes of a Subscription Object are divided 669 into two categories: Subscription Template Attributes and 670 Subscription Description Attributes. 672 Subscription Template attributes are, in turn, like the Job Template 673 attributes, divided into 675 1.Subscription Object attributes that a client can supply in a 676 Subscription Creation Request and 678 2.their associated Printer Object attributes that specify 679 supported and default values for the Subscription Object 680 attributes 682 The remainder of this section specifies general rules for 683 Subscription Template Attributes and describes each attribute in a 684 Subscription Object. 686 5.1 Rules for Support of Subscription Template Attributes 688 Subscription Template Attributes are fundamental to the Notification 689 model described in this specification. The client supplies these 690 attributes in Subscription Creation Operations and the Printer uses 691 these attributes to populate a newly created Subscription Object. 693 Subscription Objects attributes that are Subscription Template 694 Attributes conform to the following rules: 696 1.Each attribute's name starts with the prefix string "notify-" 697 and this document calls such attributes "notify-xxx". 699 2.For each "notify-xxx" Subscription Object attribute defined in 700 column 1 of Table 1 in section 5.3, Table 1 specifies 701 corresponding Printer attributes: "notify-xxx-default", "notify- 702 xxx-supported", "yyy-supported" and "notify-max-xxx-supported" 703 defined in column 2 of Table 1. Note "xxx" stands for the same 704 string in each case and "yyy" stands for some other string. 706 3.If a Printer supports "notify-xxx" in column 1 of Table 1, then 707 the Printer MUST support all associated attributes specified in 708 column 2 of Table 1. For example, Table 1 shows that if the 709 Printer supports "notify-events", it MUST support "notify- 710 events-default", "notify-events-supported" and "notify-max- 711 events-supported". 713 4.If a Printer does not support "notify-xxx" in column 1 of Table 714 1, then the Printer MUST NOT support any associated "notify-yyy" 715 attributes specified in column 2 of Table 1. For example, Table 716 1 shows that if the Printer doesn't support "notify-events", it 717 MUST NOT support "notify-events-default", "notify-events- 718 supported" and "notify-max-events-supported". Note this rule 719 does not apply to attributes whose names do not start with the 720 string "notify-" and are thus defined in another object and used 721 by other attributes. 723 5.Most "notify-xxx" attributes have a corresponding "yyy- 724 supported" attribute that specifies the supported values for 725 "notify-xxx". Column 2 of Table 1 specifies the name of each 726 "yyy-supported" attribute. The naming rules of IPP/1.1 (see 727 [RFC2911]) are used when "yyy-supported" is "notify-xxx- 728 supported". 730 6.Some "notify-xxx" attributes have a corresponding "notify-xxx- 731 default" attribute that specifies the value for "notify-xxx" if 732 the client does not supply it. Column 2 of Table 1 specifies 733 the name of each "notify-xxx-default" attribute. The naming 734 rules of IPP/1.1 (see [RFC2911]) are used. 736 If a client wishes to present an end user with a list of supported 737 values from which to choose, the client SHOULD query the Printer for 738 its supported value attributes. The client SHOULD also query the 739 default value attributes. If the client then limits selectable 740 values to only those values that are supported, the client can 741 guarantee that the values supplied by the client in the create 742 request all fall within the set of supported values at the Printer. 743 When querying the Printer, the client MAY enumerate each attribute by 744 name in the Get-Printer-Attributes Request, or the client MAY just 745 supply the 'subscription-template' group name in order to get the 746 complete set of supported attributes (both supported and default 747 attributes - see section 11.2.3). 749 5.2 Rules for Processing Subscription Template Attributes 751 This section defines a detailed set of rules that a Printer follows 752 when it processes Subscription Template Attributes in a Subscription 753 Creation Request. These rules are similar to the rules for 754 processing Operation attributes in [RFC2911]. That is, the Printer 755 may or may not support an attribute and a client may or may not 756 supply the attribute. Some combinations of these cases are OK. 757 Others return warnings or errors, and perhaps a list of unsupported 758 attributes. 760 A Printer MUST implement the following behavior for processing 761 Subscription Template Attributes in a Subscription Creation Request: 763 1.If a client supplies a "notify-xxx" attribute from column 1 of 764 Table 1 and the Printer supports it and its value, the Printer 765 MUST populate the attribute on the created Subscription Object. 767 2.If a client supplies a "notify-xxx" attribute from column 1 of 768 Table 1 and the Printer doesn't support it or its value, the 769 Printer MUST NOT populate the attribute on the created 770 Subscription Object with it. The Printer MUST do one of the 771 following: 773 a) If the value of the "notify-xxx" attribute is unsupported, the 774 Printer MUST return the attribute with its value in the 775 Subscription Attributes Group of the response. 777 b) If "notify-xxx" is an unsupported attribute, the Printer MUST 778 return the attribute in the Subscription Attributes Group of the 779 response with the 'unsupported' out-of-band value. 781 Note: The rules of this step are the same as for Unsupported 782 Attributes [RFC2911] section 3.1.7. except that the unsupported 783 attributes are returned in the Subscription Attributes Group 784 rather than the Unsupported Attributes Group because Subscription 785 Creation Operations can create more than one Subscription Object). 787 3.If a client is REQUIRED to supply a "notify-xxx" attribute from 788 column 1 of Table 1 and the Printer doesn't support the supplied 789 value, the Printer MUST NOT create a Subscription Object. The 790 rules for Unsupported Attributes in step #2 still apply. 792 4.If a client does not supply a "notify-xxx" attribute from column 1 793 of Table 1 and the attribute is REQUIRED for the client to supply, 794 the Printer MUST reject the Subscription Creation Operation 795 (including Job Creation operations) without creating a 796 Subscription Object, and MUST return in the response: 798 c) the status code 'client-error-bad-request' AND 800 d) no Subscription Attribute Groups. 802 5.If a client does not supply a "notify-xxx" attribute from column 1 803 of Table 1 that is OPTIONAL for the client to supply, and column 2 804 of Table 1 either: 806 a) specifies a "notify-xxx-default" attribute, the Printer MUST 807 behave as if the client had supplied the "notify-xxx-default" 808 attribute (see step #1) and populate the Subscription object 809 with the value of the "notify-xxx-default" attribute as part of 810 the Subscription Creation operation (unlike Job Template 811 attributes where the Printer does not populate the Job object 812 with defaults - see [RFC2911]) OR 814 b) does not specify a "notify-xxx-default" attribute, the Printer 815 MUST populate the "notify-xxx" attribute on the Subscription 816 Object according to the definition of the "notify-xxx" attribute 817 in a section 5.3. For some attributes, the "notify-xxx" is 818 populated with the value of some other attribute, and for 819 others, the "notify-xxx" is NOT populated on the Subscription 820 object at all. 822 6.A Printer MUST create a Subscription Object for each Subscription 823 Template Attributes group in a request unless the Printer: 825 a) encounters some attributes in a Subscription Template Attributes 826 Group that require the Printer not to create the Subscription 827 Object OR 829 b) would create a Per-Job Subscription Object when it doesn't have 830 space for another Per-Job Subscription Object OR 832 c) would create a Per-Printer Subscription Object when it doesn't 833 have space for another Per-Printer Subscription Object. 835 7.A response MUST contain one Subscription Attributes Group for each 836 Subscription Template Attributes Group in the request (and in the 837 same order) whether the Printer creates a Subscription Object from 838 the Subscription Template Attributes Group or not. However, the 839 attributes in each Subscription Attributes Group can be in any 840 order. 842 8.The Printer MUST populate each Subscription Attributes Group of 843 the response such that each contains: 845 a) the "notify-subscription-id" attribute (see section 5.4.1), if 846 and only if the Printer creates a Subscription Object. 848 b) the "notify-lease-duration" attribute (see section 5.3.8), if 849 and only if the Printer creates a Per-Printer Subscription 850 Object. The value of this attribute is the value of the 851 Subscription Object's "notify-lease-duration" attribute. This 852 value MAY be different from the client-supplied value (see 853 section 5.3.8). If a client supplies this attribute in the 854 creation of a Per-Job Subscription Object, it MUST appear in 855 this group with the out-of-band value 'unsupported' to indicate 856 that the Printer doesn't support it in this context. 858 c) all of the unsupported Subscription Template Attributes from 859 step #2. Note, they are not returned in the Unsupported 860 Attributes Group in order to separate the unsupported attributes 861 for each Subscription Object. 863 d) the "notify-status-code" attribute if the Printer does not 864 create the Subscription Object or if there are unsupported 865 attributes from step #2. The possible values of the "notify- 866 status-code" attribute are shown below (see section 13 for more 867 details). The Printer returns the first value in the list below 868 that describes the status. 870 'client-error-uri-scheme-not-supported': the Subscription 871 Object was not created because the scheme of the "notify- 872 recipient-uri" attribute is not supported. See section 873 13.1 for more details about this status code. See step #3 874 in this section for the case that causes this error, and 875 the resulting step #6a) that causes the Printer not to 876 create the Subscription Object. 878 'client-error-attributes-or-values-not-supported': the 879 Subscription Object was not created because the method of 880 the "notify-pull-method" attribute is not supported. See 881 section 13.1 for more details about this status code. See 882 step #3 in this section for the case that causes this 883 error, and the resulting step #6a) that causes the Printer 884 not to create the Subscription Object. 886 'client-error-too-many-subscriptions': the Subscription 887 Object was not created because the Printer has no space for 888 additional Subscription Objects. The client SHOULD try 889 again later. See section 13.3 for more details about this 890 status code. See steps #6b) and #6c) in this section for 891 the cases that causes this error. 893 'successful-ok-too-many-events': the Subscription Object was 894 created without the "notify-events" values included in this 895 Subscription Attributes Group because the "notify-events" 896 attribute contains too many values. See section 13.4 for 897 more details about this status code. See step #2 in this 898 section and section 5.3.3 for the cases that cause this 899 status code. 901 'successful-ok-ignored-or-substituted-attributes' : the 902 Subscription Object was created but some supplied 903 Subscription Template Attributes are unsupported. These 904 unsupported attributes are also in the Subscription 905 Attributes Group. See section 13.5 for more details about 906 this status code. See step #2 in this section for the 907 cases that cause this status code. 909 9.The Printer MUST validate all Subscription Template Attributes and 910 MUST return all unsupported attributes and values in the 911 corresponding Subscription Attributes Group of the response (see 912 step #2) unless it determines that it could not create additional 913 Subscription Objects because of condition #6b) or condition #6c). 914 Then, the Printer NEED NOT validate these additional Subscription 915 Template Attributes and the client MUST NOT expect to find 916 unsupported attributes from step #2 in such additional 917 Subscription Attribute Groups. 919 5.3 Subscription Template Attributes 921 This section contains the Subscription Template Attributes defined 922 for the Subscription and Printer objects. 924 Table 1 below shows the Subscription Template Attributes and has two 925 columns: 927 - Attribute in Subscription Object: the name and attribute syntax 928 of each Subscription Object Attribute that is a Subscription 929 Template Attribute 931 - Default and Supported Printer Attributes: the default attribute 932 and supported Printer attributes that are associated with the 933 attribute in column 1. 935 The "notify-recipient-uri" attribute is for use with Push Delivery 936 Methods. The "notify-pull-method" attribute is for use with Pull 937 Delivery Methods. 939 For Push Delivery Methods, a Printer MUST support all attributes in 940 Table 1 below except for "notify-pull-method" and "notify-attributes" 941 (and "notify-pull-method-supported" and "notify-attributes- 942 supported"). For Pull Delivery Methods, a Printer MUST support all 943 attributes in Table 1 below except for "notify-recipient-uri" and 944 "notify-attributes" (and "notify-schemes-supported" and "notify- 945 attributes-supported"). If a Printer supports both Push and Pull 946 Delivery Methods, then it MUST support both "notify-recipient-uri" 947 and "notify-pull-method" attributes. 949 For Pull Delivery Methods, a client MUST supply "notify-recipient- 950 uri" and MAY omit any of the rest of the attributes in column 1 of 951 Table 1 in a Subscription Creation Request. For Push Delivery 952 Methods, a client MUST supply "notify-pull-method" and MAY omit any 953 of the rest of the attributes in column 1 of Table 1 in a 954 Subscription Creation Request. A client MUST NOT supply both 955 "notify-recipient-uri" and "notify-pull-method" attributes in the 956 same Subscription Creation Request. 958 Note: The Default and Supported Printer attributes listed in column 959 2 of Table 1 do not have separate sections in this specification 960 defining their semantics. Instead, the section for the corresponding 961 Subscription Object attribute (column 1 of Table 1) contains the 962 semantics of these Printer attributes. This approach follows the 963 precedence of the Job Template attributes in section 4.2 of [RFC2911] 964 where the corresponding "xxx-default" and "xxx-supported" Printer 965 attributes are defined in the same section as the "xxx" Job 966 attribute. 968 Table 1 - Subscription Template Attributes 970 Attribute in Subscription Default and Supported Printer 971 Object Attributes 973 notify-recipient-uri (uri) * notify-schemes-supported (1setOf 974 uriScheme) 976 notify-pull-method (type2 notify-pull-method-supported (1setOf 977 keyword) ** type2 keyword) 979 notify-events (1setOf type2 -events-default (1setOf type2 980 keyword) keyword) 981 notify-events-supported (1setOf type2 982 keyword) 983 notify-max-events-supported 984 (integer(2:MAX)) 986 notify-attributes (1setOf notify-attributes-supported (1setOf 987 type2 keyword) type2 keyword) 989 notify-user-data 990 (octetString(63)) 992 notify-charset (charset) charset-supported (1setOf charset) 994 notify-natural-language generated-natural-language-supported 995 (naturalLanguage) (1setOf naturalLanguage) 997 notify-lease-duration notify-lease-duration-default 998 (integer(0:MAX)) (integer(0:67108863)) 999 notify-lease-duration-supported 1000 (1setOf (integer(0: 67108863) | 1001 rangeOfInteger(0:67108863))) 1003 notify-time-interval 1004 (integer(0:MAX)) 1006 * "notify-recipient-uri" is for Push Delivery Methods only. 1007 ** "notify-pull-method" is for Pull Delivery Methods only. 1009 5.3.1 notify-recipient-uri (uri) 1011 This attribute's value is a URL, which is a special case of a URI. 1012 Its value consists of a scheme and an address. The address specifies 1013 the Notification Recipient and the scheme specifies the Push Delivery 1014 Method for each Event Notification associated with this Subscription 1015 Object. 1017 If a Printer supports any Push Delivery Methods, a Printer MUST 1018 support this attribute and return the value as supplied by the client 1019 (no case conversion or other canonicalization) in any operation 1020 response that includes this attribute. 1022 For a Push Delivery Method, a client MUST supply this attribute in a 1023 Subscription Creation Operation. Thus there is no need for a default 1024 Printer attribute. 1026 The URI scheme of the value of this attribute on a Subscription 1027 object MUST be a value of the "notify-schemes-supported (1setOf 1028 uriScheme)" Printer attribute (see section 5.3.1.1). Note: According 1029 to [RFC2396] the ":" terminates the scheme and so is not part of the 1030 scheme. Therefore, values of the "notify-schemes-supported" Printer 1031 attribute do not include the ":" character. 1033 If the client supplies an unsupported scheme in the value of this 1034 attribute, then the Printer MUST NOT create the Subscription Object 1035 and MUST return the "notify-status-code" attribute with the 'client- 1036 error-uri-scheme-not-supported' value in the Subscription Attributes 1037 Group in the response. 1039 The Printer MUST treat the address part of this attribute as opaque. 1041 5.3.1.1 notify-schemes-supported (1setOf uriScheme) 1043 This attribute contains the URI schemes supported in the "notify- 1044 recipient-uri" Subscription Template attribute. See sections 5.1 and 1045 5.2 for the behavior of "xxx-supported" Subscription Template Printer 1046 attributes. 1048 5.3.2 notify-pull-method (type2 keyword) 1050 This attribute's value is a type2 keyword indicating which Pull 1051 Delivery Method is to be used. 1053 Since a Printer MUST support the 'ippget' Pull Delivery Method [ipp- 1054 get-method] (see section 15), a Printer MUST support this attribute 1055 and return the value as supplied by the client in any operation 1056 response that includes this attribute. 1058 For a Pull Delivery Method, a client MUST supply this attribute in a 1059 Subscription Creation Operation. Thus there is no need for a default 1060 Printer attribute. 1062 The keyword value of this attribute on a Subscription object MUST be 1063 a value of the "notify-pull-method-supported (1setOf type2 keyword)" 1064 Printer attribute. 1066 If the client supplies an unsupported method in the value of this 1067 attribute, then the Printer MUST NOT create the Subscription Object 1068 and MUST return the "notify-status-code" attribute with the 'client- 1069 error-attributes-or-values-not-supported' value in the Subscription 1070 Attributes Group in the response. 1072 5.3.2.1 notify-pull-method-supported (1setOf type2 keyword) 1074 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1075 Subscription Template Printer attributes. 1077 5.3.3 notify-events (1setOf type2 keyword) 1079 This attribute contains a set of Subscribed Events. When an Event 1080 occurs and it "matches" a value of this attribute, the Printer 1081 delivers an Event Notification using information in the Subscription 1082 Object. The details of "matching" are described subsection 5.3.3.5. 1084 A Printer MUST support this attribute. 1086 A client MAY supply this attribute in a Subscription Creation 1087 Operation. If the client does not supply this attribute in 1088 Subscription Creation Operation, the Printer MUST populate this 1089 attribute on the Subscription Object with its "notify-events-default" 1090 attribute value. 1092 Each keyword value of this attribute on a Subscription Object MUST be 1093 a value of the "notify-events-supported (1setOf type2 keyword)" 1094 Printer attribute. 1096 The number of values of this attribute MUST NOT exceed the value of 1097 the "notify-max-events-supported" attribute. A Printer MUST support 1098 at least 2 values per Subscription Object. If the number of values 1099 supplied by a client in a Subscription Creation Operation exceeds the 1100 value of this attribute, the Printer MUST treat extra values as 1101 unsupported values and MUST use the value of 'successful-ok-too-many- 1102 events' for the "notify-status-code" attribute in the Subscription 1103 Attributes Group of the response. 1105 5.3.3.1 notify-events-default (1setOf type2 keyword) 1107 See sections 5.1 and 5.2 for the behavior of "xxx-default" 1108 Subscription Template Printer attributes. 1110 5.3.3.2 notify-events-supported (1setOf type2 keyword) 1112 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1113 Subscription Template Printer attributes. 1115 5.3.3.3 notify-max-events-supported (integer(2:MAX)) 1117 This attribute specified the maximum number of events that the 1118 Printer supports for the "notify-events" Subscription Template 1119 attribute. See sections 5.1 and 5.2 for the behavior of "xxx- 1120 supported" Subscription Template Printer attributes. 1122 5.3.3.4 Standard Values for Subscribed Events 1124 Each value of this attribute is a keyword and it specifies a 1125 Subscribed Event that represents certain changes. Some keywords 1126 represent a subset of changes of another keyword, e.g., 'job- 1127 completed' is an Event value which is a sub-value of 'job-state- 1128 change'. See section 5.3.3.5 for the case where this attribute 1129 contains both a value and a sub-value. 1131 The values in this section are divided into three categories: No 1132 Events, Job Events and Printer Events. 1134 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1135 support the Events indicated as "OPTIONAL". 1137 5.3.3.4.1 No Events 1139 The standard and only keyword value for No Events is: 1141 'none': REQUIRED - no Event Notifications for any Events. As the 1142 sole value of "notify-events-supported", this value means that the 1143 Printer does not support the delivery of Event Notifications. As 1144 the sole value of "notify-events-default", this value means that a 1145 client MUST specify the "notify-events" attribute in order for a 1146 Subscription Creation Operation to succeed. If the Printer 1147 receives this value as the sole value of a Subscription Creation 1148 Operation, it does not create a Subscription Object. If a Printer 1149 receives this value with other values of a Subscription Creation 1150 Operation, the Printer MUST treat this value as an unsupported 1151 value. 1153 5.3.3.4.2 Subscribed Printer Events 1155 The standard keyword values for Subscribed Printer Events are: 1157 'printer-state-changed': REQUIRED - the Printer changed state from 1158 any state to any other state. Specifically, the value of the 1159 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1160 accepting-jobs" attributes changed. 1162 This Subscribed Event value has the following sub-values: 1163 'printer-restarted' and 'printer-shutdown'. A client can listen 1164 for any of these sub-values if it doesn't want to listen to all 1165 printer-state changes: 1167 'printer-restarted': OPTIONAL - when the printer is powered 1168 up . 1170 'printer-shutdown': OPTIONAL - when the device is being 1171 powered down . 1173 'printer-stopped: REQUIRED - when the printer stops printing, 1174 i.e. the value of the "printer-state" Printer attribute 1175 becomes 'stopped'. 1177 'printer-config-changed': OPTIONAL - when the configuration of a 1178 Printer has changed, i.e., the value of the "printer-message-from- 1179 operator" or any "configuration" Printer attribute has changed. A 1180 "configuration" Printer attribute is an attribute which can change 1181 value because of some human interaction either direct or indirect, 1182 and which is not covered by one of the other Events in this 1183 section. Examples of "configuration" Printer attributes are any 1184 of the Job Template attributes, such as "xxx-supported", "xxx- 1185 ready" and "xxx-default". The client has to perform a Get- 1186 Printer-Attributes to find out the new values of these changed 1187 attributes. This Event is useful for GUI clients and drivers to 1188 update the available printer capabilities to the user. 1190 This Event value has the following sub-values: 'printer-media- 1191 changed' and 'printer-finishings-changed'. A client can listen 1192 for any of these sub-values if it doesn't want to listen to all 1193 printer-configuration changes: 1195 'printer-media-changed': OPTIONAL - when the media loaded on 1196 a printer has been changed, i.e., the "media-ready" 1197 attribute has changed. This Event includes two cases: an 1198 input tray that goes empty and an input tray that receives 1199 additional media of the same type or of a different type. 1200 The client must check the "media-ready" Printer attribute 1201 (see [RFC2911] section 4.2.11) separately to find out what 1202 changed. 1204 'printer-finishings-changed': OPTIONAL - when the finisher on 1205 a printer has been changed, i.e., the "finishings-ready" 1206 attribute has changed. This Event includes two cases: a 1207 finisher that goes empty and a finisher that is refilled 1208 (even if it is not full). The client must check the 1209 "finishings-ready" Printer attribute separately to find out 1210 what changed. 1212 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1213 Printer's queue has changed, so that an application that is 1214 monitoring the queue can perform a Get-Jobs operation to determine 1215 the new order. This Event does not include when a job enters the 1216 queue (the 'job-created' Event covers that) and does not include 1217 when a job leaves the queue (the 'job-completed' Event covers 1218 that). 1220 5.3.3.4.3 Subscribed Job Events 1222 The standard keyword values for Subscribed Job Events are: 1224 'job-state-changed': REQUIRED - the job has changed from any state 1225 to any other state. Specifically, the Printer delivers this Event 1226 whenever the value of the "job-state" attribute or "job-state- 1227 reasons" attribute changes. When a Job is removed from the Job 1228 Retention or Job History phases (see [RFC2911] section 4.3.7.1), 1229 no Event is generated. 1231 This Event value has the following sub-values: 'job-created', 1232 'job-completed' and 'job-stopped'. A client can listen for any of 1233 these sub-values if it doesn't want to listen to all 'job-state 1234 changes'. 1236 'job-created': REQUIRED - the Printer has accepted a Job 1237 Creation operation, a Restart-Job operation [RFC2911], or 1238 any job operation that creates a Job object from an 1239 existing Job object. The Printer populates the job's 1240 "time-at-creation" attribute value (see [RFC2911] section 1241 4.3.14.1). The Printer puts the job in the 'pending', 1242 'pending-held' or 'processing' states. 1244 'job-completed': REQUIRED - the job has reached one of the 1245 completed states, i.e., the value of the job's "job-state" 1246 attribute has changed to: 'completed', 'aborted', or 1247 'canceled'. The Job's "time-at-completed" and "date-time- 1248 at-completed" (if supported) attributes are set (see 1249 [RFC2911] section 4.3.14). When a Job completes, a 1250 Notification Recipient MAY query the Job using the Get-Job- 1251 Attributes operation. To allow such a query, the Printer 1252 retains the Job in the Job Retention and/or the Job History 1253 phases (see [RFC2911] section 4.3.7.1) for a suitable 1254 amount of time that depends on implementation and the 1255 Delivery Methods supported. The Printer also delivers this 1256 Event when a Job is removed with the Purge-Job operation 1257 (see [RFC2911] section 3.2.9). In this case, the Event 1258 Notification MUST report the 'job-state' as 'canceled' and 1259 the Job object is no longer present for query. 1261 'job-stopped: OPTIONAL - when the job stops printing, i.e. 1262 the value of the "job-state" Job attribute becomes 1263 'processing-stopped'. 1265 'job-config-changed': OPTIONAL - when the configuration of a job has 1266 changed, i.e., the value of the "job-message-from-operator" or any 1267 of the "configuration" Job attributes have changed. A 1268 "configuration" Job attribute is an attribute that can change 1269 value because of some human interaction either direct or indirect. 1270 Examples of "configuration" Job attributes are any of the job 1271 template attributes and the "job-name" attribute. The client 1272 performs a Get-Job-Attributes to find out the new values of the 1273 changed attributes. This Event is useful for GUI clients and 1274 drivers to update the job information to the user. 1276 'job-progress': OPTIONAL - when the Printer has completed Printing a 1277 sheet. See the separate [RFC3381] specification for additional 1278 attributes that a Printer MAY deliver in an Event Notification 1279 caused by this Event. The "notify-time-interval" attribute 1280 affects this Event by causing the Printer NOT to deliver an Event 1281 Notification every time a 'job-progress' Events occurs. See 1282 section 5.3.9 for full details. 1284 5.3.3.5 Rules for Matching of Subscribed Events 1286 When an Event occurs, the Printer MUST find each Subscription object 1287 whose "notify-events" attribute "matches" the Event. The rules for 1288 "matching" of Subscribed Events are described separately for Printer 1289 Events and for Job Events. This section also describes some special 1290 cases. 1292 5.3.3.5.1 Rules for Matching of Printer Events 1294 Given that the Printer causes Printer Event E to occur, for each 1295 Per-Job or Per-Printer Subscription S in the Printer, if E equals a 1296 value of this attribute in S or E is a sub-value of a value of this 1297 attribute in S, the Printer MUST generate an Event Notification. 1299 Consider the example. There are three Subscription Objects each with 1300 the Subscribed Printer Event 'printer-state-changed'. Subscription 1301 Object A is a Per-Printer Subscription Object. Subscription Object B 1302 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1303 is a Per-Job Subscription Object for Job 2. When the Printer enters 1304 the 'stopped' state, the Printer delivers an Event Notification to 1305 the Notification Recipients of Subscription Objects A, B, and C 1306 because this is a Printer Event. Note if Job 1 has already 1307 completed, the Printer would not deliver an Event Notification for 1308 its Subscription Object, even if Job 1 is retained in the Job 1309 Retention and/or the Job History phases (see [RFC2911] section 1310 4.3.7.1). 1312 5.3.3.5.2 Rules for Matching of Job Events 1314 Given that Job J causes Job Event E to occur: 1316 1.For each Per-Printer Subscription S in the Printer, if E equals 1317 a value of this attribute in S or E is a sub-value of a value of 1318 this attribute in S, the Printer MUST generate an Event 1319 Notification. 1321 2.For each Per-Job Subscription S associated with Job J, if E 1322 equals a value of this attribute in S or E is a sub-value of a 1323 value of this attribute in S, the Printer MUST generate an Event 1324 Notification. 1326 3.For each Per-Job Subscription S that is NOT associated Job J, if 1327 E equals a value of this attribute in S or E is a sub-value of a 1328 value of this attribute in, the Printer MUST NOT generate an 1329 Event Notification from S. 1331 Consider the example: There are three Subscription Objects listening 1332 for the Job Event 'job-completed'. Subscription Object A is a Per- 1333 Printer Subscription Object. Subscription Object B is a Per-Job 1334 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1335 Subscription Object for Job 2. In addition, Per-Printer Subscription 1336 Object D is listening for the Job Event 'job-state-changed'. When 1337 Job 1 completes, the Printer delivers an Event Notification to the 1338 Notification Recipient of Subscription Object A (because it is Per- 1339 Printer) and Subscription Object B because it is a Per-Job 1340 Subscription Object associated with the Job generating the Event. 1341 The Printer also delivers an Event Notification to the Notification 1342 Recipient of Subscription Object D because 'job-completed' is a sub- 1343 value of 'job-state-changed' - the value that Subscription Object D 1344 is listening for. The Printer does not deliver an Event Notification 1345 to the Notification Recipients of Subscription Object C because it is 1346 a Per-Job Subscription Object associated with some Job other than the 1347 Job generating the Event. 1349 5.3.3.5.3 Special Cases for Matching Rules 1351 This section contains rule for special cases. 1353 If an Event matches Subscribed Events in two different Subscription 1354 Objects and the Printer would deliver two identical Event 1355 Notifications (except for the "notify-subscription-id" attribute) to 1356 the same Notification Recipient using the same Delivery Method, the 1357 Printer MUST deliver both Event Notifications. That is, the Printer 1358 MUST NOT try to consolidate seemingly identical Event Notifications 1359 that occur in separate Subscription objects. Incidentally, the 1360 Printer MUST NOT reject Subscription Creation Operations that would 1361 create this scenario. 1363 If an Event matches two values of this "notify-events" attribute in a 1364 single Subscription object (e.g., a value and its sub-value), a 1365 Printer MAY deliver one Event Notification for each matched value in 1366 the Subscription Object or it MAY deliver only one Event Notification 1367 per Subscription Object. The rules in sections 5.3.3.5.1 and 1368 5.3.3.5.2 are purposefully flexible about the number of Event 1369 Notifications sent when Event E matches two or more values in a 1370 Subscription Object. 1372 Consider the example: There are two Per-Printer Subscription Objects 1373 when a Job completes. Subscription Object A has the Subscribed Job 1374 Event 'job-state-changed'. Subscription Object B has the Subscribed 1375 Job Events 'job-state-changed' and 'job-completed'. The Printer 1376 delivers an Event Notification to the Notification Recipient of 1377 Subscription Object A with the value of 'job-state-changed' for the 1378 "notify-subscribing-event" attribute. The Printer delivers either 1379 one or two Event Notifications to the Notification Recipient of 1380 Subscription Object B, depending on implementation. If it delivers 1381 two Event Notifications, one has the value of 'job-state-changed' 1382 for the "notify-subscribing-event" attribute, and the other has the 1383 value of 'job-completed' for the "notify-subscribing-event" 1384 attribute. If it delivers one Event Notification, it has the value 1385 of either 'job-state-changed' or 'job-completed' for the "notify- 1386 subscribing-event" attribute, depending on implementation. The 1387 algorithm for choosing such a value is implementation dependent. 1389 5.3.4 notify-attributes (1setOf type2 keyword) 1391 This attribute contains a set of attribute names. When a Printer 1392 delivers a Machine Consumable Event Notification, it includes a fixed 1393 set of attributes (see section 9.1). If this attribute is present 1394 and the Event Notification is Machine Consumable, the Printer also 1395 includes the attributes specified by this attribute. 1397 A Printer MAY support this attribute. 1399 A client MAY supply this attribute in a Subscription Creation 1400 Operation. If the client does not supply this attribute in 1401 Subscription Creation Operation or the Printer does not support this 1402 attribute, the Subscription Object either (1) MAY contain the 1403 "notify-attributes" attribute with a 'none' value or (2) NEED NOT 1404 contain the attribute at all. There is no "notify-attributes- 1405 default" Printer attribute. 1407 Each keyword value of this attribute on a Subscription Object MUST be 1408 a value of the "notify-attributes-supported (1setOf type2 keyword)" 1409 Printer attribute (see section 5.3.4.1). The "notify-attributes- 1410 supported" MAY contain any Printer attribute, Job attribute or 1411 Subscription Object attribute that the Printer supports in an Event 1412 Notification. It MUST NOT contain any of the attributes in Section 1413 9.1 that a Printer automatically puts in an Event Notification; it 1414 would be redundant. If a client supplies an attribute in Section 1415 9.1, the Printer MUST treat it as an unsupported attribute value of 1416 the "notify-attributes" attribute. 1418 The following rules apply to each keyword value N of the "notify- 1419 attributes" attribute: If the value N names: 1421 a)a Subscription attribute, the Printer MUST use the attribute N in 1422 the Subscription Object that is being used to generate the Event 1423 Notification. 1425 b)a Job attribute and the Printer is generating an Event 1426 Notification from a Per-Job Subscription Object S, the Printer 1427 MUST use the attribute N in the Job object associated with S. 1429 c)a Job attribute and the Printer is generating an Event 1430 Notification from a Per-Printer Subscription Object and the Event 1431 is: 1433 ? a Job Event, the Printer MUST use the attribute N in the Job 1434 object that caused the Event. 1436 ? a Printer Event, the Printer MUST use the attribute N in the 1437 active Job. 1439 If a Printer supports this attribute and a Subscription Object 1440 contains this attribute and the Delivery Method generates a Machine 1441 Consumable Event Notification, the Printer MUST include in each Event 1442 Notification: 1444 a)the attributes specified in section 9.1 and 1446 b)each attribute named by this attribute. 1448 The Printer MUST NOT use this attribute to generate a Human 1449 Consumable Event Notification. 1451 5.3.4.1 notify-attributes-supported (1setOf type2 keyword) 1453 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1454 Subscription Template Printer attributes. 1456 5.3.5 notify-user-data (octetString(63)) 1458 This attribute contains opaque data that some Delivery Methods 1459 include in each Machine Consumable Event Notification. The opaque 1460 data might contain, for example: 1462 - the identity of the Subscriber 1464 - a path or index to some Subscriber information 1466 - a key that identifies to the Notification Recipient the 1467 ultimate recipient of the Event Notification 1469 - the id for a Notification Recipient that had previously 1470 registered with an Instant Messaging Service 1472 A Printer MUST support this attribute. 1474 A client MAY supply this attribute in a Subscription Creation 1475 Operation. If the client does not supply this attribute in the 1476 Subscription Creation Operation, the Subscription Object either (1) 1477 MAY contain the "notify-user-data" attribute with a zero length value 1478 or (2) NEED NOT contain the attribute at all. There is no "notify- 1479 user-data-default" Printer attribute. 1481 There is no "notify-user-data-supported" Printer attribute. Rather, 1482 any octetString whose length does not exceed 63 octets is a supported 1483 value. If the length exceeds 63 octets, the Printer MUST treat it as 1484 an unsupported value. 1486 5.3.6 notify-charset (charset) 1488 This attribute specifies the charset to be used in the Event 1489 Notification content sent to the Notification Recipient, whether the 1490 Event Notification content is Machine Consumable or Human Consumable. 1492 A Printer MUST support this attribute. 1494 A client MAY supply this attribute in a Subscription Creation 1495 Operation. If the client does not supply this attribute in 1496 Subscription Creation Operation or supplies an unsupported value, the 1497 Printer MUST populate this attribute in the Subscription Object with 1498 the value of the "attributes-charset" operation attribute, which is a 1499 REQUIRED attribute in all IPP requests (see [RFC2911]). If the value 1500 of the "attributes-charset" attribute is unsupported, the Printer 1501 MUST populate this attribute in the Subscription Object with the 1502 value of the Printer's "charset-configured" attribute. There is no 1503 "notify-charset-default" Printer attribute. 1505 The value of this attribute on a Subscription Object MUST be a value 1506 of the "charset-supported (1setOf charset)" Printer attribute. 1508 5.3.7 notify-natural-language (naturalLanguage) 1510 This attribute specifies the natural language to be used in any human 1511 consumable text in the Event Notification content sent to the 1512 Notification Recipient, whether the Event Notification content is 1513 Machine Consumable or Human Consumable. 1515 A Printer MUST support this attribute. 1517 A client MAY supply this attribute in a Subscription Creation 1518 Operation. If the client does not supply this attribute in 1519 Subscription Creation Operation or supplies an unsupported value, the 1520 Printer MUST populate this attribute in the Subscription Object with 1521 the value of the "attributes-natural-language" operation attribute, 1522 which is a REQUIRED attribute in all IPP requests (see [RFC2911] 1523 section 3.1.4). If the value of the "attributes-natural-language" 1524 attribute is unsupported, the Printer MUST populate this attribute in 1525 the Subscription Object with the value of the Printer's "natural- 1526 language-configured" attribute (see [RFC2911] section 4.4.19). There 1527 is no "notify-natural-language-default" Printer attribute. 1529 The value of this attribute on a Subscription Object MUST be a value 1530 of the "generated-natural-language-supported (1setOf type2 1531 naturalLanguage)" Printer attribute (see [RFC2911] section 4.4.20). 1533 5.3.8 notify-lease-duration (integer(0:67108863)) 1535 This attribute specifies the duration of the lease (in seconds) 1536 associated with the Per-Printer Subscription Object at the time the 1537 Subscription Object was created or the lease was renewed. The 1538 duration of the lease is infinite if the value is 0, i.e., the lease 1539 never expires. See section 5.4.3 on "notify-lease-expiration-time 1540 (integer(0:MAX))" for more details. 1542 This attribute is not present on a Per-Job Subscription Object 1543 because the Subscription Object lasts exactly as long as the 1544 associated Job object. See discussion of the 'job-completed' event 1545 in section 5.3.3.4.3 about retention of the Job object after 1546 completion. 1548 A Printer MUST support this attribute. 1550 For a Subscription Object Creation operation of a Per-Job 1551 Subscription Object, the client MUST NOT supply this attribute. If 1552 the client does supply this attribute, the Printer MUST treat it as 1553 an unsupported attribute. 1555 For a Subscription Creation Operation of a Per-Printer Subscription 1556 Object or a Renew-Subscription operation, a client MAY supply this 1557 attribute. If the client does not supply this attribute, the Printer 1558 MUST populate this attribute with its "notify-lease-duration-default" 1559 (0:67108863) attribute value. If the client supplies this attribute 1560 with an unsupported value, the Printer MUST populate this attribute 1561 with a supported value, and this value SHOULD be as close as possible 1562 to the value requested by the client. Note: this rule implies that a 1563 Printer doesn't assign the value of 0 (infinite) unless the client 1564 requests it. 1566 After the Printer has populated this attribute with a supported 1567 value, the value represents the "granted duration" of the lease in 1568 seconds and the Printer updates the value of the Subscription 1569 Object's "notify-lease-expiration-time" attribute as specified in 1570 section 5.4.3. 1572 The value of this attribute on a Subscription Object MUST be a value 1573 of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) 1574 | rangeOfInteger(0:67108863))) Printer attribute. 1576 A Printer MAY require authentication in order to return the value of 1577 0 (the lease never expires) as one of the values of "notify-lease- 1578 duration-supported", and to allow 0 as a value of the "notify-lease- 1579 duration" attribute. 1581 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1582 1 and is about 2 years in seconds. The value is considerably less 1583 than MAX so that there is virtually no chance of an overflow when the 1584 Printer adds it to the Printer's "printer-up-time" attribute value 1585 (see [RFC2911] section 4.4.29) to produce the "notify-lease- 1586 expiration-time" Subscription Description attribute value (see 1587 section 5.4.3). 1589 5.3.8.1 notify-lease-duration-default (integer(0:67108863)) 1591 See sections 5.1 and 5.2 for the behavior of "xxx-default" 1592 Subscription Template Printer attributes. 1594 5.3.8.2 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 1595 rangeOfInteger(0:67108863))) 1597 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1598 Subscription Template Printer attributes. 1600 5.3.9 notify-time-interval (integer(0:MAX)) 1602 The 'job-progress' Event occurs each time that a Printer completes a 1603 sheet. Some Notification Recipients do not want to receive an Event 1604 Notification every time this Event occurs. This attribute allows a 1605 Subscribing Client to request how often it wants to receive Event 1606 Notifications for 'job-progress' Events. The value of this attribute 1607 MAY be any nonnegative integer (0,MAX) indicating the minimum number 1608 of seconds between 'job-progress' Event Notifications. 1610 The Printer MUST support this attribute if and only if the Printer 1611 supports the 'job-progress' Event. 1613 A client MAY supply this attribute in a Subscription Creation 1614 Operation. If the client does not supply this attribute in the 1615 Subscription Creation Operation, the Subscription Object either (1) 1616 MAY contain the "notify-time-interval" attribute with a '0' value or 1617 (2) NEED NOT contain this attribute at all. There is no "notify- 1618 time-interval-default" Printer attribute. 1620 There is no "notify-time-interval-supported" Printer attribute. 1622 If the 'job-progress' Event occurs and a Subscription Object contains 1623 the 'job-progress' Event as a value of the 'notify-events' attribute, 1624 there are two cases to consider: 1626 1.This attribute is not present on the Subscription Object or has 1627 the value of 0. The Printer MUST generate and deliver an Event 1628 Notification (as is the case with other Events). 1630 2.This attribute is present with a nonzero value of N: 1632 a)If the Printer has not sent an Event Notification for the 'job- 1633 progress' Event for the associated Subscription Object within 1634 the past N seconds, the Printer MUST deliver an Event 1635 Notification for the Event that just occurred. Note when the 1636 Printer completes the first page of a Job, this rule implies 1637 that the Printer delivers an Event Notification for a Per-Job 1638 Subscription Object. 1640 b)Otherwise, the Printer MUST NOT generate or deliver an Event 1641 Notification for the associated Subscription Object. The 1642 Printer MUST NOT increase the value of the "notify-sequence- 1643 number" Subscription Object attribute (i.e., the sequence of 1644 values of the "notify-sequence-number" attribute counts the 1645 Event Notifications that the Printer sent and not the Events 1646 that do not cause an Event Notification to be sent). 1648 It is RECOMMENDED that a Subscribing Client use this attribute when 1649 it subscribes to the 'job-progress' Event, and that the value be 1650 sufficiently large to limit the frequency with which the Printer 1651 delivers Event Notifications requests. 1653 This attribute MUST NOT effect any Events other than 'job-progress'. 1655 5.4 Subscription Description Attributes 1657 Subscription Description Attributes are those attributes that a 1658 Printer adds to a Subscription Object at the time of its creation. 1660 A Printer MUST support all attributes in this Table 2. 1662 A client MUST NOT supply the attributes in Table 2 in a Subscription 1663 Template Attributes Group of a Subscription Creation Operation. 1664 There are no corresponding default or supported attributes. 1666 Table 2 - Subscription Description Attributes 1668 Subscription Object attributes: 1670 notify-subscription-id (integer(1:MAX)) 1672 notify-sequence-number (integer(0:MAX)) 1674 notify-lease-expiration-time (integer(0:MAX)) 1676 notify-printer-up-time (integer(1:MAX)) 1678 notify-printer-uri (uri) 1680 notify-job-id (integer(1:MAX)) 1682 notify-subscriber-user-name (name(MAX)) 1684 5.4.1 notify-subscription-id (integer (1:MAX)) 1686 This attribute identifies a Subscription Object instance with a 1687 number that is unique within the context of the Printer. The Printer 1688 generates this value at the time it creates the Subscription Object. 1690 A Printer MUST support this attribute. 1692 The Printer MAY assign the value of this attribute sequentially as it 1693 creates Subscription Objects. However, if there is no security on 1694 Subscription objects, sequential assignment exposes the system to a 1695 passive traffic monitoring threat. 1697 The Printer SHOULD avoid re-using recent values of this attribute 1698 during continuous operation of the Printer as well as across power 1699 cycles. Then a Subscribing Client is unlikely to find that a stale 1700 reference accesses a new Subscription Object. 1702 The 0 value is not permitted in order to allow for compatibility with 1703 "job-id" and with SNMP index values, which also cannot be 0. 1705 5.4.2 notify-sequence-number (integer (0:MAX)) 1707 The value of this attribute indicates the number of times that the 1708 Printer has generated and attempted to deliver an Event Notification 1709 for this Subscription object. When an Event Notification contains 1710 this attribute, the Notification Recipient can determine whether it 1711 missed some Event Notifications (i.e., numbers skipped) or received 1712 duplicates (i.e., same number twice). 1714 A Printer MUST support this attribute. 1716 When the Printer creates a Subscription Object, it MUST populate this 1717 attribute with a value of 0. This value indicates that the Printer 1718 has not sent any Event Notifications for this Subscription Object. 1720 Each time the Printer delivers a newly generated Event Notification, 1721 it MUST increase the value of this attribute by 1. For some Delivery 1722 Methods, the Printer MUST include this attribute in each Event 1723 Notification, and the value MUST be the value after it is increased 1724 by 1. That is, the value of this attribute in the first Event 1725 Notification after Subscription object creation MUST be 1, the second 1726 MUST be 2, etc. If a Delivery Method is defined such that the 1727 Notification Recipient returns a response, the Printer can re-try 1728 delivering an Event Notification a certain number of times with the 1729 same sequence number when the Notification Recipient fails to return 1730 a response. 1732 If a Subscription Object lasts long enough to reach the value of MAX, 1733 its next value MUST be 0, i.e., it wraps. 1735 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1737 This attribute specifies the time in the future when the lease on the 1738 Per-Printer Subscription Object will expire, i.e. the "printer-up- 1739 time" value at which the lease will expire. If the value is 0, the 1740 lease never expires. 1742 A Printer MUST support this attribute. 1744 When the Printer creates a Per-Job Subscription Object, this 1745 attribute MUST NOT be present - the Subscription Object lasts exactly 1746 as long as the associated Job object. See also the discussion of the 1747 'job-completed' event in section 5.3.3.4.3 about retention of the Job 1748 object after completion so that a Notification Recipient can query 1749 the Job object after receiving the 'job-completed' Event 1750 Notification. 1752 When the Printer creates a Per-Printer Subscription Object, it 1753 populates this attribute with a value that is the sum of the values 1754 of the Printer's "printer-up-time" attribute and the Subscription 1755 Object's "notify-lease-duration" attribute with the following 1756 exception. If the value of the Subscription Object's "notify-lease- 1757 duration" attribute is 0 (i.e., no expiration time), then the value 1758 of this attribute MUST be set to 0 (i.e., no expiration time). 1760 When the Printer powers up, it MUST populate this attribute in each 1761 persistent Subscription Object with a value using the algorithm in 1762 the previous paragraph. 1764 When the "printer-up-time" equals the value of this attribute, the 1765 Printer MUST delete the Subscription Object. A client can extend a 1766 lease of a Per-Printer Subscription Object with the Renew- 1767 Subscription operation (see section 11.2.6). 1769 Note: In order to compute the number of seconds remaining in a lease 1770 for a Per-Printer Subscription Object, a client can subtract the 1771 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1772 from the Subscription's "notify-lease-expiration-time" attribute. 1774 5.4.4 notify-printer-up-time (integer(1:MAX)) 1776 This attribute is an alias for the Printer's "printer-up-time" 1777 attribute " (see [RFC2911] section 4.4.29). In other words, when 1778 this attribute is queried with the Get-Subscriptions or Get- 1779 Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), 1780 the value returned is the current value of the Printer's "printer-up- 1781 time" attribute, rather than the time at which the Subscription 1782 Object was created. 1784 A Printer MUST support this attribute. 1786 When the Printer creates a Per-Job Subscription Object, this 1787 attribute MUST NOT be present. When the Printer creates a Per- 1788 Printer Subscription Object, this attribute MUST be present. 1790 Note: this attribute exists in a Per-Printer Subscription Object so 1791 that a client using the Get-Subscription-Attributes or Get- 1792 Subscription operations can convert the Per-Printer Subscription's 1793 "notify-lease-expiration-time" attribute to wall clock time with one 1794 request. If the value of the "notify-lease-expiration-time" 1795 attribute is not 0 (i.e., no expiration time), then the difference 1796 between the "notify-lease-expiration-time" attribute and the "notify- 1797 printer-up-time" is the remaining number of seconds on the lease from 1798 the current time. 1800 5.4.5 notify-printer-uri (uri) 1802 This attribute identifies the Printer object that created this 1803 Subscription Object. 1805 A Printer MUST support this attribute. 1807 During a Subscription Creation Operation, the Printer MUST populate 1808 this attribute with the value of the "printer-uri" operation 1809 attribute in the request. From the Printer URI, the client can, for 1810 example, determine what security scheme was used. 1812 5.4.6 notify-job-id (integer(1:MAX)) 1814 This attribute specifies whether the containing Subscription Object 1815 is a Per-Job or Per-Printer Subscription Object, and for Per-Job 1816 Subscription Objects, it specifies the associated Job. 1818 A Printer MUST support this attribute. 1820 If this attribute is not present, the Subscription Object MUST be a 1821 Per-Printer Subscription. If this attribute is present, the 1822 Subscription Object MUST be a Per-Job Subscription Object and this 1823 attribute MUST identify the Job with which the Subscription Object is 1824 associated. 1826 Note: This attribute could be useful to a Notification Recipient that 1827 receives an Event Notification generated from a Per-Job Subscription 1828 Object and caused by a Printer Event. The Event Notification gives 1829 access to the Printer and the Subscription Object. The Event 1830 Notification gives access to the associated Job only via this 1831 attribute. See discussion of the 'job-completed' event in section 1832 5.3.3.4.3 about retention of the Job object after completion so that 1833 a Notification Recipient can query the Job object after receiving the 1834 'job-completed' Event Notification. 1836 5.4.7 notify-subscriber-user-name (name(MAX)) 1838 This attribute contains the name of the user who performed the 1839 Subscription Creation Operation. 1841 A Printer MUST support this attribute. 1843 The Printer MUST populates this attribute with the most authenticated 1844 printable name that it can obtain from the authentication service 1845 over which the Subscription Creation Operation was received. The 1846 Printer uses the same mechanism for determining the value of this 1847 attribute as it does for a Job's "job-originating-user-name" (see 1848 [RFC2911] section 4.3.6). 1850 Note: To help with authentication, a Subscription Object may have 1851 additional private attributes about the user, e.g., a credential of a 1852 principal. Such private attributes are implementation-dependent and 1853 not defined in this document. 1855 6 Printer Description Attributes Related to Notification 1857 This section defines the Printer Description attributes that are 1858 related to Notification. Table 3 lists the Printer Description 1859 attributes, indicates the Printer support required for conformance, 1860 and whether or not the attribute is READ-ONLY (see section 3.1): 1862 Table 3 - Printer Description Attributes Associated with Notification 1864 Printer object attributes: REQUIRED READ-ONLY 1866 printer-state-change-time (integer(1:MAX)) No Yes 1868 printer-state-change-date-time (dateTime) No Yes 1870 6.1 printer-state-change-time (integer(1:MAX)) 1872 This OPTIONAL attribute records the most recent time at which the 1873 'printer-state-changed' Printer Event occurred whether or not any 1874 Subscription objects were listening for this event. This attribute 1875 helps a client or operator to determine how long the Printer has been 1876 in its current state. 1878 A Printer MAY support this attribute and if so, the attribute MUST be 1879 READ-ONLY. 1881 On power-up, the Printer MUST populate this attribute with the value 1882 of its "printer-up-time" attribute, so that it always has a value. 1883 Whenever the 'printer-state-changed' Printer Event occurs, the 1884 Printer MUST update this attribute with the value of the Printer's 1885 "printer-up-time" attribute. 1887 6.2 printer-state-change-date-time (dateTime) 1889 This OPTIONAL attribute records the most recent time at which the 1890 'printer-state-changed' Printer Event occurred whether or not there 1891 were any Subscription Objects listening for this event. This 1892 attribute helps a client or operator to determine how long the 1893 Printer has been in its current state. 1895 A Printer MAY support this attribute and if so, the attribute MUST be 1896 READ-ONLY. 1898 On power-up, the Printer MUST populate this attribute with the value 1899 of its "printer-current-time" attribute, so that it always has a 1900 value (see [RFC2911] section 4.4.30 on "printer-current-time"). 1901 Whenever the 'printer-state-changed' Printer Event occurs, the 1902 Printer MUST update this attribute with the value of the Printer's 1903 "printer-current-time" attribute. 1905 7 New Values for Existing Printer Description Attributes 1907 This section contains those attributes for which additional values 1908 are added. 1910 7.1 operations-supported (1setOf type2 enum) 1912 The following "operation-id" values are added in order to support the 1913 new operations defined in this document: 1915 Table 4 - Operation-id assignments 1917 Value Operation Name 1919 0x0016 Create-Printer-Subscriptions 1921 0x0017 Create-Job-Subscriptions 1923 0x0018 Get-Subscription-Attributes 1925 0x0019 Get-Subscriptions 1927 0x001A Renew-Subscription 1929 0x001B Cancel-Subscription 1931 8 Attributes Only in Event Notifications 1933 This section contains those attributes that exist only in Event 1934 Notifications and do not exist in any objects. 1936 8.1 notify-subscribed-event (type2 keyword) 1938 This attribute indicates the Subscribed Event that caused the Printer 1939 to deliver this Event Notification. This attribute exists only in 1940 Event Notifications. 1942 This attribute MUST contain one of the values of the "notify-events" 1943 attribute in the Subscription Object, i.e., one of the Subscribed 1944 Event values. Its value is the Subscribed Event that "matches" the 1945 Event that caused the Printer to deliver this Event Notification. 1946 This Subscribed Event value may be identical to the Event or the 1947 Event may be a sub-value of the Subscribed Event. For example, the 1948 'job-completed' Event (which is a sub-event of the 'job-state- 1949 changed' event) would cause the Printer to deliver an Event 1950 Notification for either the 'job-completed' or 'job-state-changed' 1951 Subscribed Events and to deliver the 'job-completed' or 'job-state- 1952 changed' value for this attribute, respectively. See section 5.3.3.5 1953 for the "matching" rules of Subscribed Events and for additional 1954 examples. 1956 The Delivery Method Document specifies whether the Printer includes 1957 the value of this attribute in an Event Notification. 1959 8.2 notify-text (text(MAX)) 1961 This attribute contains a Human Consumable text message (see section 1962 9.2). This message describes the Event and is encoded as plain text, 1963 i.e., 'text/plain' with the charset specified by Subscription 1964 Object's "notify-charset" attribute. 1966 The Delivery Method Document specifies whether the Printer includes 1967 this attribute in an Event Notification. 1969 9 Event Notification Content 1971 This section defines the Event Notification content that the Printer 1972 delivers when an Event occurs. 1974 When an Event occurs, the Printer MUST find each Subscription object 1975 whose "notify-events" attribute "matches" the Event. See section 1976 5.3.3.5 for details on "matching". For each matched Subscription 1977 Object, the Printer MUST create an Event Notification with the 1978 content and format that the Delivery Method Document specifies. The 1979 content contains the value of attributes specified by the Delivery 1980 Method Document. The Printer obtains the values immediately after 1981 the Event occurs. For example, if the "printer-state" attribute 1982 changes from 'idle' to 'processing', the Event 'printer-state- 1983 changed' occurs and the Printer puts various attributes into the 1984 Event Notification, including "printer-up-time" and "printer-state" 1985 with the values that they have immediately after the Event occurs, 1986 i.e., the value of "printer-state" is 'processing'. 1988 Event Notification Ordering: 1990 When a Printer delivers Event Notifications, the Event Notifications 1991 from any given Subscription Object MUST be in time stamp order, i.e., 1992 in order of increasing "printer-up-time" attribute value in the Event 1993 Notification (see Table 5). These Event Notifications MAY be 1994 interleaved with those from other Subscription Objects, as long as 1995 those others are also in time stamp order. The Printer MUST observe 1996 these ordering requirements whether delivering multiple pending 1997 Events as multiple separate Event Notifications or together in a 1998 single Compound Event Notification. 2000 If a Subscribing Client wants the Printer to deliver certain Event 2001 Notifications in time stamp order, the Subscribing Client uses a 2002 single Subscription Object. Even so, depending on the underlying 2003 transport, the actual order that a Notification Recipient receives 2004 separate Event Notifications may differ from the order sent by the 2005 Printer (e.g., email). 2007 Example: Consider two Per-Printer Subscription Objects: SO1 and SO2. 2008 SO1 requests 'job-state-changed' events and SO2 requests 'printer- 2009 state-changed' events. The number in parens is the time stamp. The 2010 following Event Notification sequences are the only ones that conform 2011 to the ordering requirements for the Printer to deliver the Event 2012 Notifications: 2014 (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 2015 'job-completed' (1009), SO2: 'printer-stopped' (1005) 2017 (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2: 2018 'printer-stopped' (1005), SO1: 'job-completed' (1009) 2020 (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1: 2021 'job-stopped' (1005), SO1: 'job-completed' (1009) 2023 (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1: 2024 'job-stopped' (1005), SO1: 'job-completed' (1009) 2026 Examples (b) and (c) are interleaved; examples (a) and (d) are not 2027 interleaved and are not appropriate for some Delivery Methods. 2029 If two different Events occur simultaneously, or nearly so (e.g., 2030 "printer-up-time" has the same value for both), the Printer MUST 2031 create a separate Event Notification for each Event, even if the 2032 associated Subscription Object is the same for both Events. However, 2033 the Printer MAY combine these distinct Event Notifications into a 2034 single Compound Event Notification if the Delivery Method supports 2035 Compound Event Notifications. For example, suppose that two nearly- 2036 simultaneously Events represent two successive 'printer-state- 2037 changed' Events, one from 'idle' to 'processing' and another from 2038 'processing' to 'stopped'. These two Events have the same name but 2039 are different instances of the Event. Then the Printer MUST create a 2040 separate Event Notification for each Event and SHOULD accurately 2041 report the "printer-state" of the first Event as 'processing' and the 2042 second Event as 'stopped'. 2044 If a Subscription Object contains more than one Subscribed Event, and 2045 several Events occur in quick succession each matching a different 2046 Subscribed Event in the Subscription Object, the Printer MUST NOT 2047 generate a single Event Notification from several of these Events, 2048 but MAY combine distinct Event Notifications into a single Compound 2049 Event Notification if the Delivery Method supports Compound Event 2050 Notifications. 2052 After the Printer has created the Event Notification, the Printer 2053 delivers it via either a: 2055 Push Delivery Method: The Printer delivers the Event 2056 Notification shortly after an Event occurs. For some Push 2057 Delivery Methods, the Notification Recipient MUST deliver a 2058 response; for others it MUST NOT deliver a response. 2060 Pull Delivery Method: The Printer saves Event Notifications for 2061 some Event Life and expects the Notification Recipient to 2062 request Event Notifications. The Printer returns the Event 2063 Notifications in a response to such a request. 2065 If an error that meets the following conditions occurs, the Printer 2066 MUST cancel the Subscription Object. 2068 a)the error occurs during the delivering of an Event Notification 2069 generated from Subscription Object S AND 2071 b)the error would continue to occur every time the Printer delivers 2072 an Event Notification generated from Subscription Object S in the 2073 future. 2075 For example, if the address of the "notify-recipient-uri" of 2076 Subscription Object A references a non-existent target and the 2077 Printer determines this fact, it MUST delete Subscription Object A. 2079 The next two sections describe the values that a Printer delivers in 2080 the content of Machine Consumable and Human Consumable Event 2081 Notifications, respectively. 2083 The tables in the sub-sections of this section contain the following 2084 columns: 2086 a)Source Value: the name of the attribute that supplies the value 2087 for the Event Notification. Asterisks in this field refer to a 2088 note below the table. 2090 b)Delivers: if the Printer supports the value (column 1) on the 2091 Source Object (column 3) the Delivery Method MUST specify: 2093 MUST: that the Printer MUST deliver the value. 2095 SHOULD: either that the Printer MUST deliver the value or that 2096 the value is incompatible with the Delivery Method. 2098 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 2099 or NEED NOT deliver the value. The Delivery Method specifies 2100 the level of conformance for the Printer. 2102 c)Source Object: the object from which the source value comes. If 2103 the object is "Event Notification", the Printer fabricates the 2104 value when it delivers the Event Notification. See section 8. 2106 9.1 Content of Machine Consumable Event Notifications 2108 This section defines the attributes that a Delivery Method MUST 2109 mention in a Delivery Method Document when specifying the Machine 2110 Consumable Event Notification's contents. 2112 This document does not define the order of attributes in Event 2113 Notifications. However, Delivery Method Documents MAY define the 2114 order of some or all of the attributes. 2116 A Delivery Method Document MUST specify additional attributes (if 2117 any) that a Printer implementation delivers in a Machine Consumable 2118 Event Notification. 2120 Notification Recipients MUST be able to accept Event Notifications 2121 containing attributes they do not recognize. What a Notification 2122 Recipient does with an unrecognized attribute is implementation- 2123 dependent. Notification Recipients MAY attempt to display 2124 unrecognized attributes anyway or MAY ignore them. 2126 The next three sections define the attributes in Event Notification 2127 Contents that are: 2129 1.for all Events 2131 2.for Job Events only 2133 3.for Printer Events only 2135 9.1.1 Event Notification Content Common to All Events 2137 This section lists the attributes that a Delivery Method Document 2138 MUST specify for all Events. 2140 Table 5 lists potential values in each Event Notification. 2142 Table 5 - Attributes in Event Notification Content 2144 Source Value Delivers Source Object 2146 notify-subscription-id (integer(1:MAX)) MUST Subscription 2148 notify-printer-uri (uri) MUST Subscription 2150 notify-subscribed-event (type2 keyword) MUST Event 2151 Notification 2153 printer-up-time (integer(MIN:MAX)) MUST Printer 2155 printer-current-time (dateTime) * MUST Printer 2157 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 2159 notify-charset (charset) SHOULD Subscription 2161 notify-natural-language (naturalLanguage) SHOULD Subscription 2163 notify-user-data (octetString(63)) ** SHOULD Subscription 2165 notify-text (text) SHOULD Event 2166 Notification 2168 attributes from the "notify-attributes" MAY Printer 2169 attribute *** 2171 attributes from the "notify-attributes" MAY Job 2172 attribute *** 2174 attributes from the "notify-attributes" MAY Subscription 2175 attribute *** 2177 *A Printer MUST deliver this value only if and only if it supports 2178 the Printer's "printer-current-time" attribute. 2180 ** If the Subscription Object does not contain a "notify-user-data" 2181 attribute and the Delivery Method Document REQUIRES the Printer to 2182 deliver the "notify-user-data" source value in the Event 2183 Notification, the Printer MUST deliver an octet-string of length 0. 2185 *** The last three rows represent additional attributes that a client 2186 MAY request via the "notify-attributes" attribute. A Printer MAY 2187 support the "notify-attributes" attribute. The Delivery Method MUST 2188 say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED 2189 NOT support the "notify-attributes" attribute and specific values of 2190 this attribute. The Delivery Method MAY say that support for the 2191 "notify-attributes" is conditioned on support of the attribute by the 2192 Printer or it MAY say that Printer MUST support the "notify- 2193 attributes" attribute if the Printer supports the Delivery Method. 2195 9.1.2 Additional Event Notification Content for Job Events 2197 This section lists the additional attributes that a Delivery Method 2198 Document MUST specify for Job Events. See Table 6. 2200 Table 6 - Additional Event Notification Content for Job Events 2202 Source Value Delivers Source 2203 Object 2205 job-id (integer(1:MAX)) MUST Job 2207 job-state (type1 enum) MUST Job 2209 job-state-reasons (1setOf type2 keyword) MUST Job 2211 job-impressions-completed (integer(0:MAX)) * MUST Job 2213 * The Printer MUST deliver the "job-impressions-completed" attribute 2214 in an Event Notification only for the combinations of Events and 2215 Subscribed Events shown in Table 7. 2217 Table 7 - Combinations of Events and Subscribed Events for "job- 2218 impressions-completed" 2220 Job Event Subscribed Job Event 2222 'job-progress' 'job-progress' 2224 'job-completed' 'job-completed' 2226 'job-completed' 'job-state-changed' 2228 9.1.3 Additional Event Notification Content for Printer Events 2230 This section lists the additional attributes that a Delivery Method 2231 Document MUST specify for Printer Events. See Table 8. 2233 Table 8 - Additional Event Notification Content for Printer Events 2235 Source Value Delivers Source Object 2237 printer-state (type1 enum) MUST Printer 2239 printer-state-reasons (1setOf type2 MUST Printer 2240 keyword) 2242 printer-is-accepting-jobs (boolean) MUST Printer 2244 9.2 Content of Human Consumable Event Notification 2246 This section defines the information that a Delivery Method MUST 2247 mention in a Delivery Method Document when specifying the Human 2248 Consumable Event Notifications contents or the value of the "notify- 2249 text" attribute. 2251 Such a Delivery Method MUST specify the following information and a 2252 Printer SHOULD deliver it: 2254 a)the Printer name (see Table 9) 2256 b)the time of the Event (see Table 11) 2257 c)for Printer Events only: 2258 i) the Event (see Table 10) and/or Printer state information 2259 (see Table 14) 2260 d)for Job Events only: 2261 i) the job identity (see Table 12) 2262 ii) the Event (see Table 10) and/or Job state information (see 2263 Table 13) 2265 The subsections of this section specify the attributes that a Printer 2266 MUST use to obtain this information. 2268 A Delivery Method Document MUST specify additional information (if 2269 any) that a Printer implementation delivers in a Human Consumable 2270 Event Notification or in the "notify-text" attribute. 2272 A client MUST NOT request additional attributes via the "notify- 2273 attributes" attribute because this attribute works only for Machine 2274 Consumable Event Notifications. 2276 Notification Recipients MUST NOT expect to be able to parse the Human 2277 Consumable Event Notification contents or the value of the "notify- 2278 text" attribute. 2280 The next three sections define the attributes in Event Notification 2281 Contents that are: 2283 a) for all Events 2284 b) for Job Events only 2285 c) for Printer Events only 2287 9.2.1 Event Notification Content Common to All Events 2289 This section lists the source of the information that a Delivery 2290 Method MUST specify for all Events. 2292 There is a separate table for each piece of information. Each row in 2293 the table represents a source value for the information and the 2294 values are listed in order of preference, with the first one being 2295 the preferred one. An implementation SHOULD use the source value 2296 from the earliest row in each table. It MAY use the source value 2297 from another row instead, or it MAY combine the source values from 2298 several rows. An implementation is free to determine the best way to 2299 present this information. 2301 In all tables of this section, all rows contain a "MAY" in order to 2302 state that the Delivery Method specifies the conformance. 2304 Table 9 lists the source of the information for the Printer Name. 2305 The "printer-name" is more user-friendly unless the Notification 2306 Recipient is in a place where the Printer name is not meaningful. 2307 For example, an implementation could have the intelligence to deliver 2308 the value of the "printer-name" attribute to a Notification Recipient 2309 that can access the Printer via value of the "printer-name" attribute 2310 and otherwise deliver the value of the "notify-printer-uri" 2311 attribute. 2313 Table 9 - Printer Name in Event Notification Content 2315 Source Value Delivers Source Object 2317 printer-name (name(127)) MAY Printer 2319 notify-printer-uri (uri) MAY Subscription 2321 Table 10 lists the source of the information for the Event name. A 2322 Printer MAY combine this information with state information described 2323 for Jobs in Table 13 or for Printers in Table 14. 2325 Table 10 - Event Name in Event Notification Content 2327 Source Value Delivers Source Object 2329 notify-subscribed-event (type2 keyword) MAY Subscription 2331 Table 11 lists the source of the information for the time that the 2332 Event occurred. A Printer can deliver this value only if it supports 2333 the Printer's "printer-current-time" attribute. If a Printer does 2334 not support the "printer-current-time" attribute, it MUST NOT deliver 2335 the "printer-up-time" value instead, since it is not an allowed 2336 option for human consumable information. 2338 Table 11 - Event Time in Event Notification Content 2340 Source Value Delivers Source Object 2342 printer-current-time (dateTime) MAY Printer 2344 9.2.2 Additional Event Notification Content for Job Events 2346 This section lists the source of the additional information that a 2347 Delivery Method MUST specify for Job Events. 2349 Table 12 lists the source of the information for the job name. The 2350 "job-name" is likely more meaningful to a user than "job-id". 2352 Table 12 - Job Name in Event Notification Content 2354 Source Value Delivers Source Object 2356 job-name (name(MAX)) MAY Job 2358 job-id (integer(1:MAX)) MAY Job 2360 Table 13 lists the source of the information for the job state. If a 2361 Printer supports the "job-state-message" and "job-detailed-state- 2362 message" attributes, it SHOULD use those attributes for the job state 2363 information, otherwise, it should fabricate such information from the 2364 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2365 combine this information with Event information. 2367 Table 13 - Job State in Event Notification Content 2369 Source Value Delivers Source 2370 Object 2372 job-state-message (text(MAX)) MAY Job 2374 job-detailed-status-messages (1setOf text(MAX)) MAY Job 2376 job-state (type1 enum) MAY Job 2378 job-state-reasons (1setOf type2 keyword) MAY Job 2380 9.2.3 Additional Event Notification Content for Printer Events 2382 This section lists the source of the additional information that a 2383 Delivery Method MUST specify for Printer Events. 2385 Table 14 lists the source of the information for the printer state. 2386 If a Printer supports the "printer-state-message", it SHOULD use that 2387 attribute for the job state information, otherwise it SHOULD 2388 fabricate such information from the "printer-state" and "printer- 2389 state-reasons". For some Events, a Printer MAY combine this 2390 information with Event information. 2392 Table 14 - Printer State in Event Notification Content 2394 Source Value Delivers Source 2395 Object 2397 printer-state-message (text(MAX)) MAY Printer 2399 printer-state (type1 enum) MAY Printer 2401 printer-state-reasons (1setOf type2 keyword) MAY Printer 2403 printer-is-accepting-jobs (boolean) MAY Printer 2405 10 Delivery Methods 2407 A Delivery Method is the mechanism, i.e., protocol, by which the 2408 Printer delivers an Event Notification to a Notification Recipient. 2409 There are several potential Delivery Methods for Event Notifications, 2410 standardized, as well as proprietary. This specification REQUIRES 2411 that the 'ippget' Pull Delivery Method [ipp-get-method] be supported. 2412 Conforming implementations MAY support additional Push or Pull 2413 Delivery Methods as well. This document does not define any of these 2414 delivery mechanisms. Each Delivery Method MUST be defined in a 2415 Delivery Method Document that is separate from this document. New 2416 Delivery Methods will be created as needed using an extension to the 2417 registration procedures defined in [RFC2911]. Such documents are 2418 registered with IANA (see section 24.7.3). 2420 The following sorts of Delivery Methods are possible: 2422 - The Notification Recipient polls for Event Notifications at 2423 intervals directed by the Printer 2424 - The Printer delivers Event Notifications to the Notification 2425 Recipient using http as the transport. 2427 - The Printer delivers an email message. 2429 This section specifies how to define a Delivery Method Document and 2430 what to put in such a document. 2432 A Delivery Method Document MUST contain an exact copy of the 2433 following paragraph, caption and table. In addition, column 2 of the 2434 table in the Delivery Method Document MUST contain answers to 2435 questions in column 1 for the Delivery Method. Also, the Delivery 2436 Method document MUST contain a reference to this document and call 2437 that reference [ipp-ntfy] because the table contains an [ipp-ntfy] 2438 reference. 2440 If a Printer supports this Delivery Method, the following are its 2441 characteristics. 2443 Table 15 - Information about the Delivery Method 2445 Document Method Conformance Requirement Delivery Method 2446 Realization 2448 1.What is the URL scheme name for the Push 2449 Delivery Method or the keyword method 2450 name for the Pull Delivery Method? 2452 2.Is the Delivery Method REQUIRED, 2453 RECOMMENDED, or OPTIONAL for an IPP 2454 Printer to support? 2456 3.What transport and delivery protocols 2457 does the Printer use to deliver the 2458 Event Notification Content, i.e., what 2459 is the entire network stack? 2461 4.Can several Event Notifications be 2462 combined into a Compound Event 2463 Notification? 2465 5.Is the Delivery Method initiated by the 2466 Notification Recipient (pull), or by the 2467 Printer (push)? 2469 Document Method Conformance Requirement Delivery Method 2470 Realization 2472 6.Is the Event Notification content 2473 Machine Consumable or Human Consumable? 2475 7.What section in this document answers 2476 the following question? For a Machine 2477 Consumable Event Notification, what is 2478 the representation and encoding of 2479 values defined in section 9.1 of [ipp- 2480 ntfy] and the conformance requirements 2481 thereof? For a Human Consumable Event 2482 Notification, what is the representation 2483 and encoding of pieces of information 2484 defined in section 9.2 of [ipp-ntfy] and 2485 the conformance requirements thereof? 2487 8.What are the latency and reliability of 2488 the transport and delivery protocol? 2490 9.What are the security aspects of the 2491 transport and delivery protocol, e.g., 2492 how it is handled in firewalls? 2494 10. What are the content length 2495 restrictions? 2497 11. What are the additional values or 2498 pieces of information that a Printer 2499 delivers in an Event Notification 2500 content and the conformance requirements 2501 thereof? 2503 12. What are the additional Subscription 2504 Template and/or Subscription Description 2505 attributes and the conformance 2506 requirements thereof? 2508 13. What are the additional Printer 2509 Description attributes and the 2510 conformance requirements thereof? 2512 11 Operations for Notification 2514 This section defines all of the operations for Notification. Section 2515 7.1 assigns the "operation-id" for each operation. The following two 2516 sub-sections define Subscription Creation Operations, and other 2517 operations. 2519 11.1 Subscription Creation Operations 2521 This section defines the Subscription Creation Operations. The first 2522 section on Create-Job-Subscriptions gives most of the information. 2523 The other Subscription Creation Operations refer to the section on 2524 Create-Job-Subscriptions, even though the Create-Job-Subscriptions 2525 operation is the only OPTIONAL operation in this document (see 2526 section 12). 2528 A Printer MUST support Create-Printer-Subscriptions and the 2529 Subscription Template Attributes Group in Job Creation operations. 2530 It MAY support Create-Job-Subscriptions operations. 2532 11.1.1 Create-Job-Subscriptions Operation 2534 The operation creates one or more Per-Job Subscription Objects. The 2535 client supplies one or more Subscription Template Attributes Groups 2536 each containing one or more of Subscription Template Attributes 2537 (defined in section 5.3). 2539 Except for errors, the Printer MUST create exactly one Per-Job 2540 Subscription Object from each Subscription Template Attributes Group 2541 in the request, even if the newly created Subscription Object would 2542 have identical behavior to some existing Subscription Object. The 2543 Printer MUST associate each newly created Per-Job Subscription Object 2544 with the target Job, which is specified by the "notify-job-id" 2545 operation attribute. 2547 The Printer MUST accept the request in any of the target job's 'not- 2548 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2549 'processing-stopped'. The Printer MUST NOT change the job's "job- 2550 state" attribute because of this operation. If the target job is in 2551 any of the 'completed' states, i.e., 'completed', 'canceled', or 2552 'aborted, then the Printer MUST reject the request and return the 2553 'client-error-not-possible' status code; the response MUST NOT 2554 contain any Subscription Attribute Groups. 2556 Access Rights: To create Per-Job Subscription Objects, the 2557 authenticated user (see [RFC2911] section 8.3) performing this 2558 operation MUST (1) be the job owner, (2) have Operator or 2559 Administrator access rights for this Printer (see [RFC2911] sections 2560 1 and 8.5), or (3) be otherwise authorized by the Printer's 2561 administrator-configured security policy to create Per-Job 2562 Subscription Objects for the target job. Otherwise the Printer MUST 2563 reject the operation and return: the 'client-error-forbidden', 2564 'client-error-not-authenticated', or 'client-error-not-authorized' 2565 status code as appropriate. 2567 11.1.1.1 Create-Job-Subscriptions Request 2569 The following groups of attributes are part of the Create-Job- 2570 Subscriptions Request: 2572 Group 1: Operation Attributes 2574 Natural Language and Character Set: 2575 The "attributes-charset" and "attributes-natural-language" 2576 attributes as described in [RFC2911] section 3.1.4.1. 2578 Target: 2579 The "printer-uri" attribute which defines the target for this 2580 operation as described in [RFC2911] section 3.1.5. 2582 Requesting User Name: 2583 The "requesting-user-name" attribute SHOULD be supplied by the 2584 client as described in [RFC2911] section 8.3. 2586 11.1.1.1.1 notify-job-id (integer(1:MAX)) 2588 The client MUST supply this attribute and it MUST specify the 2589 Job object to associate the Per-Job Subscription with. The 2590 value of "notify-job-id" MUST be the value of the "job-id" of 2591 the associated Job object. If the client does not supply this 2592 attribute, the Printer MUST reject this request with a 'client- 2593 error-bad-request' status code. 2595 Group 2-N: Subscription Template Attributes 2597 For each occurrence of this group: 2599 The client MUST supply one or more Subscription Template 2600 Attributes in any order. See section 5.3 for a description of 2601 each such attribute. See section 5.2 for details on 2602 processing these attributes. 2604 11.1.1.2 Create-Job-Subscriptions Response 2606 The Printer MUST return to the client the following sets of 2607 attributes as part of a Create-Job-Subscriptions response: 2609 Group 1: Operation Attributes 2611 Status Message: 2612 In addition to the REQUIRED status code returned in every 2613 response, the response OPTIONALLY includes a "status-message" 2614 (text(255)) and/or a "detailed-status-message" (text(MAX)) 2615 operation attribute as described in [RFC2911] sections 13 and 2616 3.1.6. 2618 In this group, the Printer can return any status codes defined 2619 in [RFC2911] and section 12. The following is a description of 2620 the important status codes: 2622 successful-ok: the Printer created all Subscription Objects 2623 requested (see [RFC2911]). 2624 successful-ok-ignored-subscriptions: the Printer created 2625 some Subscription Objects requested but some failed. The 2626 Subscription Attributes Groups with a "notify-status- 2627 code" attribute are the ones that failed (see section 2628 12.1). 2629 client-error-ignored-all-subscriptions: the Printer created 2630 no Subscription Objects requested and all failed. The 2631 Subscription Attributes Groups with a "notify-status- 2632 code" attribute are the ones that failed (see section 2633 12.2). 2634 client-error-not-possible: For this operation and other 2635 Per-Job Subscription operations, this error can occur 2636 because the specified Job has already completed (see 2637 [RFC2911], whether or not the Job is retained in the Job 2638 Retention and/or Job History phases (see [RFC2911] 2639 section 4.3.7.1). 2641 Natural Language and Character Set: 2642 The "attributes-charset" and "attributes-natural-language" 2643 attributes as described in [RFC2911] section 3.1.4.2. 2645 Group 2: Unsupported Attributes 2647 See [RFC2911] section 3.1.7 for details on returning 2648 Unsupported Attributes. This group does not contain any 2649 unsupported Subscription Template Attributes; they are returned 2650 in the Subscription Attributes Group (see below). 2652 Group 3-N: Subscription Attributes 2653 These groups MUST be returned unless the Printer is unable to 2654 interpret the entire request, e.g., the "status-code" parameter 2655 returned in Group 1 has the value: 'client-error-bad-request'. 2657 "notify-status-code" (type2 enum): 2658 Indicates the status of this subscription (see section 13 2659 for the status code definitions). Section 5.2 defines when 2660 this attribute MUST be present in this group. 2662 See section 5.2 for details on the contents of each occurrence 2663 of this group. 2665 11.1.2 Create-Printer-Subscriptions operation 2667 The operation is identical to Create-Job-Subscriptions with 2668 exceptions noted in this section. 2670 The operation creates Per-Printer Subscription Objects instead of 2671 Per-Job Subscription Objects, and associates each newly created Per- 2672 Printer Subscription Object with the Printer specified by the 2673 operation target rather than with a specific Job. 2675 The Printer MUST accept the request in any of its states, i.e., 2676 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its 2677 "printer-state" attribute because of this operation. 2679 Access Rights: To create Per-Printer Subscription Objects, the 2680 authenticated user (see [RFC2911] section 8.3) performing this 2681 operation MUST have (1) Operator or Administrator access rights for 2682 this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise 2683 authorized by the Printer's administrator-configured security policy 2684 to create Per-Printer Subscription Objects for this Printer. 2685 Otherwise, the Printer MUST reject the operation and return: the 2686 'client-error-forbidden', 'client-error-not-authenticated', or 2687 'client-error-not-authorized' status code as appropriate. 2689 11.1.2.1 Create-Printer-Subscriptions Request 2691 The groups are identical to the Create-Job-Subscriptions (see section 2692 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2693 the "notify-job-id" attribute. If the client does supply the 2694 "notify-job-id" attribute, then the Printer MUST treat it as any 2695 other unsupported Operation attribute and MUST return it in the 2696 Unsupported Attributes group. 2698 11.1.2.2 Create-Printer-Subscriptions Response 2700 The groups are identical to the Create-Job-Subscriptions (see section 2701 11.1.1.2). 2703 11.1.3 Job Creation Operations - Extensions for Notification 2705 This document extends the Job Creation operations (see section 3.2) 2706 to create Subscription Objects as a part of the operation. 2708 The Job Creation operations are identical to Create-Job-Subscriptions 2709 operation with exceptions noted in this section. 2711 Unlike the Create-Job-Subscriptions operation, a Job Creation 2712 operation associates the newly created Subscription Objects with the 2713 Job object created by this operation. The operation succeeds if and 2714 only if the Job creation succeeds. If the Printer does not create 2715 some or all of the requested Subscription Objects, the Printer MUST 2716 return a 'successful-ok-ignored-subscriptions' status-code instead 2717 of a 'successful-ok' status-code, but the Printer MUST NOT reject the 2718 operation because of a failure to create Subscription Objects. 2720 If the Job Creation operation includes a Job Template group, the 2721 client MUST supply it after the Operation Attributes group and before 2722 the first Subscription Template Attributes Group. 2724 If a Printer does not support this Notification specification, then 2725 it MUST treat the Subscription Attributes Group like an unknown group 2726 and ignore it (see [RFC2911] section 5.2.2). Because the Printer 2727 ignores the Subscription Attributes Group, it doesn't return them in 2728 the response either, thus indicating to the client that the Printer 2729 doesn't support Notification. 2731 After completion of a successful Job Creation operation, the Printer 2732 generates a 'job-created' event (see section 5.3.3.4.3). 2734 Access Rights: To create Per-Job Subscription Objects, the 2735 authenticated user (see [RFC2911] section 8.3) performing this 2736 operation MUST either have permission to create Jobs on the Printer 2737 or have Operator or Administrator access rights for this Printer (see 2738 [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the 2739 operation and return: the 'client-error-forbidden', 'client-error- 2740 not-authenticated', or 'client-error-not-authorized' status code as 2741 appropriate. 2743 11.1.3.1 Job Creation Request 2745 The groups for this operation are sufficiently different from the 2746 Create-Job-Subscriptions operation that they are all presented here. 2747 The following groups of attributes are supplied as part of a Job 2748 Creation Request: 2750 Group 1: Operation Attributes 2752 Same as defined in [RFC2911] for Print-Job, Print-URI, and 2753 Create-Job requests. 2755 Group 2: Job Template Attributes 2757 The client OPTIONALLY supplies a set of Job Template attributes 2758 as defined in [RFC2911] section 4.2. 2760 Group 3 to N: Subscription Template Attributes 2762 The same as Group 2-N in Create-Job-Subscriptions. See section 2763 11.1.1.1. 2764 Group N+1: Document Content (Print-Job only) 2766 The client MUST supply the document data to be processed. 2768 11.1.3.2 Job Creation Response 2770 The Printer MUST return to the client the following sets of 2771 attributes as part of a Print-Job, Print-URI, and Create-Job 2772 Response: 2774 Group 1: Operation Attributes 2776 Status Message: 2778 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2779 Job requests. 2781 In this group, the Printer can return any status codes defined 2782 in [RFC2911] and section 12. The following is a description of 2783 the important status codes: 2785 successful-ok: the Printer created the Job and all 2786 Subscription Objects requested (see [RFC2911]. 2787 successful-ok-ignored-subscriptions: the Printer created 2788 the Job and not all of the Subscription Objects requested 2789 (see section 12.1). This status-code hides 'successful- 2790 ok-xxx' status-codes that could reveal problems in Job 2791 creation. The Printer MUST NOT return the 'client-error- 2792 ignored-all-subscriptions' status code for Job Creation 2793 operations because the Printer returns an error status- 2794 code only when it fails to create a Job. 2796 Natural Language and Character Set: 2797 The "attributes-charset" and "attributes-natural-language" 2798 attributes as described in [RFC2911] section 3.1.4.2. 2800 Group 2: Unsupported Attributes 2802 See [RFC2911] section 3.1.7 for details on returning 2803 Unsupported Attributes. This group does not contain any 2804 unsupported Subscription Template Attributes; they are returned 2805 in the Subscription Attributes Group (see below). 2807 Group 3: Job Object Attributes 2809 The "job-id" of the Job Object just created, etc., as defined 2810 in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. 2812 Group 4 to N: Subscription Attributes 2814 These groups MUST be returned if and only if the client 2815 supplied Subscription Template Attributes and the operation was 2816 accepted. 2817 See section 5.2 for details on the contents of each occurrence 2818 of this group. 2820 11.2 Other Operations 2822 This section defines other operations on Subscription objects. 2824 11.2.1 Restart-Job Operation - Extensions for Notification 2826 The Restart-Job operation [RFC2911] is neither a Job Creation 2827 operation nor a Subscription Creation operation (see section 3.2). 2828 For the Restart-Job operation, the client MUST NOT supply any Job 2829 Subscription Attributes Groups. The Printer MUST treat any supplied 2830 Job Subscription Attributes as unsupported attributes. 2832 For this operation, the Printer does not return a job-id or any 2833 Subscription Attributes groups because the Printer reuses the 2834 existing Job object with the same job-id and the existing Per-Job 2835 Subscription Objects with the same subscription-ids. However, after 2836 successful completion of this operation, the Printer generates a 2837 'job-created' event (see section 5.3.3.4.3). 2839 11.2.2 Validate-Job Operation - Extensions for Notification 2841 A client can test whether one or more Subscription Objects could be 2842 created using the Validate-Job operation. The client supplies one or 2843 more Subscription Template Attributes Groups (defined in section 2844 5.3), just as in a Job Creation request. 2846 A Printer MUST support this extension to this operation. 2848 The Printer MUST accept requests that are identical to the Job 2849 Creation request defined in section 11.1.3.1, except that the request 2850 MUST NOT contain document data. 2852 The Printer MUST return the same groups and attributes as the Print- 2853 Job operation (section 11.1.3.1) with the following exceptions. The 2854 Printer MUST NOT return a Job Object Attributes Group because no Job 2855 is created. The Printer MUST NOT return the "notify-subscription-id" 2856 attribute in any Subscription Attribute Group because no Subscription 2857 Object is created. 2859 If the Printer would succeed in creating a Subscription Object, the 2860 corresponding Subscription Attributes Group either has no 'status- 2861 code' attribute or a 'status-code' attribute with a value of 2862 'successful-ok-too-many-events' or 'successful-ok-ignored-or- 2863 substituted-attributes' (see sections 5.2 and 13). The status-codes 2864 have the same meaning as in Job Creation except the results state 2865 what "would happen". 2867 The Printer MUST validate Subscription Template Attributes Groups in 2868 the same manner as the Job Creation operations. 2870 11.2.3 Get-Printer-Attributes - Extensions for Notification 2872 This operation is extended so that it returns Printer attributes 2873 defined in this document. 2875 A Printer MUST support this extension to this operation. 2877 In addition to the requirements of [RFC2911] section 3.2.5, a Printer 2878 MUST support the following additional values for the "requested- 2879 attributes" Operation attribute in this operation and return such 2880 attributes in the Printer Object Attributes group of its response. 2882 1.Subscription Template Attributes: Each supported attribute in 2883 column 2 of Table 1. 2885 2.New Printer Description Attributes: Each supported attribute in 2886 section 6. 2888 3.New Group Name: The 'subscription-template' group name, which 2889 names all supported Subscription Template Attribute in column 2 2890 of Table 1. This group name is also used in the Get- 2891 Subscription-Attributes and Get-Subscriptions operation with an 2892 analogous meaning. 2894 4.Extended Group Name: The 'all' group name, which names all 2895 Printer attributes according to [RFC2911] section 3.2.5. In 2896 this extension 'all' names all attributes specified in [RFC2911] 2897 plus those named in items 1 and 2 of this list. 2899 11.2.4 Get-Subscription-Attributes operation 2901 This operation allows a client to request the values of the 2902 attributes of a Subscription Object. 2904 A Printer MUST support this operation. 2906 This operation is almost identical to the Get-Job-Attributes 2907 operation (see [RFC2911] section 3.3.4). The only differences are 2908 that the operation is directed at a Subscription Object rather than a 2909 Job object, and the returned attribute group contains Subscription 2910 Object attributes rather than Job object attributes. 2912 Access Rights: The authenticated user (see [RFC2911] section 8.3) 2913 performing this operation MUST (1) be the Subscription Object owner, 2914 (2) have Operator or Administrator access rights for this Printer 2915 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by 2916 the Printer's administrator-configured security policy to query the 2917 Subscription Object for the target job. Otherwise the Printer MUST 2918 reject the operation and return: the 'client-error-forbidden', 2919 'client-error-not-authenticated', or 'client-error-not-authorized' 2920 status code as appropriate. Furthermore, the Printer's security 2921 policy MAY limit which attributes are returned, in a manner similar 2922 to the Get-Job-Attributes operation (see [RFC2911] end of section 2923 3.3.4.2). 2925 11.2.4.1 Get-Subscription-Attributes Request 2927 The following groups of attributes are part of the Get-Subscription- 2928 Attributes request: 2930 Group 1: Operation Attributes 2932 Natural Language and Character Set: 2933 The "attributes-charset" and "attributes-natural-language" 2934 attributes as described in section [RFC2911] 3.1.4.1. 2936 Target: 2937 The "printer-uri" attribute which defines the target for this 2938 operation as described in [RFC2911] section 3.1.5. 2940 Requesting User Name: 2941 The "requesting-user-name" attribute SHOULD be supplied by the 2942 client as described in [RFC2911] section 8.3. 2944 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)) 2946 The client MUST supply this attribute. The Printer MUST 2947 support this attribute. This attribute specifies the 2948 Subscription Object from which the client is requesting 2949 attributes. If the client omits this attribute, the Printer 2950 MUST reject this request with the 'client-error-bad-request' 2951 status code. 2953 11.2.4.1.2 "requested-attributes" (1setOf keyword) 2955 The client OPTIONALLY supplies this attribute. The Printer 2956 MUST support this attribute. This attribute specifies the 2957 attributes of the specified Subscription Object that the 2958 Printer MUST return in the response. Each value of this 2959 attribute is either an attribute name (defined in sections 5.3 2960 and 5.4) or an attribute group name. The attribute group names 2961 are: 2963 - 'subscription-template': all attributes that are both 2964 defined in section 5.3 and present on the specified 2965 Subscription Object (column 1 of Table 1). 2966 - 'subscription-description': all attributes that are both 2967 defined in section 5.4 and present on the specified 2968 Subscription Object (Table 2). 2969 - 'all': all attributes that are present on the specified 2970 Subscription Object. 2972 A Printer MUST support all these group names. 2974 If the client omits this attribute, the Printer MUST respond as 2975 if this attribute had been supplied with a value of 'all'. 2977 11.2.4.2 Get-Subscription-Attributes Response 2979 The Printer returns the following sets of attributes as part of the 2980 Get-Subscription-Attributes Response: 2982 Group 1: Operation Attributes 2983 Status Message: 2984 Same as [RFC2911]. 2986 Natural Language and Character Set: 2987 The "attributes-charset" and "attributes-natural-language" 2988 attributes as described in [RFC2911] section 3.1.4.2. The 2989 "attributes-natural-language" MAY be the natural language of 2990 the Subscription Object, rather than the one requested. 2992 Group 2: Unsupported Attributes 2994 See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on 2995 returning Unsupported Attributes. 2997 The response NEED NOT contain the "requested-attributes" 2998 operation attribute with any supplied keyword values that were 2999 requested by the client but are not supported by the IPP 3000 object. If the Printer object does return unsupported 3001 attributes referenced in the "requested-attributes" operation 3002 attribute, the values of the "requested-attributes" attribute 3003 returned MUST include only the unsupported keywords that were 3004 requested by the client. If the client had requested a group 3005 name, such as 'all', the resulting unsupported attributes 3006 returned MUST NOT include attribute keyword names described in 3007 the standard but not supported by the implementation. 3009 Group 3: Subscription Attributes 3011 This group contains a set of attributes with their current 3012 values. Each attribute returned in this group: 3014 a)MUST be specified by the "requested-attributes" attribute 3015 in the request, AND 3017 b)MUST be present on the specified Subscription Object AND 3019 c)MUST NOT be restricted by the security policy in force. 3020 For example, a Printer MAY prohibit a client who is not the 3021 creator of a Subscription Object from seeing some or all of 3022 its attributes. See [RFC2911] end of section 3.3.4.2 and 3023 section 8. 3025 The Printer can return the attributes of the Subscription 3026 Object in any order. The client MUST accept the attributes in 3027 any order. 3029 11.2.5 Get-Subscriptions operation 3031 This operation allows a client to retrieve the values of attributes 3032 of all Subscription Objects belonging to a Job or Printer. 3034 A Printer MUST supported this operation. 3036 This operation is similar to the Get-Subscription-Attributes 3037 operation, except that this Get-Subscriptions operation returns 3038 attributes from possibly more than one object. 3040 This operation is similar to the Get-Jobs operation (see [RFC2911] 3041 section 3.2.6), except that the operation returns Subscription 3042 Objects rather than Job objects. 3044 Access Rights: To query Per-Job Subscription Objects of the 3045 specified job (client supplied the "notify-job-id" operation 3046 attribute - see section 11.2.5.1.1), the authenticated user (see 3047 [RFC2911] section 8.3) performing this operation MUST (1) be the 3048 Subscription Object owner, (2) have Operator or Administrator access 3049 rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3050 otherwise authorized by the Printer's administrator-configured 3051 security policy to query the Subscription Object for the target job. 3052 To query Per-Printer Subscription Objects of the Printer (client 3053 omits the "notify-job-id" operation attribute - see section 3054 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) 3055 performing this operation MUST (1) have Operator or Administrator 3056 access rights for this Printer (see [RFC2911] sections 1 and 8.5), or 3057 (2) be otherwise authorized by the Printer's administrator-configured 3058 security policy to query Per-Printer Subscription Objects for the 3059 target Printer. Otherwise the Printer MUST reject the operation and 3060 return: the 'client-error-forbidden', 'client-error-not- 3061 authenticated', or 'client-error-not-authorized' status code as 3062 appropriate. Furthermore, the Printer's security policy MAY limit 3063 which attributes are returned, in a manner similar to the Get-Jobs 3064 and Get-Printer-Attributes operations (see [RFC2911] end of sections 3065 3.2.6.2 and 3.2.5.2). 3067 11.2.5.1 Get-Subscriptions Request 3069 The following groups of attributes are part of the Get-Subscriptions 3070 request: 3072 Group 1: Operation Attributes 3074 Natural Language and Character Set: 3075 The "attributes-charset" and "attributes-natural-language" 3076 attributes as described in [RFC2911] section 3.1.4.1. 3078 Target: 3079 The "printer-uri" attribute which defines the target for this 3080 operation as described in [RFC2911] section 3.1.5. 3082 Requesting User Name: 3083 The "requesting-user-name" attribute SHOULD be supplied by the 3084 client as described in [RFC2911] section 8.3. 3086 11.2.5.1.1 "notify-job-id" (integer(1:MAX)) 3088 If the client specifies this attribute, the Printer returns the 3089 specified attributes of all Per-Job Subscription Objects 3090 associated with the Job whose "job-id" attribute value equals 3091 the value of this attribute. If the client does not specify 3092 this attribute, the Printer returns the specified attributes of 3093 all Per-Printer Subscription Objects. Note: there is no way to 3094 get all Per-Job Subscriptions known to the Printer in a single 3095 operation. A Get-Jobs operation followed by a Get- 3096 Subscriptions operation for each Job will return all Per-Job 3097 Subscriptions. 3099 11.2.5.1.2 "limit" (integer(1:MAX)) 3101 The client OPTIONALLY supplies this attribute. The Printer 3102 MUST support this attribute. It is an integer value that 3103 determines the maximum number of Subscription Objects that a 3104 client will receive from the Printer even if the "my- 3105 subscriptions" attribute constrains which Subscription Objects 3106 are returned. The limit is a "stateless limit" in that if the 3107 value supplied by the client is 'N', then only the first 'N' 3108 Subscription Objects are returned in the Get-Subscriptions 3109 Response. There is no mechanism to allow for the next 'M' 3110 Subscription Objects after the first 'N' Subscription Objects. 3111 If the client does not supply this attribute, the Printer 3112 responds with all applicable Subscription Objects. 3114 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword) 3116 The client OPTIONALLY supplies this attribute. The Printer 3117 MUST support this attribute. This attribute specifies the 3118 attributes of the specified Subscription Objects that the 3119 Printer MUST return in the response. Each value of this 3120 attribute is either an attribute name (defined in sections 5.3 3121 and 5.4) or an attribute group name (defined in section 3122 11.2.4.1). If the client omits this attribute, the Printer 3123 MUST respond as if the client had supplied this attribute with 3124 the one value: 'notify-subscription-id'. 3126 11.2.5.1.4 "my-subscriptions" (boolean) 3128 The client OPTIONALLY supplies this attribute. The Printer 3129 MUST support this attribute. If the value is 'false', the 3130 Printer MUST consider the Subscription Objects from all users 3131 as candidates. If the value is 'true', the Printer MUST return 3132 the Subscription Objects created by the requesting user of this 3133 request. If the client does not supply this attribute, the 3134 Printer MUST respond as if the client had supplied the 3135 attribute with a value of 'false'. The means for 3136 authenticating the requesting user and matching the 3137 Subscription Objects is similar to that for Jobs which is 3138 described in [RFC2911] section 8. 3140 11.2.5.2 Get-Subscriptions Response 3142 The Printer returns the following sets of attributes as part of the 3143 Get-Subscriptions Response: 3145 Group 1: Operation Attributes 3147 Status Message: 3148 Same as [RFC2911]. 3150 Natural Language and Character Set: 3151 The "attributes-charset" and "attributes-natural-language" 3152 attributes as described in [RFC2911] section 3.1.4.2. 3154 Group 2: Unsupported Attributes 3156 Same as for Get-Subscription-Attributes. 3158 Groups 3 to N: Subscription Attributes 3160 The Printer responds with one Subscription Attributes Group for 3161 each requested Subscription Object (see the "notify-job-id" 3162 attribute in the Operation Attributes Group of this operation). 3164 The Printer returns Subscription Objects in any order. 3166 If the "limit" attribute is present in the Operation Attributes 3167 group of the request, the number of Subscription Attributes 3168 Groups in the response MUST NOT exceed the value of the "limit" 3169 attribute. 3171 It there are no Subscription Objects associated with the 3172 specified Job or Printer, the Printer MUST return zero 3173 Subscription Attributes Groups and it MUST NOT treat this case 3174 as an error, i.e., the status-code MUST be 'successful-ok' 3175 unless something else causes the status code to have some other 3176 value. 3178 See the Group 3 response (Subscription Attributes Group) of the 3179 Get-Subscription-Attributes operation (section 11.2.4.2) for 3180 the attributes that a Printer returns in this group. 3182 11.2.6 Renew-Subscription operation 3184 This operation allows a client to request the Printer to extend the 3185 lease on a Per-Printer Subscription Object. 3187 The Printer MUST support this operation. 3189 The Printer MUST accept this request for a Per-Printer Subscription 3190 Object in any of the target Printer's states, i.e., 'idle', 3191 'processing', or 'stopped', but MUST NOT change the Printer's 3192 "printer-state" attribute. 3194 The Printer MUST reject this request for a Per-Job Subscription 3195 Object because it has no lease (see section 5.4.3). The status code 3196 returned MUST be 'client-error-not-possible'. 3198 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3199 performing this operation MUST (1) be the owner of the Per-Printer 3200 Subscription Object, (2) have Operator or Administrator access rights 3201 for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3202 otherwise authorized by the Printer's administrator-configured 3203 security policy to renew Per-Printer Subscription Objects for the 3204 target Printer. Otherwise, the Printer MUST reject the operation and 3205 return: the 'client-error-forbidden', 'client-error-not- 3206 authenticated', or 'client-error-not-authorized' status code as 3207 appropriate. 3209 11.2.6.1 Renew-Subscription Request 3211 The following groups of attributes are part of the Renew-Subscription 3212 Request: 3214 Group 1: Operation Attributes 3216 Natural Language and Character Set: 3217 The "attributes-charset" and "attributes-natural-language" 3218 attributes as described in [RFC2911] section 3.1.4.1. 3220 Target: 3221 The "printer-uri" attribute which defines the target for this 3222 operation as described in [RFC2911] section 3.1.5. 3224 Requesting User Name: 3225 The "requesting-user-name" (name(MAX)) attribute SHOULD be 3226 supplied by the client as described in [RFC2911] section 8.3. 3228 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)) 3230 The client MUST supply this attribute. The Printer MUST 3231 support this attribute. This attribute specifies the Per- 3232 Printer Subscription Object whose lease the Printer MUST renew. 3233 If the client omits this attribute, the Printer MUST reject 3234 this request with the 'client-error-bad-request' status code. 3236 Group 2: Subscription Template Attributes 3238 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX)) 3240 The client MAY supply this attribute. It indicates the number 3241 of seconds to renew the lease for the specified Subscription 3242 Object. A value of 0 requests an infinite lease (which MAY 3243 require Operator access rights). If the client omits this 3244 attribute, the Printer MUST use the value of the Printer's 3245 "notify-lease-duration-default" attribute. See section 5.3.8 3246 for more details. 3248 11.2.6.2 Renew-Subscription Response 3250 The Printer returns the following sets of attributes as part of the 3251 Renew-Subscription Response: 3253 Group 1: Operation Attributes 3255 Status Message: 3256 Same as [RFC2911]. 3258 The following are some of the status codes returned (see 3259 [RFC2911]: 3261 successful-ok: The operation successfully renewed the lease 3262 on the Subscription Object for the requested duration. 3263 successful-ok-ignored-or-substituted-attributes: The 3264 operation successfully renewed the lease on the 3265 Subscription Object for some duration other than the 3266 amount requested. 3267 client-error-not-possible: The operation failed because the 3268 "notify-subscription-id" Operation attribute identified a 3269 Per-Job Subscription Object. 3270 client-error-not-found: The operation failed because the 3271 "notify-subscription-id" Operation attribute identified a 3272 non-existent Subscription Object. 3274 Natural Language and Character Set: 3275 The "attributes-charset" and "attributes-natural-language" 3276 attributes as described in [RFC2911] section 3.1.4.2. The 3277 "attributes-natural-language" MAY be the natural language of 3278 the Subscription Object, rather than the one requested. 3280 Group 2: Unsupported Attributes 3282 See [RFC2911] section 3.1.7 for details on returning 3283 Unsupported Attributes. 3285 Group 3: Subscription Attributes 3287 The Printer MUST return the following Subscription Attribute: 3289 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX)) 3291 The value of this attribute MUST be the number of seconds that 3292 the Printer has granted for the lease of the Subscription 3293 Object (see section 5.3.8 for details, such as the value of 3294 this attribute when the Printer doesn't support the requested 3295 value). 3297 11.2.7 Cancel-Subscription operation 3299 This operation allows a client to delete a Subscription Object and 3300 stop the Printer from delivering more Event Notifications. Once 3301 performed, there is no way to reference the Subscription Object. 3303 A Printer MUST supported this operation. 3305 The Printer MUST accept this request in any of the target Printer's 3306 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 3307 the Printer's "printer-state" attribute. 3309 If the specified Subscription Object is a Per-Job Subscription 3310 Object, the Printer MUST accept this request in any of the target 3311 Job's states, but MUST NOT change the Job's "job-state" attribute or 3312 affect the Job. 3314 Note: There is no way to change any attributes on a Subscription 3315 Object, except the "notify-lease-duration" attribute (using the 3316 Renew-Subscription operation). In order to change other attributes, 3317 a client performs a Subscription Creation Operation and Cancel- 3318 Subscription operation on the old Subscription Object. If the client 3319 wants to avoid missing Event Notifications, it performs the 3320 Subscription Creation Operation first. If this order would create 3321 too many Subscription Objects on the Printer, the client reverses the 3322 order. 3324 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3325 performing this operation MUST (1) be the owner of the Subscription 3326 Object, (2) have Operator or Administrator access rights for the 3327 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 3328 authorized by the Printer's administrator-configured security policy 3329 to cancel the target Subscription Object. Otherwise, the Printer 3330 MUST reject the operation and return: the 'client-error-forbidden', 3331 'client-error-not-authenticated', or 'client-error-not-authorized' 3332 status code as appropriate. 3334 11.2.7.1 Cancel-Subscription Request 3336 The following groups of attributes are part of the Cancel- 3337 Subscription Request: 3339 Group 1: Operation Attributes 3341 Natural Language and Character Set: 3342 The "attributes-charset" and "attributes-natural-language" 3343 attributes as described in [RFC2911] section 3.1.4.1. 3345 Target: 3346 The "printer-uri" attribute which defines the target for this 3347 operation as described in [RFC2911] section 3.1.5. 3349 Requesting User Name: 3350 The "requesting-user-name" attribute SHOULD be supplied by the 3351 client as described in [RFC2911] section 8.3. 3353 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)) 3355 The client MUST supply this attribute. The Printer MUST 3356 support this attribute. This attribute specifies the 3357 Subscription Object that the Printer MUST cancel. If the 3358 client omits this attribute, the Printer MUST reject this 3359 request with the 'client-error-bad-request' status code. 3361 11.2.7.2 Cancel-Subscription Response 3363 The Printer returns the following sets of attributes as part of the 3364 Cancel-Subscription Response: 3366 Group 1: Operation Attributes 3368 Status Message: 3369 Same as [RFC2911]. 3371 The following are some of the status codes returned (see 3372 [RFC2911]: 3374 successful-ok: The operation successfully canceled 3375 (deleted) the Subscription Object. 3376 client-error-not-found: The operation failed because the 3377 "notify-subscription-id" Operation attribute identified a 3378 non-existent Subscription Object. 3380 Natural Language and Character Set: 3381 The "attributes-charset" and "attributes-natural-language" 3382 attributes as described in [RFC2911] section 3.1.4.2. The 3383 "attributes-natural-language" MAY be the natural language of 3384 the Subscription Object, rather than the one requested. 3386 Group 2: Unsupported Attributes 3388 See [RFC2911] section 3.1.7 for details on returning 3389 Unsupported Attributes. 3391 12 Status Codes 3393 The following status codes are defined as extensions for Notification 3394 and are returned as the value of the "status-code" parameter in the 3395 Operation Attributes Group of a response (see [RFC2911] section 3396 3.1.6.1). Operations in this document can also return the status 3397 codes defined in section 13 of [RFC2911]. The 'successful-ok' status 3398 code is an example of such a status code. 3400 12.1 successful-ok-ignored-subscriptions (0x0003) 3402 The Subscription Creation Operation was unable to create all 3403 requested Subscription Objects. 3405 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3406 operation, this status code means that the Printer created one or 3407 more Subscription Objects, but not all requested Subscription 3408 Objects. 3410 For a Job Creation operation, this status code means that the Printer 3411 created the Job along with zero or more Subscription Objects. The 3412 Printer returns this status code even if other job attributes are 3413 unsupported or in conflict. That is, if an IPP Printer finds a 3414 warning that would allow it to return 'successful-ok-ignored- 3415 subscriptions' and either 'successful-ok-ignored-or-substituted- 3416 attributes' and/or 'successful-ok-conflicting-attributes', it MUST 3417 return 'successful-ok-ignored-subscriptions'. 3419 12.2 client-error-ignored-all-subscriptions (0x0414) 3421 This status code is the same as 'successful-ok-ignored-subscriptions' 3422 except that only the Create-Job-Subscriptions and Create-Printer- 3423 Subscriptions operation return it. They return this status code only 3424 when the Printer creates zero Subscription Objects. 3426 13 Status Codes in Subscription Attributes Groups 3428 This section contains values of the "notify-status-code" (type2 enum) 3429 attribute that the Printer returns in a Subscription Attributes Group 3430 in a response when the corresponding Subscription Object: 3432 1.is not created or 3434 2.is created and some of the client-supplied attributes are not 3435 supported. 3437 The following sections are ordered in decreasing order of importance 3438 of the status-codes. 3440 13.1 client-error-uri-scheme-not-supported (0x040C) 3442 This status code is defined in [RFC2911]. This document extends its 3443 meaning and allows it to be in a Subscription Attributes Group of a 3444 response. 3446 The scheme of the client-supplied URI in a "notify-recipient-uri" 3447 Subscription Template Attribute in a Subscription Creation Operation 3448 is not supported. See section 5.3.1. 3450 13.2 client-error-attributes-or-values-not-supported (0x040B) 3452 This status code is defined in [RFC2911]. This document extends its 3453 meaning and allows it to be in a Subscription Attributes Group of a 3454 response. 3456 The method of the client-supplied keyword in a "notify-pull-method" 3457 Subscription Template Attribute in a Subscription Creation Operation 3458 is not supported. See section 5.3.2. 3460 13.3 client-error-too-many-subscriptions (0x0415) 3462 The number of Subscription Objects supported by the Printer would be 3463 exceeded if this Subscription Object were created (see section 5.2). 3465 13.4 successful-ok-too-many-events (0x0005) 3467 The client supplied more Events in the "notify-events" operation 3468 attribute of a Subscription Creation Operation than the Printer 3469 supports, as indicated in its "notify-max-events-supported" Printer 3470 attribute (see section 5.3.3). 3472 13.5 successful-ok-ignored-or-substituted-attributes (0x0001) 3474 This status code is defined in [RFC2911]. This document extends its 3475 meaning to include unsupported Subscription Template Attributes and 3476 it can appear in a Subscription Attributes Group. 3478 14 Encodings of Additional Attribute Tags 3480 This section assigns values to two attributes tags as extensions to 3481 the encoding defined in [RFC2910]). 3483 The "subscription-attributes-tag" delimits Subscription Template 3484 Attributes Groups in requests and Subscription Attributes Groups in 3485 responses. 3487 The "event-notification-attributes-tag" delimits Event Notifications 3488 in Delivery Methods that use an IPP-like encoding. 3490 The following table specifies the values for the delimiter tags: 3492 Tag Value (Hex) Meaning 3494 0x06 "subscription-attributes-tag" 3496 0x07 "event-notification-attributes-tag" 3498 15 Conformance Requirements 3500 It is OPTIONAL for IPP clients and Printers to implement this Event 3501 Notification specification. 3503 15.1 Conformance requirements for clients 3505 If this Event Notification specification is implemented by a client, 3506 the client MUST support the 'ippget' Pull Delivery Method and meet 3507 the conformance requirements as defined in [ipp-get-method] for 3508 clients. A client MAY support additional Delivery Methods. 3510 15.2 Conformance requirements for Printers 3512 If this Event Notification specification is implemented by a Printer, 3513 the Printer MUST: 3515 - meet the Conformance Requirements detailed in section 5 of 3516 [RFC2911]. 3518 - support the Subscription Template Attributes Group in requests 3519 and the Subscription Attributes Group in responses. 3521 - support all of the following attributes: 3523 a.REQUIRED Subscription Object attributes in section 5. 3524 b.REQUIRED Printer Description object attributes in section 6. 3525 c.REQUIRED attributes in Event Notification content in section 3526 8. 3528 - support the 'ippget' Pull Delivery Method and meet the 3529 conformance requirements as defined in [ipp-get-method] for 3530 Printers. The Printer MAY support additional Push and Pull 3531 Delivery Methods. 3533 - deliver Event Notifications that conform to the requirements of 3534 section 9 and the requirements of the Delivery Method Document 3535 for each supported Delivery Method (the conformance 3536 requirements for Delivery Method Documents is specified in 3537 section 10). 3539 - for all of the Job Creation Operations that the Printer 3540 supports, MUST support the REQUIRED extensions for notification 3541 defined in section 11.1.3. 3543 - meet the conformance requirements for operations as described 3544 in Table 16 and meet the requirements for Printers as specified 3545 in the indicated sub-sections of section 11: 3547 Table 16 - Printer Conformance Requirements for Operations 3549 Operation Printer 3550 Conformance 3551 Requirements 3553 Create-Printer-Subscriptions (section 11.1.2) REQUIRED 3555 Create-Job-Subscriptions (section 11.1.1) OPTIONAL 3557 Get-Subscription-Attributes (section 11.2.3) REQUIRED 3559 Get-Subscriptions (section 11.2.5) REQUIRED 3561 Renew-Subscription (section 11.2.6) REQUIRED 3563 Cancel-Subscription (section 11.2.7) REQUIRED 3565 16 Appendix A - Model for Notification with Cascading Printers 3566 (Informative) 3568 With this model (see Figure 2 below), there is an intervening Print 3569 server between the human user and the output-device. So the system 3570 effectively has two Printer objects. There are two cases to 3571 consider. 3573 1.When the Printer 1 (in the server) generates Events, the system 3574 behaves like the client and Printer in Figure 1. In this case, 3575 Printer 1 delivers Event Notifications that are shown as Event 3576 Notifications (A) of Figure 2. 3578 2.When the Printer 2 (in the output-device) generates Events, there 3579 are two possible system configurations: 3581 a)Printer 1 forwards the client-supplied Subscription Creation 3582 Operations to the downstream Printer 2 and lets Printer 2 3583 deliver the Event Notifications directly to the Notification 3584 Recipients supplied by the Client (Event Notifications(C) in the 3585 diagram). 3587 b)Printer 1 performs the client-supplied Subscription Creation 3588 Operations and also forwards the Subscription Creation 3589 Operations to Printer 2 with the Notification Recipient changed 3590 to be the Printer 1. When an Event occurs in Printer 2, Printer 3591 2 delivers the Event Notification (B) to Notification Recipient 3592 of Printer 1, which relays the received Event Notification (B) 3593 to the client-supplied Notification Recipient (as Event 3594 Notifications(A) in the diagram). Note, when a client performs 3595 a Subscription Creation Operation, Printer 1 need not forward 3596 the Subscription Creation Operation to Printer 2 if it would 3597 create a duplicate Subscription Object on Printer 2. 3599 Note: when Printer 1 is forwarding Subscription Creation Operations 3600 to Printer 2, it may request Printer 2 to create additional 3601 Subscription Objects (called "piggy-backing"). Piggy-backing is 3602 useful when: 3604 - Device A is configured to accept (IPP or non-IPP) requests from 3605 other servers. 3607 - Server S wants to receive Job Events that the client didn't 3608 request and Server S wants these Events for jobs it submits and 3609 not for other jobs. 3611 server S device A 3612 +------------+ +------------+ 3613 | | | | 3614 +--------+ Subscription | ###########| | ###########| 3615 | client |--Creation ----># Printer #| Subscription | # Printer #| 3616 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 3617 | ###|#######| Operation | ####|#|####| 3618 +----|---^---+ +-----|-|----+ 3619 +--------+ Event | | | | 3620 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 3621 |ation Re|<-------------Event Notifications(C)-----------------+ 3622 |cipient | 3623 +--------+ 3625 Figure 2 - Model for Notification with Cascading Printers 3627 17 Appendix B - Distributed Model for Notification (Informative) 3629 A Printer implementation could use some other remote notification 3630 server to provide some or most of the service. For example, the 3631 remote notification server could deliver Event Notifications using 3632 Delivery Methods that are not directly supported by the output device 3633 or Printer object. Or, the remote notification server could store 3634 Subscription Objects (passed to it from the output device in response 3635 to Subscription Creation requests), accept Events, format the Event 3636 Notification in the natural language of the Notification Recipient, 3637 and deliver the Event Notifications to the Notification Recipient(s). 3639 Figure 3 shows this partitioning. The interface between the output 3640 device (or Printer object) and the remote notification server is 3641 outside the scope of this document and is intended to be transparent 3642 to the client and this document. 3644 *********************** 3645 * 3646 * Printer in combination 3647 * with the distributed 3648 * Notification Server) 3649 * 3650 * output device or server 3651 * +---------------+ 3652 PDA, desktop, or server * + ########### + 3653 +--------+ * | # # | 3654 | client |---IPP Subscription--------># Printer # | 3655 +--------+ Creation operation * | # Object # | 3656 * | #####|##### | 3657 * +-------|-------+ 3658 * | Subscriptions 3659 * | OR Event 3660 +------------+ * | Notifications 3661 |Notification| IPP-defined * +------v--------+ 3662 |Recipient |<--Event Notifications---| Notification | 3663 +------------+ * | Server | 3664 * +---------------+ 3665 * 3666 ************************* 3667 *** = Implementation configuration opaque boundary 3669 Figure 3 - Opaque Use of a Notification Server Transparent to the 3670 Client 3672 18 Appendix C - Extended Notification Recipient (Informative) 3674 The model allows for an extended Notification Recipient that is 3675 itself a notification server that forwards each Event Notification to 3676 another recipient (called the Ultimate Notification Recipient in this 3677 section). The Delivery Method to the Ultimate Recipient is probably 3678 different from the Delivery Method used by the Printer to the 3679 extended Notification Recipient. 3681 This extended Notification Recipient is transparent to the Printer 3682 but not to the client. 3684 When a client performs a Subscription Creation Operation, it 3685 specifies the extended Notification Recipient as it would any 3686 Notification Recipient. In addition, the client specifies the 3687 Ultimate Notification Recipient in the Subscription Creation 3688 Operation in a manner specified by the extended Notification 3689 Recipient. Typically, it is either some bytes in the value of 3690 "notify-user-data" or some additional parameter in the value of 3691 "notify-recipient-uri". The client also subscribes directly with the 3692 extended Notification Recipient (by means outside this document), 3693 since it is a notification server in its own right. 3695 The IPP Printer treats the extended Notification Recipient like any 3696 other Notification Recipient and the IPP Printer is not aware of the 3697 forwarding. The Delivery Method that the extended Notification 3698 Recipient uses for delivering the Event Notification to the Ultimate 3699 Notification Recipient is beyond the scope of this document and is 3700 transparent to the IPP Printer. 3702 Examples of this extended Notification Recipient are paging, 3703 immediate messaging services, general notification services, and NOS 3704 vendors' infrastructure. Figure 4 shows this approach. 3706 PDA, desktop, or server server or output device 3707 +---------------+ 3708 +--------+ | ########### | 3709 | client |---Subscription Creation -----------># Printer # | 3710 +--------+ Operation | # Object # | 3711 | #####|##### | 3712 +------------+ +------------+ IPP-defined +-------|-------+ 3713 |Ultimate | any |Notification|<--Event Notifications----+ 3714 |Notification|<----|Recipient | 3715 |Recipient | +------------+ 3716 +------------+ (Notification Server) 3718 Figure 4 - Use of an Extended Notification Recipient transparent to 3719 the Printer 3721 19 Appendix D - Details about Conformance Terminology (Normative) 3723 The following paragraphs provide more details about conformance 3724 terminology. 3726 REQUIRED - an adjective used to indicate that a conforming IPP 3727 Printer implementation MUST support the indicated operation, 3728 object, attribute, attribute value, status code, or out-of-band 3729 value in requests and responses. See [RFC2911] "Appendix A - 3730 Terminology for a definition of "support". Since support of this 3731 entire Notification specification is OPTIONAL for conformance to 3732 IPP/1.1, the use of the term REQUIRED in this document means 3733 "REQUIRED if this OPTIONAL Notification specification is 3734 implemented". 3736 RECOMMENDED - an adjective used to indicate that a conforming IPP 3737 Printer implementation is recommended to support the indicated 3738 operation, object, attribute, attribute value, status code, or 3739 out-of-band value in requests and responses. Since support of 3740 this entire Notification specification is OPTIONAL for conformance 3741 to IPP/1.1, the use of the term RECOMMENDED in this document means 3742 "RECOMMENDED if this OPTIONAL Notification specification is 3743 implemented". 3745 OPTIONAL - an adjective used to indicate that a conforming IPP 3746 Printer implementation MAY, but is NOT REQUIRED to, support the 3747 indicated operation, object, attribute, attribute value, status 3748 code, or out-of-band value in requests and responses. 3750 20 Appendix E - Object Model for Notification (Normative) 3752 This section describes the Notification object model that adds a 3753 Subscription Object which together with the Job and Printer object 3754 provide the complete Notification semantics. 3756 The object relationships can be seen pictorially as: 3758 Subscription Objects (Per-Printer Subscriptions) Printer object 3759 +----+ +------------+ 3760 | s1 |<--------------------------------------------->| | 3761 +----++ | | 3762 | s2 |<-------------------------------------------->| p1 | 3763 +----++ | | 3764 | s3 |<------------------------------------------->| | 3765 +----+ +------------+ 3766 Job objects 3767 +---------+ 3768 | | 3769 +----+ | j1 | 3770 | s4 |<------->| | 3771 +----+ | | 3772 | | s4 is a Per-Job Subscription Object 3773 ++--------++ 3774 | | 3775 +----+ | j2 | 3776 | s5 |<------>| | 3777 +----++ | | 3778 | s6 |<----->| | s5 and s6 are Per-Job Subscription 3779 +----+ ++--------++ Objects 3780 | | 3781 | j3 | 3782 | | 3783 | | <----> indicates association 3784 +---------+ 3786 Figure 5 - Object Model for Notification 3788 s1, s2, and s3 are Per-Printer Subscription Objects and can 3789 identify Printer and/or Job Events. 3790 s4, s5, and s6 are Per-Job Subscription Objects and can identify 3791 Printer and/or Job Events. 3793 20.1 Object relationships 3795 This sub-section defines the object relationships between the 3796 Printer, Job, and Subscription Objects by example. Whether Per- 3797 Printer Subscription Objects are actually contained in a Printer 3798 object or are just bi-directionally associated with them in some way 3799 is IMPLEMENTATION DEPENDENT and is transparent to the client. 3800 Similarly, whether Per-Job Subscription Objects are actually 3801 contained in a Job object or are just bi-directionally associated 3802 with them in some way is IMPLEMENTATION DEPENDENT and is transparent 3803 to the client. The object relationships are defined as follows: 3805 20.2 Printer Object and Per-Printer Subscription Objects 3807 1.The Printer object contains (is associated with) zero or more 3808 Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer 3809 Subscription Objects). 3811 2.Each Per-Printer Subscription Object (s1, s2, and s3) is 3812 contained in (or is associated with) exactly one Printer object 3813 (p1). 3815 20.3 Job Object and Per-Job Subscription Objects 3817 1.A Job object (j1, j2, j3) is associated with zero or more Per- 3818 Job Subscription Objects (s4-s6). Job j1 is associated with 3819 Per-Job Subscription Object s4, Job j2 is associated with Per- 3820 Job Subscription Objects s5 and s6, and Job j3 is not associated 3821 with any Per-Job Subscription Object. 3823 2.Each Per-Job Subscription Object is associated with exactly one 3824 Job object. 3826 21 Appendix F - Per-Job versus Per-Printer Subscription Objects 3827 (Normative) 3829 Per-Job and Per-Printer Subscription Objects are quite similar. 3830 Either type of Subscription Object can subscribe to Job Events, 3831 Printer Events, or both. Both types of Subscription Objects can be 3832 queried using the Get-Subscriptions and Get-Subscription-Attributes 3833 operations and canceled using the Cancel-Subscription operation. 3834 Both types of Subscription Objects create Subscription Objects which 3835 have the same Subscription Object attributes defined. However, there 3836 are some semantic differences between Per-Job Subscription Objects 3837 and Per-Printer Subscription Objects. A Per-Job Subscription Object 3838 is established by the client when submitting a job and after creating 3839 the job using the Create-Job-Subscriptions operation by specifying 3840 the "job-id" of the Job with the "notify-job-id" attribute. A Per- 3841 Printer Subscription Object is established between a client and a 3842 Printer using the Create-Printer-Subscriptions operation. Some 3843 specific differences are: 3845 1.A client usually creates one or more Per-Job Subscription 3846 Objects as part of the Job Creation operations (Create-Job, 3847 Print-Job, and Print-URI), rather than using the OPTIONAL 3848 Create-Job-Subscriptions operation, especially since Printer 3849 implementations NEED NOT support the Create-Job-Subscriptions 3850 operation, since it is OPTIONAL. 3852 2.For Per-Job Subscription Objects, the Subscription Object is 3853 only valid while the job is "not-complete" (see sections 5.4.3) 3854 while for the Per-Printer Subscription Objects, the Subscription 3855 Object is valid until the time (in seconds) that the Printer 3856 returned in the "notify-lease-expiration-time" operation 3857 attribute. 3859 3.Job Events in a Per-Job Subscription Object apply only to "one 3860 job" (the Job created by the Job Creation operation or 3861 references by the Create-Job-Subscriptions operation) while Job 3862 Events in a Per-Printer Subscription Object apply to ALL jobs 3863 contained in the IPP Printer. 3865 22 Normative References 3867 [ipp-get-method] 3868 Herriot, R., and T. Hastings, "Internet Printing Protocol (IPP): 3869 The 'ippget' Delivery Method for Event Notifications", , February 21, 2003. 3872 [RFC2119] 3873 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3874 Levels", RFC 2119 , March 1997 3876 [RFC2396] 3877 Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource 3878 Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 3880 [RFC2717] 3881 R. Petke and I. King, "Registration Procedures for URL Scheme 3882 Names", RFC 2717, November 1999. 3884 [RFC2910] 3885 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3886 Printing Protocol/1.1: Encoding and Transport", RFC 2910, September 3887 2000. 3889 [RFC2911] 3890 deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, 3891 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 3892 September 2000. 3894 [RFC3381] 3895 Hastings, T., Lewis, H., and R. Bergman, "IPP: Job Progress 3896 Attributes", RFC 3381, September 2002. 3898 23 Informative References 3900 [IANA-CON] 3901 Narte, T. and H. Alvestrand, "Guidelines for Writing an IANA 3902 Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 3904 [ipp-not-req] 3905 deBry, R., Lewis, H., and T. Hastings, "Internet Printing 3906 Protocol/1.1: Requirements for IPP Notifications", , work in progress, July 17, 2001. 3909 [RFC2565] 3910 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3911 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 3912 1999. 3914 [RFC2566] 3915 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., and P. 3916 Powell, "Internet Printing Protocol/1.0: Model and Semantics", RFC 3917 2566, April 1999. 3919 [RFC2567] 3920 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3921 2567, April 1999. 3923 [RFC2568] 3924 Zilles, S., "Rationale for the Structure and Model and Protocol for 3925 the Internet Printing Protocol", RFC 2568, April 1999. 3927 [RFC2569] 3928 Herriot, R., Hastings, T., Jacobs, N., and J. Martin, "Mapping 3929 between LPD and IPP Protocols", RFC 2569, April 1999. 3931 [RFC2616] 3932 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 3933 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol - 3934 HTTP/1.1", RFC 2616, June 1999. 3936 [RFC3196] 3937 Hastings, T., Manros, C., Zehler, P., Kugler, C., and H. Holst, 3938 "Internet Printing Protocol/1.1: Implementer's Guide", RFC3196, 3939 November 2001. 3941 24 IANA Considerations 3943 This section contains the registration information for IANA to add to 3944 the IPP Registry according to the procedures defined in RFC 2911 3945 [RFC2911] section 6 to cover the definitions in this document. In 3946 addition, this section defines how Events and Delivery Methods will 3947 be registered when they are defined in other documents. The 3948 resulting registrations will be published in the 3949 http://www.iana.org/assignments/ipp-registrations registry. 3951 Note to RFC Editors: Replace RFC NNNN below (but not RFC xxxx) 3952 with the RFC number for this document, so that it accurately 3953 reflects the content of the information for the IANA Registry. 3955 24.1 Attribute Registrations 3957 The following table lists all the attributes defined in this 3958 document. These are to be registered according to the procedures in 3959 RFC 2911 [RFC2911] section 6.2. 3961 Subscription Template attributes: Reference Section 3962 --------------------------------- --------- ------- 3963 notify-attributes (1setOf type2 keyword) [RFCNNNN] 5.3.4 3964 notify-attributes-supported (1setOf type2 keyword) 3965 [RFCNNNN] 5.3.4.1 3966 notify-charset (charset) [RFCNNNN] 5.3.6 3967 notify-events (1setOf type2 keyword) [RFCNNNN] 5.3.3 3968 notify-events-default (1setOf type2 keyword) [RFCNNNN] 5.3.3.1 3969 notify-events-supported (1setOf type2 keyword) [RFCNNNN] 5.3.3.2 3970 notify-lease-duration (integer(0:67108863)) [RFCNNNN] 5.3.8 3971 notify-lease-duration-default (integer(0:67108863)) 3972 [RFCNNNN] 5.3.8.1 3973 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 3974 rangeOfInteger(0:67108863))) [RFCNNNN] 5.3.8.2 3975 notify-max-events-supported (integer(2:MAX)) [RFCNNNN] 5.3.3.3 3976 notify-natural-language (naturalLanguage) [RFCNNNN] 5.3.7 3977 notify-pull-method (type2 keyword) [RFCNNNN] 5.3.2 3978 notify-pull-method-supported (1setOf type2 keyword) 3979 [RFCNNNN] 5.3.2.1 3980 notify-recipient-uri (uri) [RFCNNNN] 5.3.1 3981 notify-schemes-supported (1setOf uriScheme) [RFCNNNN] 5.3.1.1 3982 notify-time-interval (integer(0:MAX)) [RFCNNNN] 5.3.9 3983 notify-user-data (octetString(63)) [RFCNNNN] 5.3.5 3985 Subscription Description Attributes: 3986 notify-job-id (integer(1:MAX))) [RFCNNNN] 5.4.6 3987 notify-lease-expiration-time (integer(0:MAX))) [RFCNNNN] 5.4.3 3988 notify-printer-up-time (integer(1:MAX))) [RFCNNNN] 5.4.4 3989 notify-printer-uri (uri)) [RFCNNNN] 5.4.5 3990 notify-sequence-number (integer (0:MAX))) [RFCNNNN] 5.4.2 3991 notify-subscriber-user-name (name(MAX))) [RFCNNNN] 5.4.7 3992 notify-subscription-id (integer (1:MAX))) [RFCNNNN] 5.4.1 3993 Printer Description Attributes: 3994 printer-state-change-date-time (dateTime)) [RFCNNNN] 6.2 3995 printer-state-change-time (integer(1:MAX))) [RFCNNNN] 6.1 3997 Attributes Only in Event Notifications 3998 notify-subscribed-event (type2 keyword) [RFCNNNN] 8.1 3999 notify-text (text(MAX)) [RFCNNNN] 8.2 4001 24.2 Additional Enum Attribute Value Registrations 4003 The following table lists all the new enum attribute values defined 4004 in this document. These are to be registered according to the 4005 procedures in RFC 2911 [RFC2911] section 6.1. 4007 Attribute 4008 Value Name Reference Section 4009 ------ ----------------------------- --------- ------- 4010 operations-supported (type2 enum) [RFC2911] 4.4.15 4011 0x0016 Create-Printer-Subscriptions [RFCNNNN] 7.1 4012 0x0017 Create-Job-Subscriptions [RFCNNNN] 7.1 4013 0x0018 Get-Subscription-Attributes [RFCNNNN] 7.1 4014 0x0019 Get-Subscriptions [RFCNNNN] 7.1 4015 0x001A Renew-Subscription [RFCNNNN] 7.1 4016 0x001B Cancel-Subscription [RFCNNNN] 7.1 4018 24.3 Operation Registrations 4020 The following table lists all of the operations defined in this 4021 document. These are to be registered according to the procedures in 4022 RFC 2911 [RFC2911] section 6.4. 4024 Operation Name Reference Section 4025 --------------------------------- --------- ------- 4026 Cancel-Subscription [RFCNNNN] 11.2.7 4027 Create-Job - Extensions [RFCNNNN] 11.1.3 4028 Create-Job-Subscriptions [RFCNNNN] 11.1.1 4029 Create-Printer-Subscriptions [RFCNNNN] 11.1.2 4030 Get-Printer-Attributes - Extensions [RFCNNNN] 11.2.3 4031 Get-Subscription-Attributes [RFCNNNN] 11.2.4 4032 Get-Subscriptions [RFCNNNN] 11.2.5 4033 Print-Job - Extensions [RFCNNNN] 11.1.3 4034 Print-URI - Extensions [RFCNNNN] 11.1.3 4035 Renew-Subscription [RFCNNNN] 11.2.6 4036 Validate-Job Operation - Extensions [RFCNNNN] 11.2.2 4038 24.4 Status code Registrations 4040 The following table lists all the status codes defined in this 4041 document. These are to be registered according to the procedures in 4042 RFC 2911 [RFC2911] section 6.6. 4044 Value Status Code Name Reference Section 4045 ----- ---------------------------- --------- ------- 4046 0x0000:0x00FF - Successful: 4047 0x0003 successful-ok-ignored-subscriptions [RFCNNNN] 12.1 4049 0x0400:0x04FF - Client Error: 4050 0x0414 client-error-ignored-all-subscriptions [RFCNNNN] 12.2 4052 24.5 Attribute Group tag Registrations 4054 The following table lists all the attribute group tags defined in 4055 this document. These are to be registered according to the 4056 procedures in RFC 2911 [RFC2911] section 6.5. 4058 Value Attribute Group Tag Name Reference Section 4059 ----- -------------------------------- -------- ------- 4060 0x06 subscription-attributes-tag [RFCNNNN] 14 4061 0x07 event-notification-attributes-tag [RFCNNNN] 14 4063 24.6 Registration of Events 4065 The following table lists all the Events defined in this document as 4066 type2 keywords to be used with the "notify-events", "notify-events- 4067 default", and "notify-events-supported" Subscription Template 4068 attributes (see section 5.3.3)). Rather than creating a separate 4069 section in the IPP Registry for Events, these event keywords will be 4070 registered according to the procedures of [RFC2911] section 7.1 as 4071 additional keyword attribute values for use with the "notify-events" 4072 Subscription Template attribute (see section 5.3.3), i.e., registered 4073 as keyword values for the "notify-events", "notify-events-default", 4074 and "notify-events-supported" attributes: 4076 Attribute (attribute syntax) 4077 Value Reference Section 4078 --------------------- --------- ------- 4079 notify-events (1setOf type2 keyword) [RFCNNNN] 5.3.3 4080 notify-events-default (1setOf type2 keyword) [RFCNNNN] 5.3.3.1 4081 notify-events-supported (1setOf type2 keyword) [RFCNNNN] 5.3.3.2 4082 notify-subscribed-event (type2 keyword) [RFCNNNN] 8.1 4083 No Events: 4084 none [RFCNNNN] 5.3.3.4.1 4085 Printer Events: 4086 printer-state-changed [RFCNNNN] 5.3.3.4.2 4087 printer-restarted [RFCNNNN] 5.3.3.4.2 4088 printer-shutdown [RFCNNNN] 5.3.3.4.2 4089 printer-stopped [RFCNNNN] 5.3.3.4.2 4090 printer-config-changed [RFCNNNN] 5.3.3.4.2 4091 printer-media-changed [RFCNNNN] 5.3.3.4.2 4092 printer-finishings-changed [RFCNNNN] 5.3.3.4.2 4093 printer-queue-order-changed [RFCNNNN] 5.3.3.4.2 4094 Job Events: 4095 job-state-changed [RFCNNNN] 5.3.3.4.3 4096 job-created [RFCNNNN] 5.3.3.4.3 4097 job-completed [RFCNNNN] 5.3.3.4.3 4098 job-stopped [RFCNNNN] 5.3.3.4.3 4099 job-config-changed [RFCNNNN] 5.3.3.4.3 4100 job-progress [RFCNNNN] 5.3.3.4.3 4102 24.7 Registration of Event Notification Delivery Methods 4104 This section describes the requirements and procedures for 4105 registration and publication of Event Notification Delivery Methods 4106 and for the submission of such proposals. 4108 24.7.1 Requirements for Registration of Event Notification Delivery 4109 Methods 4111 Registered IPP Event Notification Delivery Methods are expected to 4112 follow a number of requirements described below. 4114 24.7.1.1 Required Characteristics 4116 A Delivery Method Document MUST either (1) contain all of the 4117 semantics of the Delivery Method or (2) contain the IPP Delivery 4118 Method registration requirements and a profile of some other protocol 4119 that in combination is the Delivery Method (e.g., mailto). The 4120 Delivery Method Document (and any documents it requires) MUST define 4121 either (1) a URL for a Push Delivery Method that the meets the 4122 requirements of [RFC2717]. or (2) a keyword for a Pull Delivery 4123 method. 4125 IPP Event Notification Delivery Method Documents MUST meet the 4126 requirements of this document (see sections 9 and 10). 4128 In addition, a Delivery Method Document MUST contain the following 4129 information: 4131 Type of registration: IPP Event Notification Delivery Method 4132 Name of this delivery method: 4133 Proposed URL scheme name of this Push Delivery Method or the 4134 keyword name of this Pull Delivery Method: 4135 Name of proposer: 4136 Address of proposer: 4137 Email address of proposer: 4138 Is this delivery method REQUIRED or OPTIONAL for conformance to the 4139 IPP Event Notification and Subscriptions document: 4140 Is this delivery method defining Machine Consumable and/or Human 4141 Consumable content: 4143 24.7.1.2 Naming Requirements 4145 Exactly one (URL scheme or keyword) name MUST be assigned to each 4146 Delivery Method. 4148 Each assigned name MUST uniquely identify a single Delivery Method. 4149 All Push Delivery Method names MUST conform to the rules for URL 4150 scheme names, according to [RFC2396] and [RFC2717] for schemes in the 4151 IETF tree. All Pull Delivery Method names MUST conform to the rules 4152 for keywords according to [RFC2911]. 4154 24.7.1.3 Functionality Requirements 4156 Delivery Methods MUST function as a protocol that is capable of 4157 delivering (push or pull) IPP Event Notifications to Notification 4158 Recipients. 4160 24.7.1.4 Usage and Implementation Requirements 4162 Use of a large number of Delivery Methods may hamper 4163 interoperability. However, the use of a large number of undocumented 4164 and/or unlabelled Delivery Methods hampers interoperability even 4165 more. 4167 A Delivery Method should therefore be registered ONLY if it adds 4168 significant functionality that is valuable to a large community, OR 4169 if it documents existing practice in a large community. Note that 4170 Delivery Methods registered for the second reason should be 4171 explicitly marked as being of limited or specialized use and should 4172 only be used with prior bilateral agreement. 4174 24.7.1.5 Publication Requirements 4176 Delivery Method Documents MUST be published in a standards track, 4177 informational, or experimental RFCs. 4179 24.7.2 Registration Procedure 4181 The IPP WG is developing a small number of Delivery Methods which are 4182 intended to be published as standards track RFCs. However, some 4183 parties may wish to register additional Delivery Methods in the 4184 future. This section describes the procedures for these additional 4185 Delivery Methods. 4187 24.7.2.1 Present the proposal to the Community 4189 First the Delivery Method Document MUST be an Internet-Draft with a 4190 target category of standards track, informational, or experimental. 4191 The same MUST be true for any documents that it references. 4193 Deliver the proposed Delivery Method Document proposal to the 4194 "ipp@pwg.org" mailing list. This mailing list has been established 4195 by [RFC2911] for reviewing proposed registrations and discussing 4196 other IPP matters. Proposed Delivery Method Documents are not 4197 formally registered and MUST NOT be used until approved. 4199 The intent of the public posting is to solicit comments and feedback 4200 on the definition and suitability of the Delivery Method and the name 4201 chosen for it over a four week period. 4203 24.7.2.2 Delivery Method Reviewer 4205 The Delivery Method Reviewer is the same person who has been 4206 appointed by the IETF Application Area Director(s) as the IPP 4207 Designated Expert according to [RFC2911] and [IANA-CON]. When the 4208 four week period is over and the IPP Designated Expert is convinced 4209 that consensus has been achieved, the IPP Designated Expert either 4210 approves the request for registration or rejects it. Rejection may 4211 occur because of significant objections raised on the list or 4212 objections raised externally. 4214 Decisions made by the Reviewer must be posted to the ipp@pwg.org 4215 mailing list within 14 days. Decisions made by the Reviewer may be 4216 appealed to the IESG. 4218 24.7.2.3 IANA Registration 4220 Provided that the Delivery Method registration proposal has either 4221 passed review or has been successfully appealed to the IESG, the IANA 4222 will be notified by the delivery method reviewer and asked to 4223 register the Delivery Method and make it available to the community. 4225 24.7.3 Delivery Method Document Registrations 4227 Each Push Delivery Method Document defines a URI scheme. Such a URI 4228 scheme is used in a URI value of the "notification-recipient" (uri) 4229 Subscription Template attribute (see section 5.3.1) and the uriScheme 4230 value of the "notify-schemes-supported" (1setOf uriScheme 5.3.1.1) 4231 Printer attribute(see section ). Rather than creating a separate 4232 section in the IPP Registry for Delivery Methods, Push Delivery 4233 Methods will be registered as an additional value of the "notify- 4234 schemes-supported" Printer attribute. These uriScheme values will be 4235 registered according to the procedures of [RFC2911] section 7.1 for 4236 additional attribute values. Therefore, the IPP Registry entry for a 4237 Push Delivery Method will be of the form: 4239 Attribute 4240 Value Ref. Section 4241 --------------------- -------- ------- 4242 notify-schemes-supported (1setOf uriScheme) RFC xxxx 5.3.1.1 4243 RFC xxxx m.n 4245 Each Pull Delivery Method Document defines a keyword method which is 4246 registered as an additional value of the "notify-pull-method" and 4247 "notify-pull-method-supported" Printer attributes. These keyword 4248 values will be registered according to the procedures of [RFC2911] 4249 section 7.1 for additional attribute values. Therefore, the IPP 4250 Registry entry for a Pull Delivery Method will be of the form: 4252 Attribute 4253 Value Ref. Section 4254 --------------------- -------- ------- 4255 notify-pull-method (type2 keyword) [ipp-ntfy] 5.3.2 4256 notify-pull-method-supported (1setOf type2 keyword) 4257 [ipp-ntfy] 5.3.2.1 4258 RFC xxxx m.n 4260 24.7.4 Registration Template 4262 To: ipp@pwg.org 4263 Subject: Registration of a new Delivery Method 4265 Delivery Method name: 4267 (All Push Delivery Method names must be suitable for use as the value 4268 of a URL scheme in the IETF tree and all Pull Delivery Method names 4269 must be suitable IPP keywords according to [RFC2911]) 4271 Published specification(s): 4273 (A specification for the Delivery Method must be openly available 4274 that accurately describes what is being registered.) 4276 Person & email address to contact for further information: 4278 25 Intellectural Property 4280 The IETF takes no position regarding the validity or scope of any 4281 intellectual property or other rights that might be claimed to 4282 pertain to the implementation or use of the technology described in 4283 this document or the extent to which any license under such rights 4284 might or might not be available; neither does it represent that it 4285 has made any effort to identify any such rights. Information on the 4286 IETF's procedures with respect to rights in standards-track and 4287 standards-related documentation can be found in RFC 2028. Copies of 4288 claims of rights made available for publication and any assurances of 4289 licenses to be made available, or the result of an attempt made to 4290 obtain a general license or permission for the use of such 4291 proprietary rights by implementers or users of this specification can 4292 be obtained from the IETF Secretariat. 4294 The IETF invites any interested party to bring to its attention any 4295 copyrights, patents or patent applications, or other proprietary 4296 rights which may cover technology that may be required to practice 4297 this standard. Please address the information to the IETF Executive 4298 Director. 4300 26 Internationalization Considerations 4302 This IPP Notification specification continues support for the 4303 internationalization of [RFC2911] of attributes containing text 4304 strings and names. Allowing a Subscribing Client to specify a 4305 different natural language and charset for each Subscription Object 4306 increases the internationalization support. 4308 The Printer MUST be able to localize the content of Human Consumable 4309 Event Notifications and to localize the value of "notify-text" 4310 attribute in Machine Consumable Event Notifications that it delivers 4311 to Notification Recipients. For localization, the Printer MUST use 4312 the value of the "notify-charset" attribute and the "notify-natural- 4313 language" attribute in the Subscription Object supplied by the 4314 Subscribing Client. 4316 27 Security Considerations 4318 Clients submitting Notification requests to the IPP Printer have the 4319 same security issues as submitting an IPP/1.1 print job request (see 4320 [RFC2911] section 3.2.1 and section 8). The same mechanisms used by 4321 IPP/1.1 can therefore be used by the client Notification submission. 4322 Operations that require authentication can use the HTTP 4323 authentication. Operations that require privacy can use the HTTP/TLS 4324 privacy. As with IPP/1.1 Print Job Objects, if there is no security 4325 on Subscription Objects, sequential assignment of subscription-ids 4326 exposes the system to a passive traffic monitoring threat. 4328 27.1 Client access rights 4330 The Subscription Object access control model is the same as the 4331 access control model for Job objects. The client MUST have the 4332 following access rights for the indicated Subscription operations: 4334 1. Create-Job-Subscriptions (see section 11.1.1): A Per-Job 4335 Subscription object is associated with a Job. To create Per-Job 4336 Subscription Objects, the authenticated user (see [RFC2911] 4337 section 8.3) performing this operation MUST (1) be the job 4338 owner, (2) have Operator or Administrator access rights for this 4339 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 4340 authorized by the Printer's administrator-configured security 4341 policy to create Per-Job Subscription Objects for the target 4342 job. 4344 2. Create-Printer-Subscriptions (see section 11.1.2): A Per- 4345 Printer Subscription object is associated with the Printer. To 4346 create Per-Printer Subscription Objects, the authenticated user 4347 (see [RFC2911] section 8.3) performing this operation MUST (1) 4348 have Operator or Administrator access rights for this Printer 4349 (see [RFC2911] sections 1 and 8.5) or (2) be otherwise 4350 authorized by the Printer's administrator-configured security 4351 policy to create Per-Printer Subscription Objects for this 4352 Printer. 4354 3. Get-Subscription-Attributes (see section 11.2.4): The access 4355 control model for this operation is the same as that of the Get- 4356 Job-Attributes operation (see [RFC2911] section 3.3.4). The 4357 primary difference is that a Get-Subscription-Attributes 4358 operation is directed at a Subscription Object rather than at a 4359 Job object, and a returned attribute group contains Subscription 4360 Object attributes rather than Job object attributes. To query 4361 the specified Subscription Object, the authenticated user (see 4362 [RFC2911] section 8.3) performing this operation MUST (1) be the 4363 Subscription Object owner, (2) have Operator or Administrator 4364 access rights for this Printer (see [RFC2911] sections 1 and 4365 8.5), or (3) be otherwise authorized by the Printer's 4366 administrator-configured security policy to query the 4367 Subscription Object for the target job. Furthermore, the 4368 Printer's security policy MAY limit which attributes are 4369 returned, in a manner similar to the Get-Job-Attributes 4370 operation (see [RFC2911] end of section 3.3.4.2). 4372 4. Get-Subscriptions (see section 11.2.5): The access control 4373 model for this operation is the same as that of the Get-Jobs 4374 operation (see [RFC2911] section 3.2.6). The primary difference 4375 is that the operation is directed at Subscription Objects rather 4376 than at Job objects, and the returned attribute groups contain 4377 Subscription Object attributes rather than Job object 4378 attributes. To query Per-Job Subscription Objects of the 4379 specified job (client supplied the "notify-job-id" operation 4380 attribute - see section 11.2.5.1.1), the authenticated user (see 4381 [RFC2911] section 8.3) performing this operation MUST (1) be the 4382 Subscription Object owner, (2) have Operator or Administrator 4383 access rights for this Printer (see [RFC2911] sections 1 and 4384 8.5), or (3) be otherwise authorized by the Printer's 4385 administrator-configured security policy to query the 4386 Subscription Object for the target job. To query Per-Printer 4387 Subscription Objects of the Printer (client omits the "notify- 4388 job-id" operation attribute - see section 11.2.5.1.1), the 4389 authenticated user (see [RFC2911] section 8.3) performing this 4390 operation MUST (1) have Operator or Administrator access rights 4391 for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be 4392 otherwise authorized by the Printer's administrator-configured 4393 security policy to query Per-Printer Subscription Objects for 4394 the target Printer. Furthermore, the Printer's security policy 4395 MAY limit which attributes are returned, in a manner similar to 4396 the Get-Job-Attributes operation (see [RFC2911] end of section 4397 3.2.6.2). 4399 5. Renew-Subscriptions (see section 11.2.6): The authenticated 4400 user (see [RFC2911] section 8.3) performing this operation MUST 4401 (1) be the owner of the Per-Printer Subscription Object, (2) 4402 have Operator or Administrator access rights for the Printer 4403 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 4404 authorized by the Printer's administrator-configured security 4405 policy to renew Per-Printer Subscription Objects for the target 4406 Printer 4408 6. Cancel-Subscription (see section 11.2.7): The authenticated 4409 user (see [RFC2911] section 8.3) performing this operation MUST 4410 (1) be the owner of the Subscription Object, (2) have Operator 4411 or Administrator access rights for the Printer (see [RFC2911] 4412 sections 1 and 8.5), or (3) be otherwise authorized by the 4413 Printer's administrator-configured security policy to cancel the 4414 target Subscription Object. 4416 The standard security concerns (delivery to the right user, privacy 4417 of content, tamper proof content) apply to each Delivery Method. 4418 Some Delivery Methods are more secure than others. Each Delivery 4419 Method Document MUST discuss its Security Considerations. 4421 27.2 Printer security threats 4423 Notification trap door: If a Printer supports the OPTIONAL "notify- 4424 attributes" Subscription Template attribute (see section 5.3.4) where 4425 the client can request that the Printer return any specified Job, 4426 Printer, and Subscription object attributes, the Printer MUST apply 4427 the same security policy to these requested attributes in the Get- 4428 Notifications request as it does for the Get-Jobs, Get-Job- 4429 Attributes, Get-Printer-Attributes, and Get-Subscription-Attributes 4430 requests. 4432 27.3 Notification Recipient security threats 4434 Unwanted Events Notifications (spam): For any Push Delivery Method, 4435 by far the biggest security concern is the abuse of notification: 4436 delivering unwanted Event Notifications to third parties (i.e., 4437 spam). The problem is made worse by notification addresses that may 4438 be redistributed to multiple parties. There exist scenarios where 4439 third party notification is used (see Scenario #2 and #3 in [ipp-not- 4440 req]). Any fully secure solution would require active agreement of 4441 all recipients before delivering anything. 4443 28 Contributors 4445 The following people made significant contributions to the design and 4446 review of this specification: 4448 Scott A. Isaacson 4449 Novell, Inc. 4450 122 E 1700 S 4451 Provo, UT 84606 4453 Phone: 801-861-7366 4454 Fax: 801-861-2517 4455 e-mail: sisaacson@novell.com 4457 Roger deBry 4458 Utah Valley State College 4459 Orem, UT 84058 4461 Phone: (801) 222-8000 4462 EMail: debryro@uvsc.edu 4464 Jay Martin 4465 Underscore Inc. 4466 9 Jacqueline St. 4467 Hudson, NH 03051-5308 4468 603-889-7000 4469 fax: 775-414-0245 4470 e-mail: jkm@underscore.com 4472 Michael Shepherd 4473 Xerox Corporation 4474 800 Phillips Road MS 128-51E 4475 Webster, NY 14450 4477 Phone: 716-422-2338 4478 Fax: 716-265-8871 4479 e-mail: mshepherd@usa.xerox.com 4480 Ron Bergman 4481 Hitachi Koki Imaging Solutions 4482 1757 Tapo Canyon Road 4483 Simi Valley, CA 93063-3394 4485 Phone: 805-578-4421 4486 Fax: 805-578-4001 4487 Email: rbergma@hitachi-hkis.com 4489 29 Author's Addresses 4491 Robert Herriot 4492 706 Colorado Ave. 4493 Palo Alto, CA 94303 4495 Phone: 650-327-4466 4496 Fax: 650-327-4466 4497 Email: bob@herriot.com 4499 Tom Hastings 4500 Xerox Corporation 4501 737 Hawaii St. ESAE 231 4502 El Segundo, CA 90245 4504 Phone: 310-333-6413 4505 Fax: 310-333-5514 4506 e-mail: hastings@cp10.es.xerox.com 4508 IPP Web Page: http://www.pwg.org/ipp/ 4509 IPP Mailing List: ipp@pwg.org 4511 To subscribe to the ipp mailing list, send the following email: 4512 1) send it to majordomo@pwg.org 4513 2) leave the subject line blank 4514 3) put the following two lines in the message body: 4515 subscribe ipp 4516 end 4518 Implementers of this specification document are encouraged to join 4519 the IPP Mailing List in order to participate in any discussions of 4520 clarification issues and review of registration proposals for 4521 additional attributes and values. In order to reduce spam the 4522 mailing list rejects mail from non-subscribers, so you must subscribe 4523 to the mailing list in order to send a question or comment to the 4524 mailing list. 4526 30 Appendix G - Description of the base IPP documents (Informative) 4528 The base set of IPP documents includes: 4530 Design Goals for an Internet Printing Protocol [RFC2567] 4531 Rationale for the Structure and Model and Protocol for the Internet 4532 Printing Protocol [RFC2568] 4533 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 4534 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 4535 Internet Printing Protocol/1.1: Implementer's Guide [RFC3196] 4536 Mapping between LPD and IPP Protocols [RFC2569] 4538 The "Design Goals for an Internet Printing Protocol" document takes a 4539 broad look at distributed printing functionality, and it enumerates 4540 real-life scenarios that help to clarify the features that need to be 4541 included in a printing protocol for the Internet. It identifies 4542 requirements for three types of users: end users, operators, and 4543 administrators. It calls out a subset of end user requirements that 4544 are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator 4545 operations have been added to IPP/1.1 [RFC2911, RFC2910]. 4547 The "Rationale for the Structure and Model and Protocol for the 4548 Internet Printing Protocol" document describes IPP from a high level 4549 view, defines a roadmap for the various documents that form the suite 4550 of IPP specification documents, and gives background and rationale 4551 for the IETF IPP working group's major decisions. 4553 The "Internet Printing Protocol/1.1: Model and Semantics" document 4554 describes a simplified model with abstract objects, their attributes, 4555 and their operations. The model introduces a Printer and a Job. The 4556 Job supports multiple documents per Job. The model document also 4557 addresses how security, internationalization, and directory issues 4558 are addressed. 4560 The "Internet Printing Protocol/1.1: Encoding and Transport" document 4561 is a formal mapping of the abstract operations and attributes defined 4562 in the model document onto HTTP/1.1 [RFC2616]. It also defines the 4563 encoding rules for a new Internet MIME media type called 4564 "application/ipp". This document also defines the rules for 4565 transporting over HTTP a message body whose Content-Type is 4566 "application/ipp". This document defines the 'ipp' scheme for 4567 identifying IPP printers and jobs. 4569 The "Internet Printing Protocol/1.1: Implementer's Guide" document 4570 gives insight and advice to implementers of IPP clients and IPP 4571 objects. It is intended to help them understand IPP/1.1 and some of 4572 the considerations that may assist them in the design of their client 4573 and/or IPP object implementations. For example, a typical order of 4574 processing requests is given, including error checking. Motivation 4575 for some of the specification decisions is also included. 4577 The "Mapping between LPD and IPP Protocols" document gives some 4578 advice to implementers of gateways between IPP and LPD (Line Printer 4579 Daemon) implementations. 4581 31 Appendix H - Full Copyright Statement (Informative) 4583 Copyright (C) The Internet Society (1998,1999,2000,2001,2002,2003). 4584 All Rights Reserved 4586 This document and translations of it may be copied and furnished to 4587 others, and derivative works that comment on or otherwise explain it 4588 or assist in its implementation may be prepared, copied, published 4589 and distributed, in whole or in part, without restriction of any 4590 kind, provided that the above copyright notice and this paragraph are 4591 included on all such copies and derivative works. However, this 4592 document itself may not be modified in any way, such as by removing 4593 the copyright notice or references to the Internet Society or other 4594 Internet organizations, except as needed for the purpose of 4595 developing Internet standards in which case the procedures for 4596 copyrights defined in the Internet Standards process must be 4597 followed, or as required to translate it into languages other than 4598 English. 4600 The limited permissions granted above are perpetual and will not be 4601 revoked by the Internet Society or its successors or assigns. 4603 This document and the information contained herein is provided on an 4604 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4605 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4606 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4607 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4608 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4610 Acknowledgement 4612 Funding for the RFC Editor function is currently provided by the 4613 Internet Society.