idnits 2.17.1 draft-ietf-ipp-not-spec-12.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 3751 has weird spacing: '...reation opera...' == Line 4135 has weird spacing: '...FC xxxx m.n...' == Line 4150 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). == 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 (June 21, 2004) is 7241 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 3992, 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 (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Printing Protocol WG R. Herriot 2 INTERNET-DRAFT Global Workflow Solutions 3 T. Hastings 4 Updates RFC 2910 and 2911 Xerox Corporation 5 [Target Category: standards track] June 21, 2004 6 Expires: December 21, 2004 8 Internet Printing Protocol (IPP): 9 Event Notifications and Subscriptions 11 Copyright (C) The Internet Society (2004). All Rights Reserved. 13 Status of this Memo 15 This document is an Internet-Draft and is in full conformance with 16 all provisions of Section 10 of RFC 2026. Internet-Drafts are 17 working documents of the Internet Engineering Task Force (IETF), its 18 areas, and its working groups. Note that other groups may also 19 distribute working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress". 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.html 28 The list of Internet-Draft Shadow Directories can be accessed as 29 http://www.ietf.org/shadow.html. 31 Abstract 33 This document describes an OPTIONAL extension to the Internet 34 Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). 35 This extension allows a client to subscribe to printing related 36 Events. Subscriptions are modeled as Subscription Objects. The 37 Subscription Object specifies that when one of the specified Events 38 occurs, the Printer delivers an asynchronous Event Notification to 39 the specified Notification Recipient via the specified Push or Pull 40 Delivery Method (i.e., protocol). 42 A client associates Subscription Objects with a particular Job by 43 performing the Create-Job-Subscriptions operation or by submitting a 44 Job with subscription information. A client associates Subscription 45 Objects with the Printer by performing a Create-Printer-Subscriptions 46 operation. Four other operations are defined for Subscription 47 Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- 48 Subscription, and Cancel-Subscription. 50 Table of Contents 52 1 Introduction.....................................................7 53 1.1 Notification Overview..........................................7 55 2 Models for Notification.........................................10 56 2.1 Model for Simple Notification (Normative).....................10 57 2.2 Additional Models for Notification (Informative)..............11 59 3 Terminology.....................................................11 60 3.1 Conformance Terminology.......................................11 61 3.2 Other Terminology.............................................11 63 4 Object Relationships............................................14 64 4.1 Printer and Per-Printer Subscription Objects..................14 65 4.2 Printer, Job and Per-Job Subscription Objects.................14 67 5 Subscription Object.............................................15 68 5.1 Rules for Support of Subscription Template Attributes.........15 69 5.2 Rules for Processing Subscription Template Attributes.........16 70 5.3 Subscription Template Attributes..............................20 71 5.3.1 notify-recipient-uri (uri)..................................22 72 5.3.1.1 notify-schemes-supported (1setOf uriScheme)..............23 73 5.3.2 notify-pull-method (type2 keyword)..........................23 74 5.3.2.1 notify-pull-method-supported (1setOf type2 keyword).......23 75 5.3.3 notify-events (1setOf type2 keyword)........................24 76 5.3.3.1 notify-events-default (1setOf type2 keyword)..............24 77 5.3.3.2 notify-events-supported (1setOf type2 keyword)............24 78 5.3.3.3 notify-max-events-supported (integer(2:MAX))..............24 79 5.3.3.4 Standard Values for Subscribed Events.....................25 80 5.3.3.4.1 No Events...............................................25 81 5.3.3.4.2 Subscribed Printer Events...............................25 82 5.3.3.4.3 Subscribed Job Events...................................27 83 5.3.3.5 Rules for Matching of Subscribed Events...................28 84 5.3.3.5.1 Rules for Matching of Printer Events....................28 85 5.3.3.5.2 Rules for Matching of Job Events........................28 86 5.3.3.5.3 Special Cases for Matching Rules........................29 87 5.3.4 notify-attributes (1setOf type2 keyword)....................30 88 5.3.4.1 notify-attributes-supported (1setOf type2 keyword)........32 89 5.3.5 notify-user-data (octetString(63))..........................32 90 5.3.6 notify-charset (charset)....................................32 91 5.3.7 notify-natural-language (naturalLanguage)...................33 92 5.3.8 notify-lease-duration (integer(0:67108863)).................33 93 5.3.8.1 notify-lease-duration-default (integer(0:67108863)).......34 94 5.3.8.2 notify-lease-duration-supported (1setOf (integer(0: 67108863) 95 | rangeOfInteger(0:67108863)))....................................35 96 5.3.9 notify-time-interval (integer(0:MAX)).......................35 97 5.4 Subscription Description Attributes...........................36 98 5.4.1 notify-subscription-id (integer (1:MAX))...................36 99 5.4.2 notify-sequence-number (integer (0:MAX))....................37 100 5.4.3 notify-lease-expiration-time (integer(0:MAX))...............37 101 5.4.4 notify-printer-up-time (integer(1:MAX)).....................38 102 5.4.5 notify-printer-uri (uri)....................................39 103 5.4.6 notify-job-id (integer(1:MAX))..............................39 104 5.4.7 notify-subscriber-user-name (name(MAX)).....................40 106 6 Printer Description Attributes Related to Notification..........40 107 6.1 printer-state-change-time (integer(1:MAX))....................40 108 6.2 printer-state-change-date-time (dateTime).....................41 110 7 New Values for Existing Printer Description Attributes..........41 111 7.1 operations-supported (1setOf type2 enum)......................41 113 8 Attributes Only in Event Notifications..........................42 114 8.1 notify-subscribed-event (type2 keyword).......................42 115 8.2 notify-text (text(MAX)).......................................42 117 9 Event Notification Content......................................43 118 9.1 Content of Machine Consumable Event Notifications.............46 119 9.1.1 Event Notification Content Common to All Events.............46 120 9.1.2 Additional Event Notification Content for Job Events........47 121 9.1.3 Additional Event Notification Content for Printer Events....48 122 9.2 Content of Human Consumable Event Notification................48 123 9.2.1 Event Notification Content Common to All Events.............49 124 9.2.2 Additional Event Notification Content for Job Events........51 125 9.2.3 Additional Event Notification Content for Printer Events....51 127 10 Delivery Methods...............................................52 129 11 Operations for Notification....................................54 130 11.1 Subscription Creation Operations.............................54 131 11.1.1 Create-Job-Subscriptions Operation.........................54 132 11.1.1.1 Create-Job-Subscriptions Request.........................55 133 11.1.1.1.1 notify-job-id (integer(1:MAX)).........................55 134 11.1.1.2 Create-Job-Subscriptions Response........................56 135 11.1.2 Create-Printer-Subscriptions operation.....................57 136 11.1.2.1 Create-Printer-Subscriptions Request.....................58 137 11.1.2.2 Create-Printer-Subscriptions Response....................58 138 11.1.3 Job Creation Operations - Extensions for Notification......58 139 11.1.3.1 Job Creation Request.....................................59 140 11.1.3.2 Job Creation Response....................................59 141 11.2 Other Operations.............................................60 142 11.2.1 Restart-Job Operation - Extensions for Notification........60 143 11.2.2 Validate-Job Operation - Extensions for Notification.......61 144 11.2.3 Get-Printer-Attributes - Extensions for Notification.......61 145 11.2.4 Get-Subscription-Attributes operation......................62 146 11.2.4.1 Get-Subscription-Attributes Request......................63 147 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)).............63 148 11.2.4.1.2 "requested-attributes" (1setOf keyword)................63 149 11.2.4.2 Get-Subscription-Attributes Response.....................64 150 11.2.5 Get-Subscriptions operation................................65 151 11.2.5.1 Get-Subscriptions Request................................66 152 11.2.5.1.1 "notify-job-id" (integer(1:MAX)).......................66 153 11.2.5.1.2 "limit" (integer(1:MAX))...............................66 154 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword)..........67 155 11.2.5.1.4 "my-subscriptions" (boolean)...........................67 156 11.2.5.2 Get-Subscriptions Response...............................67 157 11.2.6 Renew-Subscription operation...............................68 158 11.2.6.1 Renew-Subscription Request...............................69 159 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)).............69 160 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX))...............69 161 11.2.6.2 Renew-Subscription Response..............................69 162 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX))...............70 163 11.2.7 Cancel-Subscription operation..............................70 164 11.2.7.1 Cancel-Subscription Request..............................71 165 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)).............72 166 11.2.7.2 Cancel-Subscription Response.............................72 168 12 Status Codes...................................................72 169 12.1 successful-ok-ignored-subscriptions (0x0003).................73 170 12.2 client-error-ignored-all-subscriptions (0x0414)..............73 172 13 Status Codes in Subscription Attributes Groups.................73 173 13.1 client-error-uri-scheme-not-supported (0x040C)...............74 174 13.2 client-error-attributes-or-values-not-supported (0x040B).....74 175 13.3 client-error-too-many-subscriptions (0x0415).................74 176 13.4 successful-ok-too-many-events (0x0005).......................74 177 13.5 successful-ok-ignored-or-substituted-attributes (0x0001).....74 179 14 Encodings of Additional Attribute Tags.........................74 181 15 Conformance Requirements.......................................75 182 15.1 Conformance requirements for clients.........................75 183 15.2 Conformance requirements for Printers........................75 185 16 Model for Notification with Cascading Printers (Informative)...76 187 17 Distributed Model for Notification (Informative)...............77 189 18 Extended Notification Recipient (Informative)..................78 191 19 Object Model for Notification (Normative)......................79 192 19.1 Object relationships.........................................80 193 19.2 Printer Object and Per-Printer Subscription Objects..........81 194 19.3 Job Object and Per-Job Subscription Objects..................81 195 20 Per-Job versus Per-Printer Subscription Objects (Normative)....81 197 21 Normative References...........................................82 199 22 Informative References.........................................83 201 23 IANA Considerations............................................83 202 23.1 Attribute Registrations......................................84 203 23.2 Additional Enum Attribute Value Registrations within the IPP 204 registry..........................................................85 205 23.3 Operation Registrations......................................85 206 23.4 Status code Registrations....................................86 207 23.5 Attribute Group tag Registrations............................86 208 23.6 Registration of Events.......................................86 209 23.7 Registration of Event Notification Delivery Methods..........87 210 23.7.1 Requirements for Registration of Event Notification Delivery 211 Methods................................................87 212 23.7.1.1 Required Characteristics.................................87 213 23.7.1.2 Naming Requirements......................................88 214 23.7.1.3 Functionality Requirements...............................88 215 23.7.1.4 Usage and Implementation Requirements....................88 216 23.7.1.5 Publication Requirements.................................89 217 23.7.2 Registration Procedure.....................................89 218 23.7.2.1 Present the proposal to the Community....................89 219 23.7.2.2 Delivery Method Reviewer.................................89 220 23.7.2.3 IANA Registration........................................90 221 23.7.3 Delivery Method Document Registrations.....................90 222 23.7.4 Registration Template......................................91 224 24 Intellectual Property..........................................91 226 25 Internationalization Considerations............................92 228 26 Security Considerations........................................92 229 26.1 Client access rights.........................................92 230 26.2 Printer security threats.....................................94 231 26.3 Notification Recipient security threats......................94 233 27 Contributors...................................................95 235 28 Author's Addresses.............................................96 237 29 Description of the base IPP documents (Informative)............96 239 30 Full Copyright Statement.......................................97 241 Tables 242 Table 1 - Subscription Template Attributes........................22 243 Table 2 - Subscription Description Attributes.....................36 244 Table 3 - Printer Description Attributes Associated with Notification 245 ..............................................................40 246 Table 4 - Operation-id assignments................................42 247 Table 5 - Attributes in Event Notification Content................47 248 Table 6 - Additional Event Notification Content for Job Events....48 249 Table 7 - Combinations of Events and Subscribed Events for "job- 250 impressions-completed"........................................48 251 Table 8 - Additional Event Notification Content for Printer Events48 252 Table 9 - Printer Name in Event Notification Content..............50 253 Table 10 - Event Name in Event Notification Content...............50 254 Table 11 - Event Time in Event Notification Content...............50 255 Table 12 - Job Name in Event Notification Content.................51 256 Table 13 - Job State in Event Notification Content................51 257 Table 14 - Printer State in Event Notification Content............52 258 Table 15 - Information about the Delivery Method..................53 259 Table 16 - Printer Conformance Requirements for Operations........76 261 Figures 262 Figure 1 - Model for Notification.................................10 263 Figure 2 - Model for Notification with Cascading Printers.........77 264 Figure 3 - Opaque Use of a Notification Server Transparent to the 265 Client........................................................78 266 Figure 4 - Use of an Extended Notification Recipient transparent to 267 the Printer...................................................79 268 Figure 5 - Object Model for Notification..........................80 270 1 Introduction 272 This IPP notification specification is an OPTIONAL extension to 273 Internet Printing Protocol/1.1: Model and Semantics [RFC2911, 274 RFC2910]. See Appendix 29 for a description of the base IPP 275 documents. This document in combination with the following documents 276 is intended to meet the most important notification requirements 277 described in [ipp-not-req]: 279 Internet Printing Protocol (IPP): "Job Progress Attributes" 280 [RFC3381] 281 Internet Printing Protocol (IPP): "The 'ippget' Delivery Method 282 for Event Notifications" [ipp-get-method] 284 This specification REQUIRES that clients and Printers support the 285 'ippget' Pull Delivery Method [ipp-get-method]. Conforming client 286 and Printer implementations MAY support additional Push or Pull 287 Delivery Methods as well. Note: this document does not define any 288 Delivery Methods itself, but it does define the rules for conformance 289 for Delivery Method Documents and their registration with IANA (see 290 section 23.7.3). 292 Refer to the Table of Contents for the layout of this document. 294 1.1 Notification Overview 296 This document defines operations that a client can perform in order 297 to create Subscription Objects in a Printer and carry out other 298 operations on them. A Subscription Object represents a Subscription 299 abstraction. The Subscription Object specifies that when one of the 300 specified Events occurs, the Printer delivers an asynchronous Event 301 Notification to the specified Notification Recipient via the 302 specified Delivery Method (i.e., protocol). 304 When a client (called a Subscribing Client) performs an operation 305 that creates a Subscription Object, the operation contains one or 306 more Subscription Template Attributes Groups. Each such group holds 307 information used by the Printer to initialize a newly created 308 Subscription Object. The Printer creates one Subscription Object for 309 each Subscription Template Attributes Group in the operation. This 310 group is like the Job Template Attributes group defined in [RFC2911]. 311 The following is an example of the information included in a 312 Subscription Template Attributes Group (see section 5 for details on 313 the Subscription Object attributes): 315 1. The names of Subscribed Events that are of interest to the 316 Notification Recipient. 318 2. The address (URL) of one Notification Recipient for a Push 319 Delivery Method or the method for a Pull Delivery Method. 320 3. The Delivery Method (i.e., the protocol) which the Printer uses 321 to deliver the Event Notification. 322 4. Some opaque data that the Printer delivers to the Notification 323 Recipient in the Event Notification. For example, the 324 Notification Recipient might use this opaque data as a 325 forwarding address for the Event Notification. 326 5. The charset to use in text fields within an Event Notification 327 6. The natural language to use in the text fields of the Event 328 Notification 329 7. The requested lease time in seconds for the Subscription Object 330 An operation that creates a Subscription Object is called a 331 Subscription Creation Operation. These operations include the 332 following operations (see section 11.1 for further details): 334 - Job Creation operation: When a client performs such an 335 operation (Print-Job, Print-URI, and Create-Job), a client can 336 include zero or more Subscription Template Attributes Groups in 337 the request. The Printer creates one Subscription Object for 338 each Subscription Template Attributes Group in the request, and 339 the Printer associates each such Subscription Object with the 340 newly created Job. This document extends these operations' 341 definitions in [RFC2911] by adding Subscription Template 342 Attributes Groups in the request and Subscription Attributes 343 Groups in the response. 345 - Create-Job-Subscriptions operation: A client can include one or 346 more Subscription Template Attributes Groups in the request. 347 The Printer creates one Subscription Object for each 348 Subscription Template Attributes Group and associates each with 349 the job that is the target of this operation. 351 - Create-Printer-Subscriptions operation: A client can include 352 one or more Subscription Template Attributes Groups in the 353 request. The Printer creates one Subscription Object for each 354 Subscription Template Attributes Group and associates each with 355 the Printer that is the target of this operation. 357 For each of the above operations: 359 - the Printer associates a Subscription Object with the Printer 360 or a specific Job. When a Subscription Object is associated 361 with a Job Object, it is called a Per-Job Subscription Object. 362 When a Subscription Object is associated with a Printer Object, 363 it is called a Per-Printer Subscription Object. 365 - the response contains one Subscription Attributes Group for 366 each Subscription Template Attributes Group in the request and 367 in the same order. When the Printer successfully creates a 368 Subscription Object, its corresponding Subscription Attributes 369 Group contains the "notify-subscription-id" attribute. This 370 attribute uniquely identifies the Subscription Object and is 371 analogous to a "job-id" for a Job object. Some operations 372 described below use the "notify-subscription-id" to identify 373 the target Subscription Object. 375 This document defines the following additional operations (see 376 section 11.2 for further details): 378 - Restart-Job operation: When a client performs the Restart-Job 379 operation [RFC2911], the Printer re-uses the same Job and its 380 Subscription Objects. 382 - Validate-Job operation: When a client performs this operation, 383 a client can include zero or more Subscription Template 384 Attributes Groups in the request. The Printer determines if it 385 could create one Subscription Object for each Subscription 386 Template Attributes Group in the request. This document 387 extends this operation's definition in [RFC2911] by adding 388 Subscription Template Attributes Groups in the request and 389 Subscription Attributes Groups in the response. 391 - Get-Subscription-Attributes operation: This operation allows a 392 client to obtain the specified attributes of a target 393 Subscription Object. 395 - Get-Subscriptions operation: This operation allows a client to 396 obtain the specified attributes of all Subscription Objects 397 associated with the Printer or a specified Job. 399 - Renew-Subscription operation: This operation renews the lease 400 on the target Per-Printer Subscription Object before it 401 expires. A newly created Per-Printer Subscription Object 402 receives an initial lease. It is the duty of the client to use 403 this operation frequently enough to preserve a Per-Printer 404 Subscription Object. The Printer deletes a Per-Printer 405 Subscription Object when its lease expires. A Per-Job 406 Subscription Object last exactly as long as its associated Job 407 Object and thus doesn't have a lease. 409 - Cancel-Subscription operation: This operation (1) cancels the 410 lease on the specified Per-Printer Subscription Object and 411 thereby deletes the Per-Printer Subscription Object or (2) 412 deletes the Per-Job Subscription Object. 414 When an Event occurs, the Printer finds all Subscription Objects 415 listening for the Event (see section 9 for details on finding such 416 Subscription Objects). For each such Subscription Object, the 417 Printer: 419 a) generates an Event Notification with information specified in 420 section 9, AND 421 b) either: 422 i) If the Delivery Method is a Push Delivery Method as 423 indicated by the presence of the Subscription Object's 424 "notify-recipient-uri" attribute, delivers the Event 425 Notification using the Delivery Method and target address 426 identified in the Subscription Object's "notify-recipient- 427 uri" attribute, OR 428 ii) If the Delivery Method is a Pull Delivery Method as 429 indicated by the presence of the Subscription Object's 430 "notify-pull-method" attribute, saves Event Notification 431 for a time period called the Event Life defined by the 432 Delivery Method, i.e., the Notification Recipient is 433 expected to fetch the Event Notifications. 435 2 Models for Notification 437 2.1 Model for Simple Notification (Normative) 439 As part of a Subscription Creation Operation, an IPP Printer (i.e., 440 located in an output device or a server) creates one or more 441 Subscription Objects. In a Subscription Creation Operation, the 442 client specifies the Notification Recipient to which the Printer is 443 to deliver Event Notifications. A Notification Recipient can be the 444 Subscribing Client or a third party. 446 Figure 1 shows the Notification model for a simple Client-Printer 447 relationship. 449 embedded printer: 450 output device or server 451 PDA, desktop, or server +---------------+ 452 +--------+ | ########### | 453 | client |-----Subscription ---------># Printer # | 454 +--------+ Creation Operation | # Object # | 455 +------------+ | #####|##### | 456 |Notification| +-------|-------+ 457 |Recipient |<----IPP Event Notifications----+ 458 +------------+ (Job and/or Printer Events) 459 Figure 1 - Model for Notification 461 2.2 Additional Models for Notification (Informative) 463 Additional models have been proposed (see Appendices 16, 17, and 18). 465 3 Terminology 467 This section defines terminology used throughout this document. 468 Other terminology is defined in [RFC2911]. 470 3.1 Conformance Terminology 472 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 473 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 474 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 475 12.1. If an implementation supports the extension defined in this 476 document, then these terms apply; otherwise, they do not. These 477 terms define conformance to this document only; they do not affect 478 conformance to other documents, unless explicitly stated otherwise.. 480 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 481 the Printer implements a Delivery Method that REQUIRES the feature. 483 READ-ONLY - an adjective used in an attribute definition to indicate 484 that an IPP Printer MUST NOT allow the attribute's value to be 485 modified. 487 3.2 Other Terminology 489 This document uses the same terminology as [RFC2911], such as 490 "client", "Printer", "attribute", "attribute value", "keyword", 491 "operation", "request", "response", "administrator", "operator", and 492 "support". In addition, the following terms are defined for use in 493 this document and the Delivery Method Documents: 495 Compound Event Notification - two or more Event Notifications that a 496 Printer delivers together as a single request or response. The 497 Delivery Method Document specifies whether the Delivery Method 498 supports Compound Event Notifications. 500 Delivery Method - the mechanism by which the Printer delivers an 501 Event Notification. 503 Delivery Method Document - a document, separate from this document, 504 that defines a Delivery Method. 506 Event - some occurrence (either expected or unexpected) within the 507 printing system of a change of state, condition, or configuration of 508 a Job or Printer object. An Event occurs only at one instant in time 509 and does not span the time the physical Event takes place. For 510 example, jam-occurred and jam-cleared are two distinct, instantaneous 511 Events, even though the jam may last for a while. 513 Event Life - For a Pull Delivery Method, the length of time in 514 seconds after an Event occurs during which the Printer will retain 515 that Event for delivery in an Event Notification. After the Event 516 Life expires, the Printer will no longer deliver an Event 517 Notification for that Event in such a response. 519 Event Notification - the information about an Event that the Printer 520 delivers when an Event occurs. 522 Event Notification Attributes Group - The attributes group which is 523 used to deliver an Event Notification in a request (Push 524 Delivery Methods) or a response (Pull Delivery Methods). 526 Human Consumable Event Notification - localized text for human 527 consumption only. There is no standardized format and thus programs 528 should not try to parse this text. 530 Job Creation operation - One of the operations that creates a Job 531 object: Print-Job, Print-URI and Create-Job. The Restart-Job 532 operation [RFC2911] is not considered a Job Creation operation, since 533 the Printer re-uses the existing Job object. The Validate-Job 534 operation is not considered a Job Creation operation because no Job 535 object is created. Therefore, when a statement also applies to 536 either the Restart-Job and/or the Validate-Job operation, they are 537 mentioned explicitly. 539 Job Event - an Event caused by some change in a particular job on the 540 Printer, e.g., 'job-completed'. 542 Machine Consumable Event Notification - bytes for program 543 consumption. The bytes are formatted according to the Delivery 544 Method document. 546 Notification - when not in the phrases 'Event Notification' and 547 'Notification Recipient' - the concepts of this specification, i.e., 548 Events, Subscription Objects, and Event Notifications. 550 Notification Recipient - the entity to which the Printer delivers an 551 Event Notification. For Push Delivery Methods, the IPP Printer sends 552 the Notifications to a Notification Recipient. For Pull Delivery 553 Methods, the Notification Recipient is acting in the role of an IPP 554 client and requests Event Notifications and so the terms "client" and 555 "Notification Recipient" are used interchangeably with such Delivery 556 Methods. For example, see [ipp-get-method]. 558 Per-Job Subscription Object - A Subscription Object that is 559 associated with a single Job. The Create-Job-Subscriptions operation 560 and Job Creation operations create such an object. 562 Per-Printer Subscription Object - A Subscription Object that is 563 associated with the Printer as a whole. The Create-Printer- 564 Subscriptions operation creates such an object. 566 Printer Event - an Event caused by some change in the Printer that is 567 not specific to a job, e.g., 'printer-state-changed'. 569 Pull Delivery Method - The Printer saves Event Notifications for some 570 event life time and expects the Notification Recipient to request 571 Event Notifications. The Printer delivers the Event Notifications in 572 a response to such a request. 574 Push Delivery Method -The Printer delivers the Event Notification 575 shortly after an Event occurs. 577 Subscribed Event - an Event that the Subscribing Client expresses 578 interest in by making it a value of the "notify-events" attribute on 579 a Subscription Object. 581 Subscribed Job Event - a Subscribed Event that is a Job Event. 583 Subscribed Printer Event - a Subscribed Event that is a Printer 584 Event. 586 Subscribing Client - The client that creates the Subscription Object. 588 Subscription Attributes Group - The attributes group in a response 589 that contains Subscription Object attributes. 591 Subscription Creation Operation - An operation that creates a 592 Subscription Object: Job Creation operations, Create-Job- 593 Subscriptions operation, Create-Printer-Subscriptions operation. In 594 the context of a Job Creation operation, a Subscription Creation 595 Operation is the part of the Job Creation operation that creates one 596 or more Subscription objects. The Restart-Job operation [RFC2911] is 597 not considered a Subscription Creation Operation, since the Printer 598 re-uses the Job's existing Subscription Objects, rather than creating 599 any new Subscription Objects. 601 Subscription Creation Request - The request portion of a Subscription 602 Creation Operation. 604 Subscription Description Attributes - Subscription Object attributes 605 that a Printer supplies during a Subscription Creation Operation. 607 Subscription Object - An object containing a set of attributes that 608 indicate: the Notification Recipient (for Push Delivery Method 609 only), the Delivery Method, the Subscribed Events that cause the 610 Printer to deliver an Event Notification, and the information to 611 include in an Event Notification. 613 Subscription Template Attributes - Subscription Object attributes 614 that a client can supply in a Subscription Creation Operation and 615 associated Printer Object attributes that specify supported and 616 default values for the Subscription Object attributes. 618 Subscription Template Attributes Group - The attributes group in a 619 request that contains Subscription Object attributes that are 620 Subscription Template Attributes. 622 4 Object Relationships 624 This section defines the object relationships between the Printer, 625 Job, and Subscription Objects. It does not define the 626 implementation. For an illustration of these relationships, see 627 Appendix 19. 629 4.1 Printer and Per-Printer Subscription Objects 631 1. A Printer object can be associated with zero or more Per-Printer 632 Subscription Objects. 634 2. Each Per-Printer Subscription Object is associated with exactly 635 one Printer object. 637 4.2 Printer, Job and Per-Job Subscription Objects 639 1. A Printer object is associated with zero or more Job objects. 641 2. Each Job object is associated with exactly one Printer object. 643 3. A Job object is associated with zero or more Per-Job Subscription 644 Objects. 646 4. Each Per-Job Subscription Object is associated with exactly one 647 Job object. 649 5 Subscription Object 651 A Subscribing Client creates a Subscription Object with a 652 Subscription Creation Operation in order to indicate its interest in 653 certain Events. See section 11 for a description of these 654 operations. When an Event occurs, the Subscription Object specifies 655 to the Printer where to deliver Event Notifications for Push Delivery 656 Methods only, how to deliver them, and what to include in them. See 657 section 9 for details on the contents of an Event Notification. 659 Using the IPP Job Template attributes as a model (see [RFC2911] 660 section 4.2), the attributes of a Subscription Object are divided 661 into two categories: Subscription Template Attributes and 662 Subscription Description Attributes. 664 Subscription Template attributes are, in turn, like the Job Template 665 attributes, divided into 667 1. Subscription Object attributes that a client can supply in a 668 Subscription Creation Request and 670 2. their associated Printer Object attributes that specify 671 supported and default values for the Subscription Object 672 attributes 674 The remainder of this section specifies general rules for 675 Subscription Template Attributes and describes each attribute in a 676 Subscription Object. 678 5.1 Rules for Support of Subscription Template Attributes 680 Subscription Template Attributes are fundamental to the Notification 681 model described in this specification. The client supplies these 682 attributes in Subscription Creation Operations and the Printer uses 683 these attributes to populate a newly created Subscription Object. 685 Subscription Objects attributes that are Subscription Template 686 Attributes conform to the following rules: 688 1. Each attribute's name starts with the prefix string "notify-" 689 and this document calls such attributes "notify-xxx". 691 2. For each "notify-xxx" Subscription Object attribute defined in 692 column 1 of Table 1 in section 5.3, Table 1 specifies 693 corresponding Printer attributes: "notify-xxx-default", "notify- 694 xxx-supported", "yyy-supported" and "notify-max-xxx-supported" 695 defined in column 2 of Table 1. Note "xxx" stands for the same 696 string in each case and "yyy" stands for some other string. 698 3. If a Printer supports "notify-xxx" in column 1 of Table 1, then 699 the Printer MUST support all associated attributes specified in 700 column 2 of Table 1. For example, Table 1 shows that if the 701 Printer supports "notify-events", it MUST support "notify- 702 events-default", "notify-events-supported" and "notify-max- 703 events-supported". 705 4. If a Printer does not support "notify-xxx" in column 1 of Table 706 1, then the Printer MUST NOT support any associated "notify-yyy" 707 attributes specified in column 2 of Table 1. For example, Table 708 1 shows that if the Printer doesn't support "notify-events", it 709 MUST NOT support "notify-events-default", "notify-events- 710 supported" and "notify-max-events-supported". Note this rule 711 does not apply to attributes whose names do not start with the 712 string "notify-" and are thus defined in another object and used 713 by other attributes. 715 5. Most "notify-xxx" attributes have a corresponding "yyy- 716 supported" attribute that specifies the supported values for 717 "notify-xxx". Column 2 of Table 1 specifies the name of each 718 "yyy-supported" attribute. The naming rules of IPP/1.1 (see 719 [RFC2911]) are used when "yyy-supported" is "notify-xxx- 720 supported". 722 6. Some "notify-xxx" attributes have a corresponding "notify-xxx- 723 default" attribute that specifies the value for "notify-xxx" if 724 the client does not supply it. Column 2 of Table 1 specifies 725 the name of each "notify-xxx-default" attribute. The naming 726 rules of IPP/1.1 (see [RFC2911]) are used. 728 If a client wishes to present an end user with a list of supported 729 values from which to choose, the client SHOULD query the Printer for 730 its supported value attributes. The client SHOULD also query the 731 default value attributes. If the client then limits selectable 732 values to only those values that are supported, the client can 733 guarantee that the values supplied by the client in the create 734 request all fall within the set of supported values at the Printer. 735 When querying the Printer, the client MAY enumerate each attribute by 736 name in the Get-Printer-Attributes Request, or the client MAY just 737 supply the 'subscription-template' group name in order to get the 738 complete set of supported attributes (both supported and default 739 attributes - see section 11.2.3). 741 5.2 Rules for Processing Subscription Template Attributes 743 This section defines a detailed set of rules that a Printer follows 744 when it processes Subscription Template Attributes in a Subscription 745 Creation Request. These rules are similar to the rules for 746 processing Operation attributes in [RFC2911]. That is, the Printer 747 may or may not support an attribute and a client may or may not 748 supply the attribute. Some combinations of these cases are OK. 749 Others return warnings or errors, and perhaps a list of unsupported 750 attributes. 752 A Printer MUST implement the following behavior for processing 753 Subscription Template Attributes in a Subscription Creation Request: 755 1. If a client supplies a "notify-xxx" attribute from column 1 of 756 Table 1 and the Printer supports it and its value, the Printer 757 MUST populate the attribute on the created Subscription Object. 759 2. If a client supplies a "notify-xxx" attribute from column 1 of 760 Table 1 and the Printer doesn't support it or its value, the 761 Printer MUST NOT populate the attribute on the created 762 Subscription Object with it. The Printer MUST do one of the 763 following: 765 a) If the value of the "notify-xxx" attribute is unsupported, the 766 Printer MUST return the attribute with its value in the 767 Subscription Attributes Group of the response. 769 b) If "notify-xxx" is an unsupported attribute, the Printer MUST 770 return the attribute in the Subscription Attributes Group of the 771 response with the 'unsupported' out-of-band value. 773 Note: The rules of this step are the same as for Unsupported 774 Attributes [RFC2911] section 3.1.7. except that the unsupported 775 attributes are returned in the Subscription Attributes Group 776 rather than the Unsupported Attributes Group because Subscription 777 Creation Operations can create more than one Subscription Object). 778 3. If a client is REQUIRED to supply a "notify-xxx" attribute from 779 column 1 of Table 1 and the Printer doesn't support the supplied 780 value, the Printer MUST NOT create a Subscription Object. The 781 rules for Unsupported Attributes in step #2 still apply. 783 4. If a client does not supply a "notify-xxx" attribute from column 1 784 of Table 1 and the attribute is REQUIRED for the client to supply, 785 the Printer MUST reject the Subscription Creation Operation 786 (including Job Creation operations) without creating a 787 Subscription Object, and MUST return in the response: 789 a)the status code 'client-error-bad-request' AND 791 b) no Subscription Attribute Groups. 793 5. If a client does not supply a "notify-xxx" attribute from column 1 794 of Table 1 that is OPTIONAL for the client to supply, and column 2 795 of Table 1 either: 797 a) specifies a "notify-xxx-default" attribute, the Printer MUST 798 behave as if the client had supplied the "notify-xxx-default" 799 attribute (see step #1) and populate the Subscription object 800 with the value of the "notify-xxx-default" attribute as part of 801 the Subscription Creation operation (unlike Job Template 802 attributes where the Printer does not populate the Job object 803 with defaults - see [RFC2911]) OR 805 b) does not specify a "notify-xxx-default" attribute, the Printer 806 MUST populate the "notify-xxx" attribute on the Subscription 807 Object according to the definition of the "notify-xxx" attribute 808 in a section 5.3. For some attributes, the "notify-xxx" is 809 populated with the value of some other attribute, and for 810 others, the "notify-xxx" is NOT populated on the Subscription 811 object at all. 813 6. A Printer MUST create a Subscription Object for each Subscription 814 Template Attributes group in a request unless the Printer: 816 a) encounters some attributes in a Subscription Template Attributes 817 Group that require the Printer not to create the Subscription 818 Object OR 820 b) would create a Per-Job Subscription Object when it doesn't have 821 space for another Per-Job Subscription Object OR 823 c) would create a Per-Printer Subscription Object when it doesn't 824 have space for another Per-Printer Subscription Object. 826 7. A response MUST contain one Subscription Attributes Group for each 827 Subscription Template Attributes Group in the request (and in the 828 same order) whether the Printer creates a Subscription Object from 829 the Subscription Template Attributes Group or not. However, the 830 attributes in each Subscription Attributes Group can be in any 831 order. 833 8. The Printer MUST populate each Subscription Attributes Group of 834 the response such that each contains: 836 a) the "notify-subscription-id" attribute (see section 5.4.1), if 837 and only if the Printer creates a Subscription Object. 839 b) the "notify-lease-duration" attribute (see section 5.3.8), if 840 and only if the Printer creates a Per-Printer Subscription 841 Object. The value of this attribute is the value of the 842 Subscription Object's "notify-lease-duration" attribute. This 843 value MAY be different from the client-supplied value (see 844 section 5.3.8). If a client supplies this attribute in the 845 creation of a Per-Job Subscription Object, it MUST appear in 846 this group with the out-of-band value 'unsupported' to indicate 847 that the Printer doesn't support it in this context. 849 c) all of the unsupported Subscription Template Attributes from 850 step #2. Note, they are not returned in the Unsupported 851 Attributes Group in order to separate the unsupported attributes 852 for each Subscription Object. 854 d) the "notify-status-code" attribute if the Printer does not 855 create the Subscription Object or if there are unsupported 856 attributes from step #2. The possible values of the "notify- 857 status-code" attribute are shown below (see section 13 for more 858 details). The Printer returns the first value in the list below 859 that describes the status. 861 'client-error-uri-scheme-not-supported': the Subscription 862 Object was not created because the scheme of the "notify- 863 recipient-uri" attribute is not supported. See section 864 13.1 for more details about this status code. See step #3 865 in this section for the case that causes this error, and 866 the resulting step #6a) that causes the Printer not to 867 create the Subscription Object. 868 'client-error-attributes-or-values-not-supported': the 869 Subscription Object was not created because the method of 870 the "notify-pull-method" attribute is not supported. See 871 section 13.1 for more details about this status code. See 872 step #3 in this section for the case that causes this 873 error, and the resulting step #6a) that causes the Printer 874 not to create the Subscription Object. 875 'client-error-too-many-subscriptions': the Subscription 876 Object was not created because the Printer has no space for 877 additional Subscription Objects. The client MAY try again 878 later. See section 13.3 for more details about this status 879 code. See steps #6b) and #6c) in this section for the 880 cases that causes this error. 881 'successful-ok-too-many-events': the Subscription Object was 882 created without the "notify-events" values included in this 883 Subscription Attributes Group because the "notify-events" 884 attribute contains too many values. See section 13.4 for 885 more details about this status code. See step #2 in this 886 section and section 5.3.3 for the cases that cause this 887 status code. 889 'successful-ok-ignored-or-substituted-attributes' : the 890 Subscription Object was created but some supplied 891 Subscription Template Attributes are unsupported. These 892 unsupported attributes are also in the Subscription 893 Attributes Group. See section 13.5 for more details about 894 this status code. See step #2 in this section for the 895 cases that cause this status code. 896 9. The Printer MUST validate all Subscription Template Attributes and 897 MUST return all unsupported attributes and values in the 898 corresponding Subscription Attributes Group of the response (see 899 step #2) unless it determines that it could not create additional 900 Subscription Objects because of condition #6b) or condition #6c). 901 Then, the Printer NEED NOT validate these additional Subscription 902 Template Attributes and the client MUST NOT expect to find 903 unsupported attributes from step #2 in such additional 904 Subscription Attribute Groups. 906 5.3 Subscription Template Attributes 908 This section contains the Subscription Template Attributes defined 909 for the Subscription and Printer objects. 911 Table 1 below shows the Subscription Template Attributes and has two 912 columns: 914 - Attribute in Subscription Object: the name and attribute syntax 915 of each Subscription Object Attribute that is a Subscription 916 Template Attribute 918 - Default and Supported Printer Attributes: the default attribute 919 and supported Printer attributes that are associated with the 920 attribute in column 1. 922 The "notify-recipient-uri" attribute is for use with Push Delivery 923 Methods. The "notify-pull-method" attribute is for use with Pull 924 Delivery Methods. 926 For Push Delivery Methods, a Printer MUST support all attributes in 927 Table 1 below except for "notify-pull-method" and "notify-attributes" 928 (and "notify-pull-method-supported" and "notify-attributes- 929 supported"). For Pull Delivery Methods, a Printer MUST support all 930 attributes in Table 1 below except for "notify-recipient-uri" and 931 "notify-attributes" (and "notify-schemes-supported" and "notify- 932 attributes-supported"). If a Printer supports both Push and Pull 933 Delivery Methods, then it MUST support both "notify-recipient-uri" 934 and "notify-pull-method" attributes. 936 For Pull Delivery Methods, a client MUST supply "notify-recipient- 937 uri" and MAY omit any of the rest of the attributes in column 1 of 938 Table 1 in a Subscription Creation Request. For Push Delivery 939 Methods, a client MUST supply "notify-pull-method" and MAY omit any 940 of the rest of the attributes in column 1 of Table 1 in a 941 Subscription Creation Request. A client MUST NOT supply both 942 "notify-recipient-uri" and "notify-pull-method" attributes in the 943 same Subscription Creation Request. 945 Note: The Default and Supported Printer attributes listed in column 946 2 of Table 1 do not have separate sections in this specification 947 defining their semantics. Instead, the section for the corresponding 948 Subscription Object attribute (column 1 of Table 1) contains the 949 semantics of these Printer attributes. This approach follows the 950 precedence of the Job Template attributes in section 4.2 of [RFC2911] 951 where the corresponding "xxx-default" and "xxx-supported" Printer 952 attributes are defined in the same section as the "xxx" Job 953 attribute. 955 Table 1 - Subscription Template Attributes 956 Attribute in Subscription Default and Supported Printer 957 Object Attributes 959 notify-recipient-uri (uri) * notify-schemes-supported (1setOf 960 uriScheme) 961 notify-pull-method (type2 notify-pull-method-supported (1setOf 962 keyword) ** type2 keyword) 963 notify-events (1setOf type2 notify-events-default (1setOf type2 964 keyword) keyword) 965 notify-events-supported (1setOf type2 966 keyword) 967 notify-max-events-supported 968 (integer(2:MAX)) 969 notify-attributes (1setOf notify-attributes-supported (1setOf 970 type2 keyword) type2 keyword) 971 notify-user-data 972 (octetString(63)) 973 notify-charset (charset) charset-supported (1setOf charset) 974 notify-natural-language generated-natural-language-supported 975 (naturalLanguage) (1setOf naturalLanguage) 976 notify-lease-duration notify-lease-duration-default 977 (integer(0:MAX)) (integer(0:67108863)) 978 notify-lease-duration-supported 979 (1setOf (integer(0: 67108863) | 980 rangeOfInteger(0:67108863))) 981 notify-time-interval 982 (integer(0:MAX)) 983 * "notify-recipient-uri" is for Push Delivery Methods only. 984 ** "notify-pull-method" is for Pull Delivery Methods only. 986 5.3.1 notify-recipient-uri (uri) 988 This attribute's value is a URL, which is a special case of a URI. 989 Its value consists of a scheme and an address. The address specifies 990 the Notification Recipient and the scheme specifies the Push Delivery 991 Method for each Event Notification associated with this Subscription 992 Object. 994 If a Printer supports any Push Delivery Methods, a Printer MUST 995 support this attribute and return the value as supplied by the client 996 (no case conversion or other canonicalization) in any operation 997 response that includes this attribute. 999 For a Push Delivery Method, a client MUST supply this attribute in a 1000 Subscription Creation Operation. Thus there is no need for a default 1001 Printer attribute. 1003 The URI scheme of the value of this attribute on a Subscription 1004 object MUST be a value of the "notify-schemes-supported (1setOf 1005 uriScheme)" Printer attribute (see section 5.3.1.1). Note: According 1006 to [RFC2396] the ":" terminates the scheme and so is not part of the 1007 scheme. Therefore, values of the "notify-schemes-supported" Printer 1008 attribute do not include the ":" character. 1010 If the client supplies an unsupported scheme in the value of this 1011 attribute, then the Printer MUST NOT create the Subscription Object 1012 and MUST return the "notify-status-code" attribute with the 'client- 1013 error-uri-scheme-not-supported' value in the Subscription Attributes 1014 Group in the response. 1016 5.3.1.1 notify-schemes-supported (1setOf uriScheme) 1018 This attribute contains the URI schemes supported in the "notify- 1019 recipient-uri" Subscription Template attribute. See sections 5.1 and 1020 5.2 for the behavior of "xxx-supported" Subscription Template Printer 1021 attributes. 1023 5.3.2 notify-pull-method (type2 keyword) 1025 This attribute's value is a type2 keyword indicating which Pull 1026 Delivery Method is to be used. 1028 Since a Printer MUST support the 'ippget' Pull Delivery Method [ipp- 1029 get-method] (see section 15), a Printer MUST support this attribute 1030 and return the value as supplied by the client in any operation 1031 response that includes this attribute. 1033 For a Pull Delivery Method, a client MUST supply this attribute in a 1034 Subscription Creation Operation. Thus there is no need for a default 1035 Printer attribute. 1037 The keyword value of this attribute on a Subscription object MUST be 1038 a value of the "notify-pull-method-supported (1setOf type2 keyword)" 1039 Printer attribute. 1041 If the client supplies an unsupported method in the value of this 1042 attribute, then the Printer MUST NOT create the Subscription Object 1043 and MUST return the "notify-status-code" attribute with the 'client- 1044 error-attributes-or-values-not-supported' value in the Subscription 1045 Attributes Group in the response. 1047 5.3.2.1 notify-pull-method-supported (1setOf type2 keyword) 1049 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1050 Subscription Template Printer attributes. 1052 5.3.3 notify-events (1setOf type2 keyword) 1054 This attribute contains a set of Subscribed Events. When an Event 1055 occurs and it "matches" a value of this attribute, the Printer 1056 delivers an Event Notification using information in the Subscription 1057 Object. The details of "matching" are described subsection 5.3.3.5. 1059 A Printer MUST support this attribute. 1061 A client MAY supply this attribute in a Subscription Creation 1062 Operation. If the client does not supply this attribute in 1063 Subscription Creation Operation, the Printer MUST populate this 1064 attribute on the Subscription Object with its "notify-events-default" 1065 attribute value. 1067 Each keyword value of this attribute on a Subscription Object MUST be 1068 a value of the "notify-events-supported (1setOf type2 keyword)" 1069 Printer attribute. 1071 The number of values of this attribute MUST NOT exceed the value of 1072 the "notify-max-events-supported" attribute. A Printer MUST support 1073 at least 2 values per Subscription Object. If the number of values 1074 supplied by a client in a Subscription Creation Operation exceeds the 1075 value of this attribute, the Printer MUST treat extra values as 1076 unsupported values and MUST use the value of 'successful-ok-too-many- 1077 events' for the "notify-status-code" attribute in the Subscription 1078 Attributes Group of the response. 1080 5.3.3.1 notify-events-default (1setOf type2 keyword) 1082 See sections 5.1 and 5.2 for the behavior of "xxx-default" 1083 Subscription Template Printer attributes. 1085 5.3.3.2 notify-events-supported (1setOf type2 keyword) 1087 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1088 Subscription Template Printer attributes. 1090 5.3.3.3 notify-max-events-supported (integer(2:MAX)) 1092 This attribute specified the maximum number of events that the 1093 Printer supports for the "notify-events" Subscription Template 1094 attribute. See sections 5.1 and 5.2 for the behavior of "xxx- 1095 supported" Subscription Template Printer attributes. 1097 5.3.3.4 Standard Values for Subscribed Events 1099 Each value of this attribute is a keyword and it specifies a 1100 Subscribed Event that represents certain changes. Some keywords 1101 represent a subset of changes of another keyword, e.g., 'job- 1102 completed' is an Event value which is a sub-value of 'job-state- 1103 change'. See section 5.3.3.5 for the case where this attribute 1104 contains both a value and a sub-value. 1106 The values in this section are divided into three categories: No 1107 Events, Job Events and Printer Events. 1109 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1110 support the Events indicated as "OPTIONAL". 1112 5.3.3.4.1 No Events 1114 The standard and only keyword value for No Events is: 1116 'none': REQUIRED - no Event Notifications for any Events. As the 1117 sole value of "notify-events-supported", this value means that the 1118 Printer does not support the delivery of Event Notifications. As 1119 the sole value of "notify-events-default", this value means that a 1120 client MUST specify the "notify-events" attribute in order for a 1121 Subscription Creation Operation to succeed. If the Printer 1122 receives this value as the sole value of a Subscription Creation 1123 Operation, it does not create a Subscription Object. If a Printer 1124 receives this value with other values of a Subscription Creation 1125 Operation, the Printer MUST treat this value as an unsupported 1126 value. 1128 5.3.3.4.2 Subscribed Printer Events 1130 The standard keyword values for Subscribed Printer Events are: 1132 'printer-state-changed': REQUIRED - the Printer changed state from 1133 any state to any other state. Specifically, the value of the 1134 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1135 accepting-jobs" attributes changed. 1137 This Subscribed Event value has the following sub-values: 1138 'printer-restarted' and 'printer-shutdown'. A client can listen 1139 for any of these sub-values if it doesn't want to listen to all 1140 printer-state changes: 1142 'printer-restarted': OPTIONAL - when the printer is powered 1143 up . 1145 'printer-shutdown': OPTIONAL - when the device is being 1146 powered down . 1148 'printer-stopped: REQUIRED - when the printer stops printing, 1149 i.e. the value of the "printer-state" Printer attribute 1150 becomes 'stopped'. 1152 'printer-config-changed': OPTIONAL - when the configuration of a 1153 Printer has changed, i.e., the value of the "printer-message-from- 1154 operator" or any "configuration" Printer attribute has changed. A 1155 "configuration" Printer attribute is an attribute which can change 1156 value because of some human interaction either direct or indirect, 1157 and which is not covered by one of the other Events in this 1158 section. Examples of "configuration" Printer attributes are any 1159 of the Job Template attributes, such as "xxx-supported", "xxx- 1160 ready" and "xxx-default". The client has to perform a Get- 1161 Printer-Attributes to find out the new values of these changed 1162 attributes. This Event is useful for GUI clients and drivers to 1163 update the available printer capabilities to the user. 1165 This Event value has the following sub-values: 'printer-media- 1166 changed' and 'printer-finishings-changed'. A client can listen 1167 for any of these sub-values if it doesn't want to listen to all 1168 printer-configuration changes: 1170 'printer-media-changed': OPTIONAL - when the media loaded on 1171 a printer has been changed, i.e., the "media-ready" 1172 attribute has changed. This Event includes two cases: an 1173 input tray that goes empty and an input tray that receives 1174 additional media of the same type or of a different type. 1175 The client must check the "media-ready" Printer attribute 1176 (see [RFC2911] section 4.2.11) separately to find out what 1177 changed. 1179 'printer-finishings-changed': OPTIONAL - when the finisher on 1180 a printer has been changed, i.e., the "finishings-ready" 1181 attribute has changed. This Event includes two cases: a 1182 finisher that goes empty and a finisher that is refilled 1183 (even if it is not full). The client must check the 1184 "finishings-ready" Printer attribute separately to find out 1185 what changed. 1187 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1188 Printer's queue has changed, so that an application that is 1189 monitoring the queue can perform a Get-Jobs operation to determine 1190 the new order. This Event does not include when a job enters the 1191 queue (the 'job-created' Event covers that) and does not include 1192 when a job leaves the queue (the 'job-completed' Event covers 1193 that). 1195 5.3.3.4.3 Subscribed Job Events 1197 The standard keyword values for Subscribed Job Events are: 1199 'job-state-changed': REQUIRED - the job has changed from any state 1200 to any other state. Specifically, the Printer delivers this Event 1201 whenever the value of the "job-state" attribute or "job-state- 1202 reasons" attribute changes. When a Job is removed from the Job 1203 Retention or Job History phases (see [RFC2911] section 4.3.7.1), 1204 no Event is generated. 1206 This Event value has the following sub-values: 'job-created', 1207 'job-completed' and 'job-stopped'. A client can listen for any of 1208 these sub-values if it doesn't want to listen to all 'job-state 1209 changes'. 1211 'job-created': REQUIRED - the Printer has accepted a Job 1212 Creation operation, a Restart-Job operation [RFC2911], or 1213 any job operation that creates a Job object from an 1214 existing Job object. The Printer populates the job's 1215 "time-at-creation" attribute value (see [RFC2911] section 1216 4.3.14.1). The Printer puts the job in the 'pending', 1217 'pending-held' or 'processing' states. 1219 'job-completed': REQUIRED - the job has reached one of the 1220 completed states, i.e., the value of the job's "job-state" 1221 attribute has changed to: 'completed', 'aborted', or 1222 'canceled'. The Job's "time-at-completed" and "date-time- 1223 at-completed" (if supported) attributes are set (see 1224 [RFC2911] section 4.3.14). When a Job completes, a 1225 Notification Recipient MAY query the Job using the Get-Job- 1226 Attributes operation. To allow such a query, the Printer 1227 retains the Job in the Job Retention and/or the Job History 1228 phases (see [RFC2911] section 4.3.7.1) for a suitable 1229 amount of time that depends on implementation and the 1230 Delivery Methods supported. The Printer also delivers this 1231 Event when a Job is removed with the Purge-Job operation 1232 (see [RFC2911] section 3.2.9). In this case, the Event 1233 Notification MUST report the 'job-state' as 'canceled' and 1234 the Job object is no longer present for query. 1236 'job-stopped: OPTIONAL - when the job stops printing, i.e. 1237 the value of the "job-state" Job attribute becomes 1238 'processing-stopped'. 1240 'job-config-changed': OPTIONAL - when the configuration of a job has 1241 changed, i.e., the value of the "job-message-from-operator" or any 1242 of the "configuration" Job attributes have changed. A 1243 "configuration" Job attribute is an attribute that can change 1244 value because of some human interaction either direct or indirect. 1245 Examples of "configuration" Job attributes are any of the job 1246 template attributes and the "job-name" attribute. The client 1247 performs a Get-Job-Attributes to find out the new values of the 1248 changed attributes. This Event is useful for GUI clients and 1249 drivers to update the job information to the user. 1251 'job-progress': OPTIONAL - when the Printer has completed Printing a 1252 sheet. See the separate [RFC3381] specification for additional 1253 attributes that a Printer MAY deliver in an Event Notification 1254 caused by this Event. The "notify-time-interval" attribute 1255 affects this Event by causing the Printer NOT to deliver an Event 1256 Notification every time a 'job-progress' Events occurs. See 1257 section 5.3.9 for full details. 1259 5.3.3.5 Rules for Matching of Subscribed Events 1261 When an Event occurs, the Printer MUST find each Subscription object 1262 whose "notify-events" attribute "matches" the Event. The rules for 1263 "matching" of Subscribed Events are described separately for Printer 1264 Events and for Job Events. This section also describes some special 1265 cases. 1267 5.3.3.5.1 Rules for Matching of Printer Events 1269 Given that the Printer causes Printer Event E to occur, for each Per- 1270 Job or Per-Printer Subscription S in the Printer, if E equals a value 1271 of this attribute in S or E is a sub-value of a value of this 1272 attribute in S, the Printer MUST generate an Event Notification. 1274 Consider the example. There are three Subscription Objects each with 1275 the Subscribed Printer Event 'printer-state-changed'. Subscription 1276 Object A is a Per-Printer Subscription Object. Subscription Object B 1277 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1278 is a Per-Job Subscription Object for Job 2. When the Printer enters 1279 the 'stopped' state, the Printer delivers an Event Notification to 1280 the Notification Recipients of Subscription Objects A, B, and C 1281 because this is a Printer Event. Note if Job 1 has already 1282 completed, the Printer would not deliver an Event Notification for 1283 its Subscription Object, even if Job 1 is retained in the Job 1284 Retention and/or the Job History phases (see [RFC2911] section 1285 4.3.7.1). 1287 5.3.3.5.2 Rules for Matching of Job Events 1289 Given that Job J causes Job Event E to occur: 1291 1. For each Per-Printer Subscription S in the Printer, if E equals 1292 a value of this attribute in S or E is a sub-value of a value of 1293 this attribute in S, the Printer MUST generate an Event 1294 Notification. 1296 2. For each Per-Job Subscription S associated with Job J, if E 1297 equals a value of this attribute in S or E is a sub-value of a 1298 value of this attribute in S, the Printer MUST generate an Event 1299 Notification. 1301 3. For each Per-Job Subscription S that is NOT associated Job J, if 1302 E equals a value of this attribute in S or E is a sub-value of a 1303 value of this attribute in, the Printer MUST NOT generate an 1304 Event Notification from S. 1306 Consider the example: There are three Subscription Objects listening 1307 for the Job Event 'job-completed'. Subscription Object A is a Per- 1308 Printer Subscription Object. Subscription Object B is a Per-Job 1309 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1310 Subscription Object for Job 2. In addition, Per-Printer Subscription 1311 Object D is listening for the Job Event 'job-state-changed'. When 1312 Job 1 completes, the Printer delivers an Event Notification to the 1313 Notification Recipient of Subscription Object A (because it is Per- 1314 Printer) and Subscription Object B because it is a Per-Job 1315 Subscription Object associated with the Job generating the Event. 1316 The Printer also delivers an Event Notification to the Notification 1317 Recipient of Subscription Object D because 'job-completed' is a sub- 1318 value of 'job-state-changed' - the value that Subscription Object D 1319 is listening for. The Printer does not deliver an Event Notification 1320 to the Notification Recipients of Subscription Object C because it is 1321 a Per-Job Subscription Object associated with some Job other than the 1322 Job generating the Event. 1324 5.3.3.5.3 Special Cases for Matching Rules 1326 This section contains two rules for the special case where a single 1327 Event produces multiple Event Notifications destined for the same 1328 Notification Recipient. These two rules clarify whether a Printer 1329 should send multiple Event Notifications or consolidate them into a 1330 single Event Notification. 1332 If an Event matches Subscribed Events in two different Subscription 1333 Objects and the Printer would deliver two identical Event 1334 Notifications (except for the "notify-subscription-id" attribute) to 1335 the same Notification Recipient using the same Delivery Method, the 1336 Printer MUST deliver both Event Notifications. That is, the Printer 1337 MUST NOT try to consolidate seemingly identical Event Notifications 1338 that occur in separate Subscription objects. Incidentally, the 1339 Printer MUST NOT reject Subscription Creation Operations that would 1340 create this scenario. 1342 Consider the example: At the time a Job completes, there are two Per- 1343 Printer Subscription Objects A and B with the same Notification 1344 Recipient R. Subscription Object A has the Subscribed Job Event 1345 'job-state-changed'. Subscription Object B has the Subscribed Job 1346 Event 'job-completed'. Both Subscription Objects match the Event 1347 'job-completed'. The Printer delivers two Event Notifications to the 1348 Notification Recipient R. One with the value of 'job-state-changed' 1349 for the "notify-subscribed-event" attribute and the other with the 1350 value of 'job-completed' for the "notify-subscribed-event" 1351 attribute. 1353 If an Event matches two Subscribed Events in a single Subscription 1354 object (e.g., a value and its sub-value), a Printer MAY deliver one 1355 Event Notification for each matched value in the Subscription Object 1356 or it MAY deliver only a single Event Notification. The rules in 1357 sections 5.3.3.5.1 and 5.3.3.5.2 are purposefully flexible about the 1358 number of Event Notifications sent when Event E matches two or more 1359 values in a Subscription Object. 1361 Consider the example: At the time a Job completes, a Subscription 1362 Object A has two Subscribed Job Events 'job-state-changed' and 'job- 1363 completed'. Both Subscribed Job Events match the Event 'job- 1364 completed'. The Printer delivers either one or two Event 1365 Notifications to the Notification Recipient of Subscription Object A, 1366 depending on implementation. If it delivers two Event Notifications, 1367 one has the value of 'job-state-changed' for the "notify-subscribed- 1368 event" attribute, and the other has the value of 'job-completed' for 1369 the "notify-subscribed-event" attribute. If it delivers one Event 1370 Notification, it has the value of either 'job-state-changed' or 'job- 1371 completed' for the "notify-subscribed-event" attribute, depending on 1372 implementation. The algorithm for choosing such a value is 1373 implementation dependent. 1375 5.3.4 notify-attributes (1setOf type2 keyword) 1377 This attribute contains a set of attribute names. When a Printer 1378 delivers a Machine Consumable Event Notification, it includes a fixed 1379 set of attributes (see section 9.1). If this attribute is present 1380 and the Event Notification is Machine Consumable, the Printer also 1381 includes the attributes specified by this attribute. 1383 A Printer MAY support this attribute. 1385 A client MAY supply this attribute in a Subscription Creation 1386 Operation. If the client does not supply this attribute in 1387 Subscription Creation Operation or the Printer does not support this 1388 attribute, the Subscription Object either (1) MAY contain the 1389 "notify-attributes" attribute with a 'none' value or (2) NEED NOT 1390 contain the attribute at all. There is no "notify-attributes- 1391 default" Printer attribute. 1393 Each keyword value of this attribute on a Subscription Object MUST be 1394 a value of the "notify-attributes-supported (1setOf type2 keyword)" 1395 Printer attribute (see section 5.3.4.1). The "notify-attributes- 1396 supported" MAY contain any Printer attribute, Job attribute or 1397 Subscription Object attribute that the Printer supports in an Event 1398 Notification. It MUST NOT contain any of the attributes in Section 1399 9.1 that a Printer automatically puts in an Event Notification; it 1400 would be redundant. If a client supplies an attribute in Section 1401 9.1, the Printer MUST treat it as an unsupported attribute value of 1402 the "notify-attributes" attribute. 1404 The following rules apply to each keyword value N of the "notify- 1405 attributes" attribute: If the value N names: 1407 a) a Subscription attribute, the Printer MUST use the attribute N in 1408 the Subscription Object that is being used to generate the Event 1409 Notification. 1411 b) a Job attribute and the Printer is generating an Event 1412 Notification from a Per-Job Subscription Object S, the Printer 1413 MUST use the attribute N in the Job object associated with S. 1415 c) a Job attribute and the Printer is generating an Event 1416 Notification from a Per-Printer Subscription Object and the Event 1417 is: 1419 . a Job Event, the Printer MUST use the attribute N in the Job 1420 object that caused the Event. 1422 . a Printer Event, the Printer MUST use the attribute N in the 1423 active Job. 1425 If a Printer supports this attribute and a Subscription Object 1426 contains this attribute and the Delivery Method generates a Machine 1427 Consumable Event Notification, the Printer MUST include in each Event 1428 Notification: 1430 a) the attributes specified in section 9.1 and 1432 b) each attribute named by this attribute. 1434 The Printer MUST NOT use this attribute to generate a Human 1435 Consumable Event Notification. 1437 5.3.4.1 notify-attributes-supported (1setOf type2 keyword) 1439 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1440 Subscription Template Printer attributes. 1442 5.3.5 notify-user-data (octetString(63)) 1444 This attribute contains opaque data that some Delivery Methods 1445 include in each Machine Consumable Event Notification. The opaque 1446 data might contain, for example: 1448 - the identity of the Subscriber 1450 - a path or index to some Subscriber information 1452 - a key that identifies to the Notification Recipient the 1453 ultimate recipient of the Event Notification 1455 - the id for a Notification Recipient that had previously 1456 registered with an Instant Messaging Service 1458 A Printer MUST support this attribute. 1460 A client MAY supply this attribute in a Subscription Creation 1461 Operation. If the client does not supply this attribute in the 1462 Subscription Creation Operation, the Subscription Object either (1) 1463 MAY contain the "notify-user-data" attribute with a zero length value 1464 or (2) NEED NOT contain the attribute at all. There is no "notify- 1465 user-data-default" Printer attribute. 1467 There is no "notify-user-data-supported" Printer attribute. Rather, 1468 any octetString whose length does not exceed 63 octets is a supported 1469 value. If the length exceeds 63 octets, the Printer MUST treat it as 1470 an unsupported value. 1472 5.3.6 notify-charset (charset) 1474 This attribute specifies the charset to be used in the Event 1475 Notification content sent to the Notification Recipient, whether the 1476 Event Notification content is Machine Consumable or Human Consumable. 1478 A Printer MUST support this attribute. 1480 A client MAY supply this attribute in a Subscription Creation 1481 Operation. If the client does not supply this attribute in 1482 Subscription Creation Operation or supplies an unsupported value, the 1483 Printer MUST populate this attribute in the Subscription Object with 1484 the value of the "attributes-charset" operation attribute, which is a 1485 REQUIRED attribute in all IPP requests (see [RFC2911]). If the value 1486 of the "attributes-charset" attribute is unsupported, the Printer 1487 MUST populate this attribute in the Subscription Object with the 1488 value of the Printer's "charset-configured" attribute. There is no 1489 "notify-charset-default" Printer attribute. 1491 The value of this attribute on a Subscription Object MUST be a value 1492 of the "charset-supported (1setOf charset)" Printer attribute. 1494 5.3.7 notify-natural-language (naturalLanguage) 1496 This attribute specifies the natural language to be used in any human 1497 consumable text in the Event Notification content sent to the 1498 Notification Recipient, whether the Event Notification content is 1499 Machine Consumable or Human Consumable. 1501 A Printer MUST support this attribute. 1503 A client MAY supply this attribute in a Subscription Creation 1504 Operation. If the client does not supply this attribute in 1505 Subscription Creation Operation or supplies an unsupported value, the 1506 Printer MUST populate this attribute in the Subscription Object with 1507 the value of the "attributes-natural-language" operation attribute, 1508 which is a REQUIRED attribute in all IPP requests (see [RFC2911] 1509 section 3.1.4). If the value of the "attributes-natural-language" 1510 attribute is unsupported, the Printer MUST populate this attribute in 1511 the Subscription Object with the value of the Printer's "natural- 1512 language-configured" attribute (see [RFC2911] section 4.4.19). There 1513 is no "notify-natural-language-default" Printer attribute. 1515 The value of this attribute on a Subscription Object MUST be a value 1516 of the "generated-natural-language-supported (1setOf type2 1517 naturalLanguage)" Printer attribute (see [RFC2911] section 4.4.20). 1519 5.3.8 notify-lease-duration (integer(0:67108863)) 1521 This attribute specifies the duration of the lease (in seconds) 1522 associated with the Per-Printer Subscription Object at the time the 1523 Subscription Object was created or the lease was renewed. The 1524 duration of the lease is infinite if the value is 0, i.e., the lease 1525 never expires. See section 5.4.3 on "notify-lease-expiration-time 1526 (integer(0:MAX))" for more details. 1528 This attribute is not present on a Per-Job Subscription Object 1529 because the Subscription Object lasts exactly as long as the 1530 associated Job object. See discussion of the 'job-completed' event 1531 in section 5.3.3.4.3 about retention of the Job object after 1532 completion. 1534 A Printer MUST support this attribute. 1536 For a Subscription Object Creation operation of a Per-Job 1537 Subscription Object, the client MUST NOT supply this attribute. If 1538 the client does supply this attribute, the Printer MUST treat it as 1539 an unsupported attribute. 1541 For a Subscription Creation Operation of a Per-Printer Subscription 1542 Object or a Renew-Subscription operation, a client MAY supply this 1543 attribute. If the client does not supply this attribute, the Printer 1544 MUST populate this attribute with its "notify-lease-duration-default" 1545 (0:67108863) attribute value. If the client supplies this attribute 1546 with an unsupported value, the Printer MUST populate this attribute 1547 with a supported value, and this value SHOULD be as close as possible 1548 to the value requested by the client. Note: this rule implies that a 1549 Printer doesn't assign the value of 0 (infinite) unless the client 1550 requests it. 1552 After the Printer has populated this attribute with a supported 1553 value, the value represents the "granted duration" of the lease in 1554 seconds and the Printer updates the value of the Subscription 1555 Object's "notify-lease-expiration-time" attribute as specified in 1556 section 5.4.3. 1558 The value of this attribute on a Subscription Object MUST be a value 1559 of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) 1560 | rangeOfInteger(0:67108863))) Printer attribute. 1562 A Printer MAY require authentication in order to return the value of 1563 0 (the lease never expires) as one of the values of "notify-lease- 1564 duration-supported", and to allow 0 as a value of the "notify-lease- 1565 duration" attribute. 1567 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1568 1 and is about 2 years in seconds. The value is considerably less 1569 than MAX so that there is virtually no chance of an overflow when the 1570 Printer adds it to the Printer's "printer-up-time" attribute value 1571 (see [RFC2911] section 4.4.29) to produce the "notify-lease- 1572 expiration-time" Subscription Description attribute value (see 1573 section 5.4.3). 1575 5.3.8.1 notify-lease-duration-default (integer(0:67108863)) 1577 See sections 5.1 and 5.2 for the behavior of "xxx-default" 1578 Subscription Template Printer attributes. 1580 5.3.8.2 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 1581 rangeOfInteger(0:67108863))) 1583 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1584 Subscription Template Printer attributes. 1586 5.3.9 notify-time-interval (integer(0:MAX)) 1588 The 'job-progress' Event occurs each time that a Printer completes a 1589 sheet. Some Notification Recipients do not want to receive an Event 1590 Notification every time this Event occurs. This attribute allows a 1591 Subscribing Client to request how often it wants to receive Event 1592 Notifications for 'job-progress' Events. The value of this attribute 1593 MAY be any nonnegative integer (0,MAX) indicating the minimum number 1594 of seconds between 'job-progress' Event Notifications. 1596 The Printer MUST support this attribute if and only if the Printer 1597 supports the 'job-progress' Event. 1599 A client MAY supply this attribute in a Subscription Creation 1600 Operation. If the client does not supply this attribute in the 1601 Subscription Creation Operation, the Subscription Object either (1) 1602 MAY contain the "notify-time-interval" attribute with a '0' value or 1603 (2) NEED NOT contain this attribute at all. There is no "notify- 1604 time-interval-default" Printer attribute. 1606 There is no "notify-time-interval-supported" Printer attribute. 1608 If the 'job-progress' Event occurs and a Subscription Object contains 1609 the 'job-progress' Event as a value of the 'notify-events' attribute, 1610 there are two cases to consider: 1612 1. This attribute is not present on the Subscription Object or has 1613 the value of 0. The Printer MUST generate and deliver an Event 1614 Notification (as is the case with other Events). 1616 2. This attribute is present with a nonzero value of N: 1618 a) If the Printer has not sent an Event Notification for the 'job- 1619 progress' Event for the associated Subscription Object within 1620 the past N seconds, the Printer MUST deliver an Event 1621 Notification for the Event that just occurred. Note when the 1622 Printer completes the first page of a Job, this rule implies 1623 that the Printer delivers an Event Notification for a Per-Job 1624 Subscription Object. 1626 b) Otherwise, the Printer MUST NOT generate or deliver an Event 1627 Notification for the associated Subscription Object. The 1628 Printer MUST NOT increase the value of the "notify-sequence- 1629 number" Subscription Object attribute (i.e., the sequence of 1630 values of the "notify-sequence-number" attribute counts the 1631 Event Notifications that the Printer sent and not the Events 1632 that do not cause an Event Notification to be sent). 1634 It is RECOMMENDED that a Subscribing Client use this attribute when 1635 it subscribes to the 'job-progress' Event, and that the value be 1636 sufficiently large to limit the frequency with which the Printer 1637 delivers Event Notifications requests. 1639 This attribute MUST NOT effect any Events other than 'job-progress'. 1641 5.4 Subscription Description Attributes 1643 Subscription Description Attributes are those attributes that a 1644 Printer adds to a Subscription Object at the time of its creation. 1646 A Printer MUST support all attributes in this Table 2. 1648 A client MUST NOT supply the attributes in Table 2 in a Subscription 1649 Template Attributes Group of a Subscription Creation Operation. 1650 There are no corresponding default or supported attributes. 1652 Table 2 - Subscription Description Attributes 1653 Subscription Object attributes: 1655 notify-subscription-id (integer(1:MAX)) 1656 notify-sequence-number (integer(0:MAX)) 1657 notify-lease-expiration-time (integer(0:MAX)) 1658 notify-printer-up-time (integer(1:MAX)) 1659 notify-printer-uri (uri) 1660 notify-job-id (integer(1:MAX)) 1661 notify-subscriber-user-name (name(MAX)) 1663 5.4.1 notify-subscription-id (integer (1:MAX)) 1665 This attribute identifies a Subscription Object instance with a 1666 number that is unique within the context of the Printer. The Printer 1667 generates this value at the time it creates the Subscription Object. 1669 A Printer MUST support this attribute. 1671 The Printer MAY assign the value of this attribute sequentially as it 1672 creates Subscription Objects. However, if there is no security on 1673 Subscription objects, sequential assignment exposes the system to a 1674 passive traffic monitoring threat. 1676 The Printer SHOULD avoid re-using recent values of this attribute 1677 during continuous operation of the Printer as well as across power 1678 cycles. Then a Subscribing Client is unlikely to find that a stale 1679 reference accesses a new Subscription Object. 1681 The 0 value is not permitted in order to allow for compatibility with 1682 "job-id" and with MIB table index values, which are recommended not 1683 to be 0. 1685 5.4.2 notify-sequence-number (integer (0:MAX)) 1687 The value of this attribute indicates the number of times that the 1688 Printer has generated and attempted to deliver an Event Notification 1689 for this Subscription object. When an Event Notification contains 1690 this attribute, the Notification Recipient can determine whether it 1691 missed some Event Notifications (i.e., numbers skipped) or received 1692 duplicates (i.e., same number twice). 1694 A Printer MUST support this attribute. 1696 When the Printer creates a Subscription Object, it MUST populate this 1697 attribute with a value of 0. This value indicates that the Printer 1698 has not sent any Event Notifications for this Subscription Object. 1700 Each time the Printer delivers a newly generated Event Notification, 1701 it MUST increase the value of this attribute by 1. For some Delivery 1702 Methods, the Printer MUST include this attribute in each Event 1703 Notification, and the value MUST be the value after it is increased 1704 by 1. That is, the value of this attribute in the first Event 1705 Notification after Subscription object creation MUST be 1, the second 1706 MUST be 2, etc. If a Delivery Method is defined such that the 1707 Notification Recipient returns a response, the Printer can re-try 1708 delivering an Event Notification a certain number of times with the 1709 same sequence number when the Notification Recipient fails to return 1710 a response. 1712 If a Subscription Object lasts long enough to reach the value of MAX, 1713 its next value MUST be 0, i.e., it wraps. 1715 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1717 This attribute specifies the time in the future when the lease on the 1718 Per-Printer Subscription Object will expire, i.e. the "printer-up- 1719 time" value at which the lease will expire. If the value is 0, the 1720 lease never expires. 1722 A Printer MUST support this attribute. 1724 When the Printer creates a Per-Job Subscription Object, this 1725 attribute MUST NOT be present - the Subscription Object lasts exactly 1726 as long as the associated Job object. See also the discussion of the 1727 'job-completed' event in section 5.3.3.4.3 about retention of the Job 1728 object after completion so that a Notification Recipient can query 1729 the Job object after receiving the 'job-completed' Event 1730 Notification. 1732 When the Printer creates a Per-Printer Subscription Object, it 1733 populates this attribute with a value that is the sum of the values 1734 of the Printer's "printer-up-time" attribute and the Subscription 1735 Object's "notify-lease-duration" attribute with the following 1736 exception. If the value of the Subscription Object's "notify-lease- 1737 duration" attribute is 0 (i.e., no expiration time), then the value 1738 of this attribute MUST be set to 0 (i.e., no expiration time). 1740 When the Printer powers up, it MUST populate this attribute in each 1741 persistent Subscription Object with a value using the algorithm in 1742 the previous paragraph. 1744 When the "printer-up-time" equals the value of this attribute, the 1745 Printer MUST delete the Subscription Object. A client can extend a 1746 lease of a Per-Printer Subscription Object with the Renew- 1747 Subscription operation (see section 11.2.6). 1749 Note: In order to compute the number of seconds remaining in a lease 1750 for a Per-Printer Subscription Object, a client can subtract the 1751 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1752 from the Subscription's "notify-lease-expiration-time" attribute. 1754 5.4.4 notify-printer-up-time (integer(1:MAX)) 1756 This attribute is an alias for the Printer's "printer-up-time" 1757 attribute " (see [RFC2911] section 4.4.29). In other words, when 1758 this attribute is queried with the Get-Subscriptions or Get- 1759 Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), 1760 the value returned is the current value of the Printer's "printer-up- 1761 time" attribute, rather than the time at which the Subscription 1762 Object was created. 1764 A Printer MUST support this attribute. 1766 When the Printer creates a Per-Job Subscription Object, this 1767 attribute MUST NOT be present. When the Printer creates a Per- 1768 Printer Subscription Object, this attribute MUST be present. 1770 Note: this attribute exists in a Per-Printer Subscription Object so 1771 that a client using the Get-Subscription-Attributes or Get- 1772 Subscription operations can convert the Per-Printer Subscription's 1773 "notify-lease-expiration-time" attribute to wall clock time with one 1774 request. If the value of the "notify-lease-expiration-time" 1775 attribute is not 0 (i.e., no expiration time), then the difference 1776 between the "notify-lease-expiration-time" attribute and the "notify- 1777 printer-up-time" is the remaining number of seconds on the lease from 1778 the current time. 1780 5.4.5 notify-printer-uri (uri) 1782 This attribute identifies the Printer object that created this 1783 Subscription Object. 1785 A Printer MUST support this attribute. 1787 During a Subscription Creation Operation, the Printer MUST populate 1788 this attribute with the value of the "printer-uri" operation 1789 attribute in the request. From the Printer URI, the client can, for 1790 example, determine what security scheme was used. 1792 5.4.6 notify-job-id (integer(1:MAX)) 1794 This attribute specifies whether the containing Subscription Object 1795 is a Per-Job or Per-Printer Subscription Object, and for Per-Job 1796 Subscription Objects, it specifies the associated Job. 1798 A Printer MUST support this attribute. 1800 If this attribute is not present, the Subscription Object MUST be a 1801 Per-Printer Subscription. If this attribute is present, the 1802 Subscription Object MUST be a Per-Job Subscription Object and this 1803 attribute MUST identify the Job with which the Subscription Object is 1804 associated. 1806 Note: This attribute could be useful to a Notification Recipient that 1807 receives an Event Notification generated from a Per-Job Subscription 1808 Object and caused by a Printer Event. The Event Notification gives 1809 access to the Printer and the Subscription Object. The Event 1810 Notification gives access to the associated Job only via this 1811 attribute. See discussion of the 'job-completed' event in section 1812 5.3.3.4.3 about retention of the Job object after completion so that 1813 a Notification Recipient can query the Job object after receiving the 1814 'job-completed' Event Notification. 1816 5.4.7 notify-subscriber-user-name (name(MAX)) 1818 This attribute contains the name of the user who performed the 1819 Subscription Creation Operation. 1821 A Printer MUST support this attribute. 1823 The Printer MUST populates this attribute with the most authenticated 1824 printable name that it can obtain from the authentication service 1825 over which the Subscription Creation Operation was received. The 1826 Printer uses the same mechanism for determining the value of this 1827 attribute as it does for a Job's "job-originating-user-name" (see 1828 [RFC2911] section 4.3.6). 1830 Note: To help with authentication, a Subscription Object may have 1831 additional private attributes about the user, e.g., a credential of a 1832 principal. Such private attributes are implementation-dependent and 1833 not defined in this document. 1835 6 Printer Description Attributes Related to Notification 1837 This section defines the Printer Description attributes that are 1838 related to Notification. Table 3 lists the Printer Description 1839 attributes, indicates the Printer support required for conformance, 1840 and whether or not the attribute is READ-ONLY (see section 3.1): 1842 Table 3 - Printer Description Attributes Associated with Notification 1843 Printer object attributes: REQUIRED READ-ONLY 1845 printer-state-change-time (integer(1:MAX)) No Yes 1846 printer-state-change-date-time (dateTime) No Yes 1848 6.1 printer-state-change-time (integer(1:MAX)) 1850 This OPTIONAL attribute records the most recent time at which the 1851 'printer-state-changed' Printer Event occurred whether or not any 1852 Subscription objects were listening for this event. This attribute 1853 helps a client or operator to determine how long the Printer has been 1854 in its current state. 1856 A Printer MAY support this attribute and if so, the attribute MUST be 1857 READ-ONLY. 1859 On power-up, the Printer MUST populate this attribute with the value 1860 of its "printer-up-time" attribute, so that it always has a value. 1861 Whenever the 'printer-state-changed' Printer Event occurs, the 1862 Printer MUST update this attribute with the value of the Printer's 1863 "printer-up-time" attribute. 1865 6.2 printer-state-change-date-time (dateTime) 1867 This OPTIONAL attribute records the most recent time at which the 1868 'printer-state-changed' Printer Event occurred whether or not there 1869 were any Subscription Objects listening for this event. This 1870 attribute helps a client or operator to determine how long the 1871 Printer has been in its current state. 1873 A Printer MAY support this attribute and if so, the attribute MUST be 1874 READ-ONLY. 1876 On power-up, the Printer MUST populate this attribute with the value 1877 of its "printer-current-time" attribute, so that it always has a 1878 value (see [RFC2911] section 4.4.30 on "printer-current-time"). 1879 Whenever the 'printer-state-changed' Printer Event occurs, the 1880 Printer MUST update this attribute with the value of the Printer's 1881 "printer-current-time" attribute. 1883 7 New Values for Existing Printer Description Attributes 1885 This section contains those attributes for which additional values 1886 are added. 1888 7.1 operations-supported (1setOf type2 enum) 1890 The following "operation-id" values are added in order to support the 1891 new operations defined in this document: 1893 Table 4 - Operation-id assignments 1894 Value Operation Name 1896 0x0016 Create-Printer-Subscriptions 1897 0x0017 Create-Job-Subscriptions 1898 0x0018 Get-Subscription-Attributes 1899 0x0019 Get-Subscriptions 1900 0x001A Renew-Subscription 1901 0x001B Cancel-Subscription 1903 8 Attributes Only in Event Notifications 1905 This section contains those attributes that exist only in Event 1906 Notifications and do not exist in any objects. 1908 8.1 notify-subscribed-event (type2 keyword) 1910 This attribute indicates the Subscribed Event that caused the Printer 1911 to deliver this Event Notification. This attribute exists only in 1912 Event Notifications. 1914 This attribute MUST contain one of the values of the "notify-events" 1915 attribute in the Subscription Object, i.e., one of the Subscribed 1916 Event values. Its value is the Subscribed Event that "matches" the 1917 Event that caused the Printer to deliver this Event Notification. 1918 This Subscribed Event value may be identical to the Event or the 1919 Event may be a sub-value of the Subscribed Event. For example, the 1920 'job-completed' Event (which is a sub-event of the 'job-state- 1921 changed' event) would cause the Printer to deliver an Event 1922 Notification for either the 'job-completed' or 'job-state-changed' 1923 Subscribed Events and to deliver the 'job-completed' or 'job-state- 1924 changed' value for this attribute, respectively. See section 5.3.3.5 1925 for the "matching" rules of Subscribed Events and for additional 1926 examples. 1928 The Delivery Method Document specifies whether the Printer includes 1929 the value of this attribute in an Event Notification. 1931 8.2 notify-text (text(MAX)) 1933 This attribute contains a Human Consumable text message (see section 1934 9.2). This message describes the Event and is encoded as plain text, 1935 i.e., 'text/plain' with the charset specified by Subscription 1936 Object's "notify-charset" attribute. 1938 Note: this attribute contains a text message only and must not 1939 contain any encoding information, such as 'text/plain'. The 1940 'text/plain' encoding is implicit and thus the charset must be 1941 specified by an alternate mechanism, namely the "notify-charset" 1942 attribute. 1944 The Delivery Method Document specifies whether the Printer includes 1945 this attribute in an Event Notification. 1947 9 Event Notification Content 1949 This section defines the Event Notification content that the Printer 1950 delivers when an Event occurs. 1952 When an Event occurs, the Printer MUST find each Subscription object 1953 whose "notify-events" attribute "matches" the Event. See section 1954 5.3.3.5 for details on "matching". For each matched Subscription 1955 Object, the Printer MUST create an Event Notification with the 1956 content and format that the Delivery Method Document specifies. The 1957 content contains the value of attributes specified by the Delivery 1958 Method Document. The Printer obtains the values immediately after 1959 the Event occurs. For example, if the "printer-state" attribute 1960 changes from 'idle' to 'processing', the Event 'printer-state- 1961 changed' occurs and the Printer puts various attributes into the 1962 Event Notification, including "printer-up-time" and "printer-state" 1963 with the values that they have immediately after the Event occurs, 1964 i.e., the value of "printer-state" is 'processing'. 1966 Event Notification Ordering: 1968 When a Printer delivers Event Notifications, the Event Notifications 1969 from any given Subscription Object MUST be in time stamp order, i.e., 1970 in order of increasing "printer-up-time" attribute value in the Event 1971 Notification (see Table 5). These Event Notifications MAY be 1972 interleaved with those from other Subscription Objects, as long as 1973 those others are also in time stamp order. The Printer MUST observe 1974 these ordering requirements whether delivering multiple pending 1975 Events as multiple separate Event Notifications or together in a 1976 single Compound Event Notification. 1978 If a Subscribing Client wants the Printer to deliver certain Event 1979 Notifications in time stamp order, the Subscribing Client uses a 1980 single Subscription Object. Even so, depending on the underlying 1981 transport, the actual order that a Notification Recipient receives 1982 separate Event Notifications may differ from the order sent by the 1983 Printer (e.g., email). 1985 Example: Consider two Per-Printer Subscription Objects: SO1 and SO2. 1986 SO1 requests 'job-state-changed' events and SO2 requests 'printer- 1987 state-changed' events. The number in parens is the time stamp. The 1988 following Event Notification sequences are the only ones that conform 1989 to the ordering requirements for the Printer to deliver the Event 1990 Notifications: 1992 (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 1993 'job-completed' (1009), SO2: 'printer-stopped' (1005) 1995 (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2: 1996 'printer-stopped' (1005), SO1: 'job-completed' (1009) 1998 (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1: 1999 'job-stopped' (1005), SO1: 'job-completed' (1009) 2001 (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1: 2002 'job-stopped' (1005), SO1: 'job-completed' (1009) 2004 Examples (b) and (c) are interleaved; examples (a) and (d) are not 2005 interleaved and are not appropriate for some Delivery Methods. 2007 If two different Events occur simultaneously, or nearly so (e.g., 2008 "printer-up-time" has the same value for both), the Printer MUST 2009 create a separate Event Notification for each Event, even if the 2010 associated Subscription Object is the same for both Events. However, 2011 the Printer MAY combine these distinct Event Notifications into a 2012 single Compound Event Notification if the Delivery Method supports 2013 Compound Event Notifications. For example, suppose that two nearly- 2014 simultaneously Events represent two successive 'printer-state- 2015 changed' Events, one from 'idle' to 'processing' and another from 2016 'processing' to 'stopped'. These two Events have the same name but 2017 are different instances of the Event. Then the Printer MUST create a 2018 separate Event Notification for each Event and SHOULD accurately 2019 report the "printer-state" of the first Event as 'processing' and the 2020 second Event as 'stopped'. 2022 If a Subscription Object contains more than one Subscribed Event, and 2023 several Events occur in quick succession each matching a different 2024 Subscribed Event in the Subscription Object, the Printer MUST NOT 2025 generate a single Event Notification from several of these Events, 2026 but MAY combine distinct Event Notifications into a single Compound 2027 Event Notification if the Delivery Method supports Compound Event 2028 Notifications. 2030 After the Printer has created the Event Notification, the Printer 2031 delivers it via either a: 2033 Push Delivery Method: The Printer delivers the Event 2034 Notification shortly after an Event occurs. For some Push 2035 Delivery Methods, the Notification Recipient MUST deliver a 2036 response; for others it MUST NOT deliver a response. 2038 Pull Delivery Method: The Printer saves Event Notifications for 2039 some Event Life and expects the Notification Recipient to 2040 request Event Notifications. The Printer returns the Event 2041 Notifications in a response to such a request. 2043 If an error that meets the following conditions occurs, the Printer 2044 MUST cancel the Subscription Object. 2046 a) the error occurs during the delivering of an Event Notification 2047 generated from Subscription Object S AND 2049 b) the error would continue to occur every time the Printer delivers 2050 an Event Notification generated from Subscription Object S in the 2051 future. 2053 For example, if the address of the "notify-recipient-uri" of 2054 Subscription Object A references a non-existent target and the 2055 Printer determines this fact, it MUST delete Subscription Object A. 2057 The next two sections describe the values that a Printer delivers in 2058 the content of Machine Consumable and Human Consumable Event 2059 Notifications, respectively. 2061 The tables in the sub-sections of this section contain the following 2062 columns: 2064 a) Source Value: the name of the attribute that supplies the value 2065 for the Event Notification. Asterisks in this field refer to a 2066 note below the table. 2068 b) Delivers: if the Printer supports the value (column 1) on the 2069 Source Object (column 3) the Delivery Method MUST specify: 2071 MUST: that the Printer MUST deliver the value. 2073 SHOULD: either that the Printer MUST deliver the value or that 2074 the value is incompatible with the Delivery Method. 2076 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 2077 or NEED NOT deliver the value. The Delivery Method specifies 2078 the level of conformance for the Printer. 2080 c) Source Object: the object from which the source value comes. If 2081 the object is "Event Notification", the Printer fabricates the 2082 value when it delivers the Event Notification. See section 8. 2084 9.1 Content of Machine Consumable Event Notifications 2086 This section defines the attributes that a Delivery Method MUST 2087 mention in a Delivery Method Document when specifying the Machine 2088 Consumable Event Notification's contents. 2090 This document does not define the order of attributes in Event 2091 Notifications. However, Delivery Method Documents MAY define the 2092 order of some or all of the attributes. 2094 A Delivery Method Document MUST specify additional attributes (if 2095 any) that a Printer implementation delivers in a Machine Consumable 2096 Event Notification. 2098 Notification Recipients MUST be able to accept Event Notifications 2099 containing attributes they do not recognize. What a Notification 2100 Recipient does with an unrecognized attribute is implementation- 2101 dependent. Notification Recipients MAY attempt to display 2102 unrecognized attributes anyway or MAY ignore them. 2104 The next three sections define the attributes in Event Notification 2105 Contents that are: 2107 1. for all Events 2109 2. for Job Events only 2111 3. for Printer Events only 2113 9.1.1 Event Notification Content Common to All Events 2115 This section lists the attributes that a Delivery Method Document 2116 MUST specify for all Events. 2118 Table 5 lists potential values in each Event Notification. 2120 Table 5 - Attributes in Event Notification Content 2121 Source Value Delivers Source Object 2123 notify-subscription-id (integer(1:MAX)) MUST Subscription 2124 notify-printer-uri (uri) MUST Subscription 2125 notify-subscribed-event (type2 keyword) MUST Event 2126 Notification 2127 printer-up-time (integer(MIN:MAX)) MUST Printer 2128 printer-current-time (dateTime) * MUST Printer 2129 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 2130 notify-charset (charset) SHOULD Subscription 2131 notify-natural-language (naturalLanguage) SHOULD Subscription 2132 notify-user-data (octetString(63)) ** SHOULD Subscription 2133 notify-text (text) SHOULD Event 2134 Notification 2135 attributes from the "notify-attributes" MAY Printer 2136 attribute *** 2137 attributes from the "notify-attributes" MAY Job 2138 attribute *** 2139 attributes from the "notify-attributes" MAY Subscription 2140 attribute *** 2142 *A Printer MUST deliver this value only if and only if it supports 2143 the Printer's "printer-current-time" attribute. 2145 ** If the Subscription Object does not contain a "notify-user-data" 2146 attribute and the Delivery Method Document REQUIRES the Printer to 2147 deliver the "notify-user-data" source value in the Event 2148 Notification, the Printer MUST deliver an octet-string of length 0. 2150 *** The last three rows represent additional attributes that a client 2151 MAY request via the "notify-attributes" attribute. A Printer MAY 2152 support the "notify-attributes" attribute. The Delivery Method MUST 2153 say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED 2154 NOT support the "notify-attributes" attribute and specific values of 2155 this attribute. The Delivery Method MAY say that support for the 2156 "notify-attributes" is conditioned on support of the attribute by the 2157 Printer or it MAY say that Printer MUST support the "notify- 2158 attributes" attribute if the Printer supports the Delivery Method. 2160 9.1.2 Additional Event Notification Content for Job Events 2162 This section lists the additional attributes that a Delivery Method 2163 Document MUST specify for Job Events. See Table 6. 2165 Table 6 - Additional Event Notification Content for Job Events 2166 Source Value Delivers Source 2167 Object 2169 job-id (integer(1:MAX)) MUST Job 2170 job-state (type1 enum) MUST Job 2171 job-state-reasons (1setOf type2 keyword) MUST Job 2172 job-impressions-completed (integer(0:MAX)) * MUST Job 2174 * The Printer MUST deliver the "job-impressions-completed" attribute 2175 in an Event Notification only for the combinations of Events and 2176 Subscribed Events shown in Table 7. 2178 Table 7 - Combinations of Events and Subscribed Events for "job- 2179 impressions-completed" 2180 Job Event Subscribed Job Event 2182 'job-progress' 'job-progress' 2183 'job-completed' 'job-completed' 2184 'job-completed' 'job-state-changed' 2186 9.1.3 Additional Event Notification Content for Printer Events 2188 This section lists the additional attributes that a Delivery Method 2189 Document MUST specify for Printer Events. See Table 8. 2191 Table 8 - Additional Event Notification Content for Printer Events 2192 Source Value Delivers Source Object 2194 printer-state (type1 enum) MUST Printer 2195 printer-state-reasons (1setOf type2 MUST Printer 2196 keyword) 2197 printer-is-accepting-jobs (boolean) MUST Printer 2199 9.2 Content of Human Consumable Event Notification 2201 This section defines the information that a Delivery Method MUST 2202 mention in a Delivery Method Document when specifying the Human 2203 Consumable Event Notifications contents or the value of the "notify- 2204 text" attribute. 2206 Such a Delivery Method MUST specify the following information and a 2207 Printer SHOULD deliver it: 2209 a) the Printer name (see Table 9) 2211 b) the time of the Event (see Table 11) 2212 c) for Printer Events only: 2213 i) the Event (see Table 10) and/or Printer state information 2214 (see Table 14) 2215 d) for Job Events only: 2216 i) the job identity (see Table 12) 2217 ii) the Event (see Table 10) and/or Job state information (see 2218 Table 13) 2220 The subsections of this section specify the attributes that a Printer 2221 MUST use to obtain this information. 2223 A Delivery Method Document MUST specify additional information (if 2224 any) that a Printer implementation delivers in a Human Consumable 2225 Event Notification or in the "notify-text" attribute. 2227 A client MUST NOT request additional attributes via the "notify- 2228 attributes" attribute because this attribute works only for Machine 2229 Consumable Event Notifications. 2231 Notification Recipients MUST NOT expect to be able to parse the Human 2232 Consumable Event Notification contents or the value of the "notify- 2233 text" attribute. 2235 The next three sections define the attributes in Event Notification 2236 Contents that are: 2238 a) for all Events 2239 b) for Job Events only 2240 c) for Printer Events only 2242 9.2.1 Event Notification Content Common to All Events 2244 This section lists the source of the information that a Delivery 2245 Method MUST specify for all Events. 2247 There is a separate table for each piece of information. Each row in 2248 the table represents a source value for the information and the 2249 values are listed in order of preference, with the first one being 2250 the preferred one. An implementation SHOULD use the source value 2251 from the earliest row in each table. It MAY use the source value 2252 from another row instead, or it MAY combine the source values from 2253 several rows. An implementation is free to determine the best way to 2254 present this information. 2256 In all tables of this section, all rows contain a "MAY" in order to 2257 state that the Delivery Method specifies the conformance. 2259 Table 9 lists the source of the information for the Printer Name. 2260 The "printer-name" is more user-friendly unless the Notification 2261 Recipient is in a place where the Printer name is not meaningful. 2262 For example, an implementation could have the intelligence to deliver 2263 the value of the "printer-name" attribute to a Notification Recipient 2264 that can access the Printer via value of the "printer-name" attribute 2265 and otherwise deliver the value of the "notify-printer-uri" 2266 attribute. 2268 Table 9 - Printer Name in Event Notification Content 2269 Source Value Delivers Source Object 2271 printer-name (name(127)) MAY Printer 2272 notify-printer-uri (uri) MAY Subscription 2274 Table 10 lists the source of the information for the Event name. A 2275 Printer MAY combine this information with state information described 2276 for Jobs in Table 13 or for Printers in Table 14. 2278 Table 10 - Event Name in Event Notification Content 2279 Source Value Delivers Source Object 2281 notify-subscribed-event (type2 keyword) MAY Subscription 2283 Table 11 lists the source of the information for the time that the 2284 Event occurred. A Printer can deliver this value only if it supports 2285 the Printer's "printer-current-time" attribute. If a Printer does 2286 not support the "printer-current-time" attribute, it MUST NOT deliver 2287 the "printer-up-time" value instead, since it is not an allowed 2288 option for human consumable information. 2290 Table 11 - Event Time in Event Notification Content 2291 Source Value Delivers Source Object 2293 printer-current-time (dateTime) MAY Printer 2295 9.2.2 Additional Event Notification Content for Job Events 2297 This section lists the source of the additional information that a 2298 Delivery Method MUST specify for Job Events. 2300 Table 12 lists the source of the information for the job name. The 2301 "job-name" is likely more meaningful to a user than "job-id". 2303 Table 12 - Job Name in Event Notification Content 2304 Source Value Delivers Source Object 2306 job-name (name(MAX)) MAY Job 2307 job-id (integer(1:MAX)) MAY Job 2309 Table 13 lists the source of the information for the job state. If a 2310 Printer supports the "job-state-message" and "job-detailed-state- 2311 message" attributes, it SHOULD use those attributes for the job state 2312 information, otherwise, it should fabricate such information from the 2313 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2314 combine this information with Event information. 2316 Table 13 - Job State in Event Notification Content 2317 Source Value Delivers Source 2318 Object 2320 job-state-message (text(MAX)) MAY Job 2321 job-detailed-status-messages (1setOf text(MAX)) MAY Job 2322 job-state (type1 enum) MAY Job 2323 job-state-reasons (1setOf type2 keyword) MAY Job 2325 9.2.3 Additional Event Notification Content for Printer Events 2327 This section lists the source of the additional information that a 2328 Delivery Method MUST specify for Printer Events. 2330 Table 14 lists the source of the information for the printer state. 2331 If a Printer supports the "printer-state-message", it SHOULD use that 2332 attribute for the job state information, otherwise it SHOULD 2333 fabricate such information from the "printer-state" and "printer- 2334 state-reasons". For some Events, a Printer MAY combine this 2335 information with Event information. 2337 Table 14 - Printer State in Event Notification Content 2338 Source Value Delivers Source 2339 Object 2341 printer-state-message (text(MAX)) MAY Printer 2342 printer-state (type1 enum) MAY Printer 2343 printer-state-reasons (1setOf type2 keyword) MAY Printer 2344 printer-is-accepting-jobs (boolean) MAY Printer 2346 10 Delivery Methods 2348 A Delivery Method is the mechanism, i.e., protocol, by which the 2349 Printer delivers an Event Notification to a Notification Recipient. 2350 There are several potential Delivery Methods for Event Notifications, 2351 standardized, as well as proprietary. This specification REQUIRES 2352 that the 'ippget' Pull Delivery Method [ipp-get-method] be supported. 2353 Conforming implementations MAY support additional Push or Pull 2354 Delivery Methods as well. This document does not define any of these 2355 delivery mechanisms. Each Delivery Method MUST be defined in a 2356 Delivery Method Document that is separate from this document. New 2357 Delivery Methods will be created as needed using an extension to the 2358 registration procedures defined in [RFC2911]. Such documents are 2359 registered with IANA (see section 23.7.3). 2361 The following sorts of Delivery Methods are possible: 2363 - The Notification Recipient polls for Event Notifications at 2364 intervals directed by the Printer 2366 - The Printer delivers Event Notifications to the Notification 2367 Recipient using http as the transport. 2369 - The Printer delivers an email message. 2371 This section specifies how to define a Delivery Method Document and 2372 what to put in such a document. 2374 A Delivery Method Document MUST contain an exact copy of the 2375 following paragraph, caption and table. In addition, column 2 of the 2376 table in the Delivery Method Document MUST contain answers to 2377 questions in column 1 for the Delivery Method. Also, the Delivery 2378 Method document MUST contain a reference to this document and call 2379 that reference [ipp-ntfy] because the table contains an [ipp-ntfy] 2380 reference. 2382 If a Printer supports this Delivery Method, the following are its 2383 characteristics. 2385 Table 15 - Information about the Delivery Method 2386 Document Method Conformance Requirement Delivery Method 2387 Realization 2389 1. What is the URL scheme name for the Push 2390 Delivery Method or the keyword method 2391 name for the Pull Delivery Method? 2392 2. Is the Delivery Method REQUIRED, 2393 RECOMMENDED, or OPTIONAL for an IPP 2394 Printer to support? 2395 3. What transport and delivery protocols 2396 does the Printer use to deliver the 2397 Event Notification Content, i.e., what 2398 is the entire network stack? 2399 4. Can several Event Notifications be 2400 combined into a Compound Event 2401 Notification? 2402 5. Is the Delivery Method initiated by the 2403 Notification Recipient (pull), or by the 2404 Printer (push)? 2405 6. Is the Event Notification content 2406 Machine Consumable or Human Consumable? 2407 7. What section in this document answers 2408 the following question? For a Machine 2409 Consumable Event Notification, what is 2410 the representation and encoding of 2411 values defined in section 9.1 of [ipp- 2412 ntfy] and the conformance requirements 2413 thereof? For a Human Consumable Event 2414 Notification, what is the representation 2415 and encoding of pieces of information 2416 defined in section 9.2 of [ipp-ntfy] and 2417 the conformance requirements thereof? 2418 8. What are the latency and reliability of 2419 the transport and delivery protocol? 2420 9. What are the security aspects of the 2421 transport and delivery protocol, e.g., 2422 how it is handled in firewalls? 2423 10. What are the content length 2424 restrictions? 2425 11. What are the additional values or 2426 pieces of information that a Printer 2427 delivers in an Event Notification 2428 content and the conformance requirements 2429 thereof? 2431 Document Method Conformance Requirement Delivery Method 2432 Realization 2434 12. What are the additional Subscription 2435 Template and/or Subscription Description 2436 attributes and the conformance 2437 requirements thereof? 2438 13. What are the additional Printer 2439 Description attributes and the 2440 conformance requirements thereof? 2442 11 Operations for Notification 2444 This section defines all of the operations for Notification. Section 2445 7.1 assigns the "operation-id" for each operation. The following two 2446 sub-sections define Subscription Creation Operations, and other 2447 operations. 2449 11.1 Subscription Creation Operations 2451 This section defines the Subscription Creation Operations. The first 2452 section on Create-Job-Subscriptions gives most of the information. 2453 The other Subscription Creation Operations refer to the section on 2454 Create-Job-Subscriptions, even though the Create-Job-Subscriptions 2455 operation is the only OPTIONAL operation in this document (see 2456 section 12). 2458 A Printer MUST support Create-Printer-Subscriptions and the 2459 Subscription Template Attributes Group in Job Creation operations. 2460 It MAY support Create-Job-Subscriptions operations. 2462 11.1.1 Create-Job-Subscriptions Operation 2464 The operation creates one or more Per-Job Subscription Objects. The 2465 client supplies one or more Subscription Template Attributes Groups 2466 each containing one or more of Subscription Template Attributes 2467 (defined in section 5.3). 2469 Except for errors, the Printer MUST create exactly one Per-Job 2470 Subscription Object from each Subscription Template Attributes Group 2471 in the request, even if the newly created Subscription Object would 2472 have identical behavior to some existing Subscription Object. The 2473 Printer MUST associate each newly created Per-Job Subscription Object 2474 with the target Job, which is specified by the "notify-job-id" 2475 operation attribute. 2477 The Printer MUST accept the request in any of the target job's 'not- 2478 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2479 'processing-stopped'. The Printer MUST NOT change the job's "job- 2480 state" attribute because of this operation. If the target job is in 2481 any of the 'completed' states, i.e., 'completed', 'canceled', or 2482 'aborted, then the Printer MUST reject the request and return the 2483 'client-error-not-possible' status code; the response MUST NOT 2484 contain any Subscription Attribute Groups. 2486 Access Rights: To create Per-Job Subscription Objects, the 2487 authenticated user (see [RFC2911] section 8.3) performing this 2488 operation MUST (1) be the job owner, (2) have Operator or 2489 Administrator access rights for this Printer (see [RFC2911] sections 2490 1 and 8.5), or (3) be otherwise authorized by the Printer's 2491 administrator-configured security policy to create Per-Job 2492 Subscription Objects for the target job. Otherwise the Printer MUST 2493 reject the operation and return: the 'client-error-forbidden', 2494 'client-error-not-authenticated', or 'client-error-not-authorized' 2495 status code as appropriate. 2497 11.1.1.1 Create-Job-Subscriptions Request 2499 The following groups of attributes are part of the Create-Job- 2500 Subscriptions Request: 2502 Group 1: Operation Attributes 2504 Natural Language and Character Set: 2505 The "attributes-charset" and "attributes-natural-language" 2506 attributes as described in [RFC2911] section 3.1.4.1. 2508 Target: 2509 The "printer-uri" attribute which defines the target for this 2510 operation as described in [RFC2911] section 3.1.5. 2512 Requesting User Name: 2513 The "requesting-user-name" attribute SHOULD be supplied by the 2514 client as described in [RFC2911] section 8.3. 2516 11.1.1.1.1 notify-job-id (integer(1:MAX)) 2518 The client MUST supply this attribute and it MUST specify the 2519 Job object to associate the Per-Job Subscription with. The 2520 value of "notify-job-id" MUST be the value of the "job-id" of 2521 the associated Job object. If the client does not supply this 2522 attribute, the Printer MUST reject this request with a 'client- 2523 error-bad-request' status code. 2525 Group 2-N: Subscription Template Attributes 2527 For each occurrence of this group: 2529 The client MUST supply one or more Subscription Template 2530 Attributes in any order. See section 5.3 for a description of 2531 each such attribute. See section 5.2 for details on 2532 processing these attributes. 2534 11.1.1.2 Create-Job-Subscriptions Response 2536 The Printer MUST return to the client the following sets of 2537 attributes as part of a Create-Job-Subscriptions response: 2539 Group 1: Operation Attributes 2541 Status Message: 2542 In addition to the REQUIRED status code returned in every 2543 response, the response OPTIONALLY includes a "status-message" 2544 (text(255)) and/or a "detailed-status-message" (text(MAX)) 2545 operation attribute as described in [RFC2911] sections 13 and 2546 3.1.6. 2548 In this group, the Printer can return any status codes defined 2549 in [RFC2911] and section 12. The following is a description of 2550 the important status codes: 2552 successful-ok: the Printer created all Subscription Objects 2553 requested (see [RFC2911]). 2554 successful-ok-ignored-subscriptions: the Printer created 2555 some Subscription Objects requested but some failed. The 2556 Subscription Attributes Groups with a "notify-status- 2557 code" attribute are the ones that failed (see section 2558 12.1). 2559 client-error-ignored-all-subscriptions: the Printer created 2560 no Subscription Objects requested and all failed. The 2561 Subscription Attributes Groups with a "notify-status- 2562 code" attribute are the ones that failed (see section 2563 12.2). 2564 client-error-not-possible: For this operation and other 2565 Per-Job Subscription operations, this error can occur 2566 because the specified Job has already completed (see 2567 [RFC2911], whether or not the Job is retained in the Job 2568 Retention and/or Job History phases (see [RFC2911] 2569 section 4.3.7.1). 2571 Natural Language and Character Set: 2572 The "attributes-charset" and "attributes-natural-language" 2573 attributes as described in [RFC2911] section 3.1.4.2. 2575 Group 2: Unsupported Attributes 2577 See [RFC2911] section 3.1.7 for details on returning 2578 Unsupported Attributes. This group does not contain any 2579 unsupported Subscription Template Attributes; they are returned 2580 in the Subscription Attributes Group (see below). 2582 Group 3-N: Subscription Attributes 2584 These groups MUST be returned unless the Printer is unable to 2585 interpret the entire request, e.g., the "status-code" parameter 2586 returned in Group 1 has the value: 'client-error-bad-request'. 2588 "notify-status-code" (type2 enum): 2589 Indicates the status of this subscription (see section 13 2590 for the status code definitions). Section 5.2 defines when 2591 this attribute MUST be present in this group. 2593 See section 5.2 for details on the contents of each occurrence 2594 of this group. 2596 11.1.2 Create-Printer-Subscriptions operation 2598 The operation is identical to Create-Job-Subscriptions with 2599 exceptions noted in this section. 2601 The operation creates Per-Printer Subscription Objects instead of 2602 Per-Job Subscription Objects, and associates each newly created Per- 2603 Printer Subscription Object with the Printer specified by the 2604 operation target rather than with a specific Job. 2606 The Printer MUST accept the request in any of its states, i.e., 2607 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its 2608 "printer-state" attribute because of this operation. 2610 Access Rights: To create Per-Printer Subscription Objects, the 2611 authenticated user (see [RFC2911] section 8.3) performing this 2612 operation MUST have (1) Operator or Administrator access rights for 2613 this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise 2614 authorized by the Printer's administrator-configured security policy 2615 to create Per-Printer Subscription Objects for this Printer. 2616 Otherwise, the Printer MUST reject the operation and return: the 2617 'client-error-forbidden', 'client-error-not-authenticated', or 2618 'client-error-not-authorized' status code as appropriate. 2620 11.1.2.1 Create-Printer-Subscriptions Request 2622 The groups are identical to the Create-Job-Subscriptions (see section 2623 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2624 the "notify-job-id" attribute. If the client does supply the 2625 "notify-job-id" attribute, then the Printer MUST treat it as any 2626 other unsupported Operation attribute and MUST return it in the 2627 Unsupported Attributes group. 2629 11.1.2.2 Create-Printer-Subscriptions Response 2631 The groups are identical to the Create-Job-Subscriptions (see section 2632 11.1.1.2). 2634 11.1.3 Job Creation Operations - Extensions for Notification 2636 This document extends the Job Creation operations (see section 3.2) 2637 to create Subscription Objects as a part of the operation. 2639 The Job Creation operations are identical to Create-Job-Subscriptions 2640 operation with exceptions noted in this section. 2642 Unlike the Create-Job-Subscriptions operation, a Job Creation 2643 operation associates the newly created Subscription Objects with the 2644 Job object created by this operation. The operation succeeds if and 2645 only if the Job creation succeeds. If the Printer does not create 2646 some or all of the requested Subscription Objects, the Printer MUST 2647 return a 'successful-ok-ignored-subscriptions' status-code instead 2648 of a 'successful-ok' status-code, but the Printer MUST NOT reject the 2649 operation because of a failure to create Subscription Objects. 2651 If the Job Creation operation includes a Job Template group, the 2652 client MUST supply it after the Operation Attributes group and before 2653 the first Subscription Template Attributes Group. 2655 If a Printer does not support this Notification specification, then 2656 it MUST treat the Subscription Attributes Group like an unknown group 2657 and ignore it (see [RFC2911] section 5.2.2). Because the Printer 2658 ignores the Subscription Attributes Group, it doesn't return them in 2659 the response either, thus indicating to the client that the Printer 2660 doesn't support Notification. 2662 After completion of a successful Job Creation operation, the Printer 2663 generates a 'job-created' event (see section 5.3.3.4.3). 2665 Access Rights: To create Per-Job Subscription Objects, the 2666 authenticated user (see [RFC2911] section 8.3) performing this 2667 operation MUST either have permission to create Jobs on the Printer 2668 or have Operator or Administrator access rights for this Printer (see 2669 [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the 2670 operation and return: the 'client-error-forbidden', 'client-error- 2671 not-authenticated', or 'client-error-not-authorized' status code as 2672 appropriate. 2674 11.1.3.1 Job Creation Request 2676 The groups for this operation are sufficiently different from the 2677 Create-Job-Subscriptions operation that they are all presented here. 2678 The following groups of attributes are supplied as part of a Job 2679 Creation Request: 2681 Group 1: Operation Attributes 2683 Same as defined in [RFC2911] for Print-Job, Print-URI, and 2684 Create-Job requests. 2686 Group 2: Job Template Attributes 2688 The client OPTIONALLY supplies a set of Job Template attributes 2689 as defined in [RFC2911] section 4.2. 2691 Group 3 to N: Subscription Template Attributes 2693 The same as Group 2-N in Create-Job-Subscriptions. See section 2694 11.1.1.1. 2695 Group N+1: Document Content (Print-Job only) 2697 The client MUST supply the document data to be processed. 2699 11.1.3.2 Job Creation Response 2701 The Printer MUST return to the client the following sets of 2702 attributes as part of a Print-Job, Print-URI, and Create-Job 2703 Response: 2705 Group 1: Operation Attributes 2707 Status Message: 2709 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2710 Job requests. 2712 In this group, the Printer can return any status codes defined 2713 in [RFC2911] and section 12. The following is a description of 2714 the important status codes: 2716 successful-ok: the Printer created the Job and all 2717 Subscription Objects requested (see [RFC2911]. 2718 successful-ok-ignored-subscriptions: the Printer created 2719 the Job and not all of the Subscription Objects requested 2720 (see section 12.1). This status-code hides 'successful- 2721 ok-xxx' status-codes that could reveal problems in Job 2722 creation. The Printer MUST NOT return the 'client-error- 2723 ignored-all-subscriptions' status code for Job Creation 2724 operations because the Printer returns an error status- 2725 code only when it fails to create a Job. 2727 Natural Language and Character Set: 2728 The "attributes-charset" and "attributes-natural-language" 2729 attributes as described in [RFC2911] section 3.1.4.2. 2731 Group 2: Unsupported Attributes 2733 See [RFC2911] section 3.1.7 for details on returning 2734 Unsupported Attributes. This group does not contain any 2735 unsupported Subscription Template Attributes; they are returned 2736 in the Subscription Attributes Group (see below). 2738 Group 3: Job Object Attributes 2740 The "job-id" of the Job Object just created, etc., as defined 2741 in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. 2743 Group 4 to N: Subscription Attributes 2745 These groups MUST be returned if and only if the client 2746 supplied Subscription Template Attributes and the operation was 2747 accepted. 2748 See section 5.2 for details on the contents of each occurrence 2749 of this group. 2751 11.2 Other Operations 2753 This section defines other operations on Subscription objects. 2755 11.2.1 Restart-Job Operation - Extensions for Notification 2757 The Restart-Job operation [RFC2911] is neither a Job Creation 2758 operation nor a Subscription Creation operation (see section 3.2). 2760 For the Restart-Job operation, the client MUST NOT supply any Job 2761 Subscription Attributes Groups. The Printer MUST treat any supplied 2762 Job Subscription Attributes as unsupported attributes. 2764 For this operation, the Printer does not return a job-id or any 2765 Subscription Attributes groups because the Printer reuses the 2766 existing Job object with the same job-id and the existing Per-Job 2767 Subscription Objects with the same subscription-ids. However, after 2768 successful completion of this operation, the Printer generates a 2769 'job-created' event (see section 5.3.3.4.3). 2771 11.2.2 Validate-Job Operation - Extensions for Notification 2773 A client can test whether one or more Subscription Objects could be 2774 created using the Validate-Job operation. The client supplies one or 2775 more Subscription Template Attributes Groups (defined in section 2776 5.3), just as in a Job Creation request. 2778 A Printer MUST support this extension to this operation. 2780 The Printer MUST accept requests that are identical to the Job 2781 Creation request defined in section 11.1.3.1, except that the request 2782 MUST NOT contain document data. 2784 The Printer MUST return the same groups and attributes as the Print- 2785 Job operation (section 11.1.3.1) with the following exceptions. The 2786 Printer MUST NOT return a Job Object Attributes Group because no Job 2787 is created. The Printer MUST NOT return the "notify-subscription-id" 2788 attribute in any Subscription Attribute Group because no Subscription 2789 Object is created. 2791 If the Printer would succeed in creating a Subscription Object, the 2792 corresponding Subscription Attributes Group either has no 'status- 2793 code' attribute or a 'status-code' attribute with a value of 2794 'successful-ok-too-many-events' or 'successful-ok-ignored-or- 2795 substituted-attributes' (see sections 5.2 and 13). The status-codes 2796 have the same meaning as in Job Creation except the results state 2797 what "would happen". 2799 The Printer MUST validate Subscription Template Attributes Groups in 2800 the same manner as the Job Creation operations. 2802 11.2.3 Get-Printer-Attributes - Extensions for Notification 2804 This operation is extended so that it returns Printer attributes 2805 defined in this document. 2807 A Printer MUST support this extension to this operation. 2809 In addition to the requirements of [RFC2911] section 3.2.5, a Printer 2810 MUST support the following additional values for the "requested- 2811 attributes" Operation attribute in this operation and return such 2812 attributes in the Printer Object Attributes group of its response. 2814 1. Subscription Template Attributes: Each supported attribute in 2815 column 2 of Table 1. 2817 2. New Printer Description Attributes: Each supported attribute in 2818 section 6. 2820 3. New Group Name: The 'subscription-template' group name, which 2821 names all supported Subscription Template Attribute in column 2 2822 of Table 1. This group name is also used in the Get- 2823 Subscription-Attributes and Get-Subscriptions operation with an 2824 analogous meaning. 2826 4. Extended Group Name: The 'all' group name, which names all 2827 Printer attributes according to [RFC2911] section 3.2.5. In 2828 this extension 'all' names all attributes specified in [RFC2911] 2829 plus those named in items 1 and 2 of this list. 2831 11.2.4 Get-Subscription-Attributes operation 2833 This operation allows a client to request the values of the 2834 attributes of a Subscription Object. 2836 A Printer MUST support this operation. 2838 This operation is almost identical to the Get-Job-Attributes 2839 operation (see [RFC2911] section 3.3.4). The only differences are 2840 that the operation is directed at a Subscription Object rather than a 2841 Job object, and the returned attribute group contains Subscription 2842 Object attributes rather than Job object attributes. 2844 Access Rights: The authenticated user (see [RFC2911] section 8.3) 2845 performing this operation MUST (1) be the Subscription Object owner, 2846 (2) have Operator or Administrator access rights for this Printer 2847 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by 2848 the Printer's administrator-configured security policy to query the 2849 Subscription Object for the target job. Otherwise the Printer MUST 2850 reject the operation and return: the 'client-error-forbidden', 2851 'client-error-not-authenticated', or 'client-error-not-authorized' 2852 status code as appropriate. Furthermore, the Printer's security 2853 policy MAY limit which attributes are returned, in a manner similar 2854 to the Get-Job-Attributes operation (see [RFC2911] end of section 2855 3.3.4.2). 2857 11.2.4.1 Get-Subscription-Attributes Request 2859 The following groups of attributes are part of the Get-Subscription- 2860 Attributes request: 2862 Group 1: Operation Attributes 2864 Natural Language and Character Set: 2865 The "attributes-charset" and "attributes-natural-language" 2866 attributes as described in section [RFC2911] 3.1.4.1. 2868 Target: 2869 The "printer-uri" attribute which defines the target for this 2870 operation as described in [RFC2911] section 3.1.5. 2872 Requesting User Name: 2873 The "requesting-user-name" attribute SHOULD be supplied by the 2874 client as described in [RFC2911] section 8.3. 2876 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)) 2878 The client MUST supply this attribute. The Printer MUST 2879 support this attribute. This attribute specifies the 2880 Subscription Object from which the client is requesting 2881 attributes. If the client omits this attribute, the Printer 2882 MUST reject this request with the 'client-error-bad-request' 2883 status code. 2885 11.2.4.1.2 "requested-attributes" (1setOf keyword) 2887 The client OPTIONALLY supplies this attribute. The Printer 2888 MUST support this attribute. This attribute specifies the 2889 attributes of the specified Subscription Object that the 2890 Printer MUST return in the response. Each value of this 2891 attribute is either an attribute name (defined in sections 5.3 2892 and 5.4) or an attribute group name. The attribute group names 2893 are: 2895 - 'subscription-template': all attributes that are both 2896 defined in section 5.3 and present on the specified 2897 Subscription Object (column 1 of Table 1). 2898 - 'subscription-description': all attributes that are both 2899 defined in section 5.4 and present on the specified 2900 Subscription Object (Table 2). 2902 - 'all': all attributes that are present on the specified 2903 Subscription Object. 2905 A Printer MUST support all these group names. 2907 If the client omits this attribute, the Printer MUST respond as 2908 if this attribute had been supplied with a value of 'all'. 2910 11.2.4.2 Get-Subscription-Attributes Response 2912 The Printer returns the following sets of attributes as part of the 2913 Get-Subscription-Attributes Response: 2915 Group 1: Operation Attributes 2917 Status Message: 2918 Same as [RFC2911]. 2920 Natural Language and Character Set: 2921 The "attributes-charset" and "attributes-natural-language" 2922 attributes as described in [RFC2911] section 3.1.4.2. The 2923 "attributes-natural-language" MAY be the natural language of 2924 the Subscription Object, rather than the one requested. 2926 Group 2: Unsupported Attributes 2928 See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on 2929 returning Unsupported Attributes. 2931 The response NEED NOT contain the "requested-attributes" 2932 operation attribute with any supplied keyword values that were 2933 requested by the client but are not supported by the IPP 2934 object. If the Printer object does return unsupported 2935 attributes referenced in the "requested-attributes" operation 2936 attribute, the values of the "requested-attributes" attribute 2937 returned MUST include only the unsupported keywords that were 2938 requested by the client. If the client had requested a group 2939 name, such as 'all', the resulting unsupported attributes 2940 returned MUST NOT include attribute keyword names described in 2941 the standard but not supported by the implementation. 2943 Group 3: Subscription Attributes 2945 This group contains a set of attributes with their current 2946 values. Each attribute returned in this group: 2948 a) MUST be specified by the "requested-attributes" attribute 2949 in the request, AND 2951 b) MUST be present on the specified Subscription Object AND 2953 c) MUST NOT be restricted by the security policy in force. 2954 For example, a Printer MAY prohibit a client who is not the 2955 creator of a Subscription Object from seeing some or all of 2956 its attributes. See [RFC2911] end of section 3.3.4.2 and 2957 section 8. 2959 The Printer can return the attributes of the Subscription 2960 Object in any order. The client MUST accept the attributes in 2961 any order. 2963 11.2.5 Get-Subscriptions operation 2965 This operation allows a client to retrieve the values of attributes 2966 of all Subscription Objects belonging to a Job or Printer. 2968 A Printer MUST supported this operation. 2970 This operation is similar to the Get-Subscription-Attributes 2971 operation, except that this Get-Subscriptions operation returns 2972 attributes from possibly more than one object. 2974 This operation is similar to the Get-Jobs operation (see [RFC2911] 2975 section 3.2.6), except that the operation returns Subscription 2976 Objects rather than Job objects. 2978 Access Rights: To query Per-Job Subscription Objects of the 2979 specified job (client supplied the "notify-job-id" operation 2980 attribute - see section 11.2.5.1.1), the authenticated user (see 2981 [RFC2911] section 8.3) performing this operation MUST (1) be the 2982 Subscription Object owner, (2) have Operator or Administrator access 2983 rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be 2984 otherwise authorized by the Printer's administrator-configured 2985 security policy to query the Subscription Object for the target job. 2986 To query Per-Printer Subscription Objects of the Printer (client 2987 omits the "notify-job-id" operation attribute - see section 2988 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) 2989 performing this operation MUST (1) have Operator or Administrator 2990 access rights for this Printer (see [RFC2911] sections 1 and 8.5), or 2991 (2) be otherwise authorized by the Printer's administrator-configured 2992 security policy to query Per-Printer Subscription Objects for the 2993 target Printer. Otherwise the Printer MUST reject the operation and 2994 return: the 'client-error-forbidden', 'client-error-not- 2995 authenticated', or 'client-error-not-authorized' status code as 2996 appropriate. Furthermore, the Printer's security policy MAY limit 2997 which attributes are returned, in a manner similar to the Get-Jobs 2998 and Get-Printer-Attributes operations (see [RFC2911] end of sections 2999 3.2.6.2 and 3.2.5.2). 3001 11.2.5.1 Get-Subscriptions Request 3003 The following groups of attributes are part of the Get-Subscriptions 3004 request: 3006 Group 1: Operation Attributes 3008 Natural Language and Character Set: 3009 The "attributes-charset" and "attributes-natural-language" 3010 attributes as described in [RFC2911] section 3.1.4.1. 3012 Target: 3013 The "printer-uri" attribute which defines the target for this 3014 operation as described in [RFC2911] section 3.1.5. 3016 Requesting User Name: 3017 The "requesting-user-name" attribute SHOULD be supplied by the 3018 client as described in [RFC2911] section 8.3. 3020 11.2.5.1.1 "notify-job-id" (integer(1:MAX)) 3022 If the client specifies this attribute, the Printer returns the 3023 specified attributes of all Per-Job Subscription Objects 3024 associated with the Job whose "job-id" attribute value equals 3025 the value of this attribute. If the client does not specify 3026 this attribute, the Printer returns the specified attributes of 3027 all Per-Printer Subscription Objects. Note: there is no way to 3028 get all Per-Job Subscriptions known to the Printer in a single 3029 operation. A Get-Jobs operation followed by a Get- 3030 Subscriptions operation for each Job will return all Per-Job 3031 Subscriptions. 3033 11.2.5.1.2 "limit" (integer(1:MAX)) 3035 The client OPTIONALLY supplies this attribute. The Printer 3036 MUST support this attribute. It is an integer value that 3037 determines the maximum number of Subscription Objects that a 3038 client will receive from the Printer even if the "my- 3039 subscriptions" attribute constrains which Subscription Objects 3040 are returned. The limit is a "stateless limit" in that if the 3041 value supplied by the client is 'N', then only the first 'N' 3042 Subscription Objects are returned in the Get-Subscriptions 3043 Response. There is no mechanism to allow for the next 'M' 3044 Subscription Objects after the first 'N' Subscription Objects. 3046 If the client does not supply this attribute, the Printer 3047 responds with all applicable Subscription Objects. 3049 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword) 3051 The client OPTIONALLY supplies this attribute. The Printer 3052 MUST support this attribute. This attribute specifies the 3053 attributes of the specified Subscription Objects that the 3054 Printer MUST return in the response. Each value of this 3055 attribute is either an attribute name (defined in sections 5.3 3056 and 5.4) or an attribute group name (defined in section 3057 11.2.4.1). If the client omits this attribute, the Printer 3058 MUST respond as if the client had supplied this attribute with 3059 the one value: 'notify-subscription-id'. 3061 11.2.5.1.4 "my-subscriptions" (boolean) 3063 The client OPTIONALLY supplies this attribute. The Printer 3064 MUST support this attribute. If the value is 'false', the 3065 Printer MUST consider the Subscription Objects from all users 3066 as candidates. If the value is 'true', the Printer MUST return 3067 the Subscription Objects created by the requesting user of this 3068 request. If the client does not supply this attribute, the 3069 Printer MUST respond as if the client had supplied the 3070 attribute with a value of 'false'. The means for 3071 authenticating the requesting user and matching the 3072 Subscription Objects is similar to that for Jobs which is 3073 described in [RFC2911] section 8. 3075 11.2.5.2 Get-Subscriptions Response 3077 The Printer returns the following sets of attributes as part of the 3078 Get-Subscriptions Response: 3080 Group 1: Operation Attributes 3082 Status Message: 3083 Same as [RFC2911]. 3085 Natural Language and Character Set: 3086 The "attributes-charset" and "attributes-natural-language" 3087 attributes as described in [RFC2911] section 3.1.4.2. 3089 Group 2: Unsupported Attributes 3091 Same as for Get-Subscription-Attributes. 3093 Groups 3 to N: Subscription Attributes 3094 The Printer responds with one Subscription Attributes Group for 3095 each requested Subscription Object (see the "notify-job-id" 3096 attribute in the Operation Attributes Group of this operation). 3098 The Printer returns Subscription Objects in any order. 3100 If the "limit" attribute is present in the Operation Attributes 3101 group of the request, the number of Subscription Attributes 3102 Groups in the response MUST NOT exceed the value of the "limit" 3103 attribute. 3105 It there are no Subscription Objects associated with the 3106 specified Job or Printer, the Printer MUST return zero 3107 Subscription Attributes Groups and it MUST NOT treat this case 3108 as an error, i.e., the status-code MUST be 'successful-ok' 3109 unless something else causes the status code to have some other 3110 value. 3112 See the Group 3 response (Subscription Attributes Group) of the 3113 Get-Subscription-Attributes operation (section 11.2.4.2) for 3114 the attributes that a Printer returns in this group. 3116 11.2.6 Renew-Subscription operation 3118 This operation allows a client to request the Printer to extend the 3119 lease on a Per-Printer Subscription Object. 3121 The Printer MUST support this operation. 3123 The Printer MUST accept this request for a Per-Printer Subscription 3124 Object in any of the target Printer's states, i.e., 'idle', 3125 'processing', or 'stopped', but MUST NOT change the Printer's 3126 "printer-state" attribute. 3128 The Printer MUST reject this request for a Per-Job Subscription 3129 Object because it has no lease (see section 5.4.3). The status code 3130 returned MUST be 'client-error-not-possible'. 3132 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3133 performing this operation MUST (1) be the owner of the Per-Printer 3134 Subscription Object, (2) have Operator or Administrator access rights 3135 for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3136 otherwise authorized by the Printer's administrator-configured 3137 security policy to renew Per-Printer Subscription Objects for the 3138 target Printer. Otherwise, the Printer MUST reject the operation and 3139 return: the 'client-error-forbidden', 'client-error-not- 3140 authenticated', or 'client-error-not-authorized' status code as 3141 appropriate. 3143 11.2.6.1 Renew-Subscription Request 3145 The following groups of attributes are part of the Renew-Subscription 3146 Request: 3148 Group 1: Operation Attributes 3150 Natural Language and Character Set: 3151 The "attributes-charset" and "attributes-natural-language" 3152 attributes as described in [RFC2911] section 3.1.4.1. 3154 Target: 3155 The "printer-uri" attribute which defines the target for this 3156 operation as described in [RFC2911] section 3.1.5. 3158 Requesting User Name: 3159 The "requesting-user-name" (name(MAX)) attribute SHOULD be 3160 supplied by the client as described in [RFC2911] section 8.3. 3162 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)) 3164 The client MUST supply this attribute. The Printer MUST 3165 support this attribute. This attribute specifies the Per- 3166 Printer Subscription Object whose lease the Printer MUST renew. 3167 If the client omits this attribute, the Printer MUST reject 3168 this request with the 'client-error-bad-request' status code. 3170 Group 2: Subscription Template Attributes 3172 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX)) 3174 The client MAY supply this attribute. It indicates the number 3175 of seconds to renew the lease for the specified Subscription 3176 Object. A value of 0 requests an infinite lease (which MAY 3177 require Operator access rights). If the client omits this 3178 attribute, the Printer MUST use the value of the Printer's 3179 "notify-lease-duration-default" attribute. See section 5.3.8 3180 for more details. 3182 11.2.6.2 Renew-Subscription Response 3184 The Printer returns the following sets of attributes as part of the 3185 Renew-Subscription Response: 3187 Group 1: Operation Attributes 3188 Status Message: 3189 Same as [RFC2911]. 3191 The following are some of the status codes returned (see 3192 [RFC2911]: 3194 successful-ok: The operation successfully renewed the lease 3195 on the Subscription Object for the requested duration. 3196 successful-ok-ignored-or-substituted-attributes: The 3197 operation successfully renewed the lease on the 3198 Subscription Object for some duration other than the 3199 amount requested. 3200 client-error-not-possible: The operation failed because the 3201 "notify-subscription-id" Operation attribute identified a 3202 Per-Job Subscription Object. 3203 client-error-not-found: The operation failed because the 3204 "notify-subscription-id" Operation attribute identified a 3205 non-existent Subscription Object. 3207 Natural Language and Character Set: 3208 The "attributes-charset" and "attributes-natural-language" 3209 attributes as described in [RFC2911] section 3.1.4.2. The 3210 "attributes-natural-language" MAY be the natural language of 3211 the Subscription Object, rather than the one requested. 3213 Group 2: Unsupported Attributes 3215 See [RFC2911] section 3.1.7 for details on returning 3216 Unsupported Attributes. 3218 Group 3: Subscription Attributes 3220 The Printer MUST return the following Subscription Attribute: 3222 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX)) 3224 The value of this attribute MUST be the number of seconds that 3225 the Printer has granted for the lease of the Subscription 3226 Object (see section 5.3.8 for details, such as the value of 3227 this attribute when the Printer doesn't support the requested 3228 value). 3230 11.2.7 Cancel-Subscription operation 3232 This operation allows a client to delete a Subscription Object and 3233 stop the Printer from delivering more Event Notifications. Once 3234 performed, there is no way to reference the Subscription Object. 3236 A Printer MUST supported this operation. 3238 The Printer MUST accept this request in any of the target Printer's 3239 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 3240 the Printer's "printer-state" attribute. 3242 If the specified Subscription Object is a Per-Job Subscription 3243 Object, the Printer MUST accept this request in any of the target 3244 Job's states, but MUST NOT change the Job's "job-state" attribute or 3245 affect the Job. 3247 Note: There is no way to change any attributes on a Subscription 3248 Object, except the "notify-lease-duration" attribute (using the 3249 Renew-Subscription operation). In order to change other attributes, 3250 a client performs a Subscription Creation Operation and Cancel- 3251 Subscription operation on the old Subscription Object. If the client 3252 wants to avoid missing Event Notifications, it performs the 3253 Subscription Creation Operation first. If this order would create 3254 too many Subscription Objects on the Printer, the client reverses the 3255 order. 3257 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3258 performing this operation MUST (1) be the owner of the Subscription 3259 Object, (2) have Operator or Administrator access rights for the 3260 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 3261 authorized by the Printer's administrator-configured security policy 3262 to cancel the target Subscription Object. Otherwise, the Printer 3263 MUST reject the operation and return: the 'client-error-forbidden', 3264 'client-error-not-authenticated', or 'client-error-not-authorized' 3265 status code as appropriate. 3267 11.2.7.1 Cancel-Subscription Request 3269 The following groups of attributes are part of the Cancel- 3270 Subscription Request: 3272 Group 1: Operation Attributes 3274 Natural Language and Character Set: 3275 The "attributes-charset" and "attributes-natural-language" 3276 attributes as described in [RFC2911] section 3.1.4.1. 3278 Target: 3279 The "printer-uri" attribute which defines the target for this 3280 operation as described in [RFC2911] section 3.1.5. 3282 Requesting User Name: 3283 The "requesting-user-name" attribute SHOULD be supplied by the 3284 client as described in [RFC2911] section 8.3. 3286 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)) 3288 The client MUST supply this attribute. The Printer MUST 3289 support this attribute. This attribute specifies the 3290 Subscription Object that the Printer MUST cancel. If the 3291 client omits this attribute, the Printer MUST reject this 3292 request with the 'client-error-bad-request' status code. 3294 11.2.7.2 Cancel-Subscription Response 3296 The Printer returns the following sets of attributes as part of the 3297 Cancel-Subscription Response: 3299 Group 1: Operation Attributes 3301 Status Message: 3302 Same as [RFC2911]. 3304 The following are some of the status codes returned (see 3305 [RFC2911]: 3307 successful-ok: The operation successfully canceled 3308 (deleted) the Subscription Object. 3309 client-error-not-found: The operation failed because the 3310 "notify-subscription-id" Operation attribute identified a 3311 non-existent Subscription Object. 3313 Natural Language and Character Set: 3314 The "attributes-charset" and "attributes-natural-language" 3315 attributes as described in [RFC2911] section 3.1.4.2. The 3316 "attributes-natural-language" MAY be the natural language of 3317 the Subscription Object, rather than the one requested. 3319 Group 2: Unsupported Attributes 3321 See [RFC2911] section 3.1.7 for details on returning 3322 Unsupported Attributes. 3324 12 Status Codes 3326 The following status codes are defined as extensions for Notification 3327 and are returned as the value of the "status-code" parameter in the 3328 Operation Attributes Group of a response (see [RFC2911] section 3329 3.1.6.1). Operations in this document can also return the status 3330 codes defined in section 13 of [RFC2911]. The 'successful-ok' status 3331 code is an example of such a status code. 3333 12.1 successful-ok-ignored-subscriptions (0x0003) 3335 The Subscription Creation Operation was unable to create all 3336 requested Subscription Objects. 3338 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3339 operation, this status code means that the Printer created one or 3340 more Subscription Objects, but not all requested Subscription 3341 Objects. 3343 For a Job Creation operation, this status code means that the Printer 3344 created the Job along with zero or more Subscription Objects. The 3345 Printer returns this status code even if other job attributes are 3346 unsupported or in conflict. That is, if an IPP Printer finds a 3347 warning that would allow it to return 'successful-ok-ignored- 3348 subscriptions' and either 'successful-ok-ignored-or-substituted- 3349 attributes' and/or 'successful-ok-conflicting-attributes', it MUST 3350 return 'successful-ok-ignored-subscriptions'. 3352 12.2 client-error-ignored-all-subscriptions (0x0414) 3354 This status code is the same as 'successful-ok-ignored-subscriptions' 3355 except that only the Create-Job-Subscriptions and Create-Printer- 3356 Subscriptions operation return it. They return this status code only 3357 when the Printer creates zero Subscription Objects. 3359 13 Status Codes in Subscription Attributes Groups 3361 This section contains values of the "notify-status-code" (type2 enum) 3362 attribute that the Printer returns in a Subscription Attributes Group 3363 in a response when the corresponding Subscription Object: 3365 1. is not created or 3367 2. is created and some of the client-supplied attributes are not 3368 supported. 3370 The following sections are ordered in decreasing order of importance 3371 of the status-codes. 3373 13.1 client-error-uri-scheme-not-supported (0x040C) 3375 This status code is defined in [RFC2911]. This document extends its 3376 meaning and allows it to be in a Subscription Attributes Group of a 3377 response. 3379 The scheme of the client-supplied URI in a "notify-recipient-uri" 3380 Subscription Template Attribute in a Subscription Creation Operation 3381 is not supported. See section 5.3.1. 3383 13.2 client-error-attributes-or-values-not-supported (0x040B) 3385 This status code is defined in [RFC2911]. This document extends its 3386 meaning and allows it to be in a Subscription Attributes Group of a 3387 response. 3389 The method of the client-supplied keyword in a "notify-pull-method" 3390 Subscription Template Attribute in a Subscription Creation Operation 3391 is not supported. See section 5.3.2. 3393 13.3 client-error-too-many-subscriptions (0x0415) 3395 The number of Subscription Objects supported by the Printer would be 3396 exceeded if this Subscription Object were created (see section 5.2). 3398 13.4 successful-ok-too-many-events (0x0005) 3400 The client supplied more Events in the "notify-events" operation 3401 attribute of a Subscription Creation Operation than the Printer 3402 supports, as indicated in its "notify-max-events-supported" Printer 3403 attribute (see section 5.3.3). 3405 13.5 successful-ok-ignored-or-substituted-attributes (0x0001) 3407 This status code is defined in [RFC2911]. This document extends its 3408 meaning to include unsupported Subscription Template Attributes and 3409 it can appear in a Subscription Attributes Group. 3411 14 Encodings of Additional Attribute Tags 3413 This section assigns values to two attributes tags as extensions to 3414 the encoding defined in [RFC2910]). 3416 The "subscription-attributes-tag" delimits Subscription Template 3417 Attributes Groups in requests and Subscription Attributes Groups in 3418 responses. 3420 The "event-notification-attributes-tag" delimits Event Notifications 3421 in Delivery Methods that use an IPP-like encoding. 3423 The following table specifies the values for the delimiter tags: 3425 Tag Value (Hex) Meaning 3427 0x06 "subscription-attributes-tag" 3428 0x07 "event-notification-attributes-tag" 3430 15 Conformance Requirements 3432 It is OPTIONAL for IPP clients and Printers to implement this Event 3433 Notification specification. 3435 15.1 Conformance requirements for clients 3437 If this Event Notification specification is implemented by a client, 3438 the client MUST support the 'ippget' Pull Delivery Method and meet 3439 the conformance requirements as defined in [ipp-get-method] for 3440 clients. A client MAY support additional Delivery Methods. 3442 15.2 Conformance requirements for Printers 3444 If this Event Notification specification is implemented by a Printer, 3445 the Printer MUST: 3447 - meet the Conformance Requirements detailed in section 5 of 3448 [RFC2911]. 3450 - support the Subscription Template Attributes Group in requests 3451 and the Subscription Attributes Group in responses. 3453 - support all of the following attributes: 3455 a. REQUIRED Subscription Object attributes in section 5. 3456 b. REQUIRED Printer Description object attributes in section 6. 3457 c. REQUIRED attributes in Event Notification content in section 3458 8. 3460 - support the 'ippget' Pull Delivery Method and meet the 3461 conformance requirements as defined in [ipp-get-method] for 3462 Printers. The Printer MAY support additional Push and Pull 3463 Delivery Methods. 3465 - deliver Event Notifications that conform to the requirements of 3466 section 9 and the requirements of the Delivery Method Document 3467 for each supported Delivery Method (the conformance 3468 requirements for Delivery Method Documents is specified in 3469 section 10). 3471 - for all of the Job Creation Operations that the Printer 3472 supports, MUST support the REQUIRED extensions for notification 3473 defined in section 11.1.3. 3475 - meet the conformance requirements for operations as described 3476 in Table 16 and meet the requirements for Printers as specified 3477 in the indicated sub-sections of section 11: 3479 Table 16 - Printer Conformance Requirements for Operations 3480 Operation Printer 3481 Conformance 3482 Requirements 3484 Create-Printer-Subscriptions (section 11.1.2) REQUIRED 3485 Create-Job-Subscriptions (section 11.1.1) OPTIONAL 3486 Get-Subscription-Attributes (section 11.2.3) REQUIRED 3487 Get-Subscriptions (section 11.2.5) REQUIRED 3488 Renew-Subscription (section 11.2.6) REQUIRED 3489 Cancel-Subscription (section 11.2.7) REQUIRED 3491 16 Model for Notification with Cascading Printers (Informative) 3493 With this model (see Figure 2 below), there is an intervening Print 3494 server between the human user and the output-device. So the system 3495 effectively has two Printer objects. There are two cases to 3496 consider. 3498 1. When the Printer 1 (in the server) generates Events, the system 3499 behaves like the client and Printer in Figure 1. In this case, 3500 Printer 1 delivers Event Notifications that are shown as Event 3501 Notifications (A) of Figure 2. 3503 2. When the Printer 2 (in the output-device) generates Events, there 3504 are two possible system configurations: 3506 a) Printer 1 forwards the client-supplied Subscription Creation 3507 Operations to the downstream Printer 2 and lets Printer 2 3508 deliver the Event Notifications directly to the Notification 3509 Recipients supplied by the Client (Event Notifications(C) in the 3510 diagram). 3512 b) Printer 1 performs the client-supplied Subscription Creation 3513 Operations and also forwards the Subscription Creation 3514 Operations to Printer 2 with the Notification Recipient changed 3515 to be the Printer 1. When an Event occurs in Printer 2, Printer 3516 2 delivers the Event Notification (B) to Notification Recipient 3517 of Printer 1, which relays the received Event Notification (B) 3518 to the client-supplied Notification Recipient (as Event 3519 Notifications(A) in the diagram). Note, when a client performs 3520 a Subscription Creation Operation, Printer 1 need not forward 3521 the Subscription Creation Operation to Printer 2 if it would 3522 create a duplicate Subscription Object on Printer 2. 3524 Note: when Printer 1 is forwarding Subscription Creation Operations 3525 to Printer 2, it may request Printer 2 to create additional 3526 Subscription Objects (called "piggy-backing"). Piggy-backing is 3527 useful when: 3529 - Device A is configured to accept (IPP or non-IPP) requests from 3530 other servers. 3532 - Server S wants to receive Job Events that the client didn't 3533 request and Server S wants these Events for jobs it submits and 3534 not for other jobs. 3536 server S device A 3537 +------------+ +------------+ 3538 | | | | 3539 +--------+ Subscription | ###########| | ###########| 3540 | client |--Creation ----># Printer #| Subscription | # Printer #| 3541 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 3542 | ###|#######| Operation | ####|#|####| 3543 +----|---^---+ +-----|-|----+ 3544 +--------+ Event | | | | 3545 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 3546 |ation Re|<-------------Event Notifications(C)-----------------+ 3547 |cipient | 3548 +--------+ 3549 Figure 2 - Model for Notification with Cascading Printers 3551 17 Distributed Model for Notification (Informative) 3553 A Printer implementation could use some other remote notification 3554 server to provide some or most of the service. For example, the 3555 remote notification server could deliver Event Notifications using 3556 Delivery Methods that are not directly supported by the output device 3557 or Printer object. Or, the remote notification server could store 3558 Subscription Objects (passed to it from the output device in response 3559 to Subscription Creation requests), accept Events, format the Event 3560 Notification in the natural language of the Notification Recipient, 3561 and deliver the Event Notifications to the Notification Recipient(s). 3563 Figure 3 shows this partitioning. The interface between the output 3564 device (or Printer object) and the remote notification server is 3565 outside the scope of this document and is intended to be transparent 3566 to the client and this document. 3568 *********************** 3569 * 3570 * Printer in combination 3571 * with the distributed 3572 * Notification Server) 3573 * 3574 * output device or server 3575 * +---------------+ 3576 PDA, desktop, or server * + ########### + 3577 +--------+ * | # # | 3578 | client |---IPP Subscription--------># Printer # | 3579 +--------+ Creation operation * | # Object # | 3580 * | #####|##### | 3581 * +-------|-------+ 3582 * | Subscriptions 3583 * | OR Event 3584 +------------+ * | Notifications 3585 |Notification| IPP-defined * +------v--------+ 3586 |Recipient |<--Event Notifications---| Notification | 3587 +------------+ * | Server | 3588 * +---------------+ 3589 * 3590 ************************* 3591 *** = Implementation configuration opaque boundary 3593 Figure 3 - Opaque Use of a Notification Server Transparent to the 3594 Client 3596 18 Extended Notification Recipient (Informative) 3598 The model allows for an extended Notification Recipient that is 3599 itself a notification server that forwards each Event Notification to 3600 another recipient (called the Ultimate Notification Recipient in this 3601 section). The Delivery Method to the Ultimate Recipient is probably 3602 different from the Delivery Method used by the Printer to the 3603 extended Notification Recipient. 3605 This extended Notification Recipient is transparent to the Printer 3606 but not to the client. 3608 When a client performs a Subscription Creation Operation, it 3609 specifies the extended Notification Recipient as it would any 3610 Notification Recipient. In addition, the client specifies the 3611 Ultimate Notification Recipient in the Subscription Creation 3612 Operation in a manner specified by the extended Notification 3613 Recipient. Typically, it is either some bytes in the value of 3614 "notify-user-data" or some additional parameter in the value of 3615 "notify-recipient-uri". The client also subscribes directly with the 3616 extended Notification Recipient (by means outside this document), 3617 since it is a notification server in its own right. 3619 The IPP Printer treats the extended Notification Recipient like any 3620 other Notification Recipient and the IPP Printer is not aware of the 3621 forwarding. The Delivery Method that the extended Notification 3622 Recipient uses for delivering the Event Notification to the Ultimate 3623 Notification Recipient is beyond the scope of this document and is 3624 transparent to the IPP Printer. 3626 Examples of this extended Notification Recipient are paging, 3627 immediate messaging services, general notification services, and NOS 3628 vendors' infrastructure. Figure 4 shows this approach. 3630 PDA, desktop, or server server or output device 3631 +---------------+ 3632 +--------+ | ########### | 3633 | client |---Subscription Creation -----------># Printer # | 3634 +--------+ Operation | # Object # | 3635 | #####|##### | 3636 +------------+ +------------+ IPP-defined +-------|-------+ 3637 |Ultimate | any |Notification|<--Event Notifications----+ 3638 |Notification|<----|Recipient | 3639 |Recipient | +------------+ 3640 +------------+ (Notification Server) 3641 Figure 4 - Use of an Extended Notification Recipient transparent to 3642 the Printer 3644 19 Object Model for Notification (Normative) 3646 This section describes the Notification object model that adds a 3647 Subscription Object which together with the Job and Printer object 3648 provide the complete Notification semantics. 3650 The object relationships can be seen pictorially as: 3652 Subscription Objects (Per-Printer Subscriptions) Printer object 3653 +----+ +------------+ 3654 | s1 |<--------------------------------------------->| | 3655 +----++ | | 3656 | s2 |<-------------------------------------------->| p1 | 3657 +----++ | | 3658 | s3 |<------------------------------------------->| | 3659 +----+ +------------+ 3660 Job objects 3661 +---------+ 3662 | | 3663 +----+ | j1 | 3664 | s4 |<------->| | 3665 +----+ | | 3666 | | s4 is a Per-Job Subscription Object 3667 ++--------++ 3668 | | 3669 +----+ | j2 | 3670 | s5 |<------>| | 3671 +----++ | | 3672 | s6 |<----->| | s5 and s6 are Per-Job Subscription 3673 +----+ ++--------++ Objects 3674 | | 3675 | j3 | 3676 | | 3677 | | <----> indicates association 3678 +---------+ 3679 Figure 5 - Object Model for Notification 3680 s1, s2, and s3 are Per-Printer Subscription Objects and can 3681 identify Printer and/or Job Events. 3682 s4, s5, and s6 are Per-Job Subscription Objects and can identify 3683 Printer and/or Job Events. 3685 19.1 Object relationships 3687 This sub-section defines the object relationships between the 3688 Printer, Job, and Subscription Objects by example. Whether Per- 3689 Printer Subscription Objects are actually contained in a Printer 3690 object or are just bi-directionally associated with them in some way 3691 is IMPLEMENTATION DEPENDENT and is transparent to the client. 3692 Similarly, whether Per-Job Subscription Objects are actually 3693 contained in a Job object or are just bi-directionally associated 3694 with them in some way is IMPLEMENTATION DEPENDENT and is transparent 3695 to the client. The object relationships are defined as follows: 3697 19.2 Printer Object and Per-Printer Subscription Objects 3699 1. The Printer object contains (is associated with) zero or more 3700 Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer 3701 Subscription Objects). 3703 2. Each Per-Printer Subscription Object (s1, s2, and s3) is 3704 contained in (or is associated with) exactly one Printer object 3705 (p1). 3707 19.3 Job Object and Per-Job Subscription Objects 3709 1. A Job object (j1, j2, j3) is associated with zero or more Per- 3710 Job Subscription Objects (s4-s6). Job j1 is associated with 3711 Per-Job Subscription Object s4, Job j2 is associated with Per- 3712 Job Subscription Objects s5 and s6, and Job j3 is not associated 3713 with any Per-Job Subscription Object. 3715 2. Each Per-Job Subscription Object is associated with exactly one 3716 Job object. 3718 20 Per-Job versus Per-Printer Subscription Objects (Normative) 3720 Per-Job and Per-Printer Subscription Objects are quite similar. 3721 Either type of Subscription Object can subscribe to Job Events, 3722 Printer Events, or both. Both types of Subscription Objects can be 3723 queried using the Get-Subscriptions and Get-Subscription-Attributes 3724 operations and canceled using the Cancel-Subscription operation. 3725 Both types of Subscription Objects create Subscription Objects which 3726 have the same Subscription Object attributes defined. However, there 3727 are some semantic differences between Per-Job Subscription Objects 3728 and Per-Printer Subscription Objects. A Per-Job Subscription Object 3729 is established by the client when submitting a job and after creating 3730 the job using the Create-Job-Subscriptions operation by specifying 3731 the "job-id" of the Job with the "notify-job-id" attribute. A Per- 3732 Printer Subscription Object is established between a client and a 3733 Printer using the Create-Printer-Subscriptions operation. Some 3734 specific differences are: 3736 1. A client usually creates one or more Per-Job Subscription 3737 Objects as part of the Job Creation operations (Create-Job, 3738 Print-Job, and Print-URI), rather than using the OPTIONAL 3739 Create-Job-Subscriptions operation, especially since Printer 3740 implementations NEED NOT support the Create-Job-Subscriptions 3741 operation, since it is OPTIONAL. 3743 2. For Per-Job Subscription Objects, the Subscription Object is 3744 only valid while the job is "not-complete" (see sections 5.4.3) 3745 while for the Per-Printer Subscription Objects, the Subscription 3746 Object is valid until the time (in seconds) that the Printer 3747 returned in the "notify-lease-expiration-time" operation 3748 attribute. 3750 3. Job Events in a Per-Job Subscription Object apply only to "one 3751 job" (the Job created by the Job Creation operation or 3752 references by the Create-Job-Subscriptions operation) while Job 3753 Events in a Per-Printer Subscription Object apply to ALL jobs 3754 contained in the IPP Printer. 3756 21 Normative References 3758 [ipp-get-method] 3759 Herriot, R., and T. Hastings, "Internet Printing Protocol (IPP): 3760 The 'ippget' Delivery Method for Event Notifications", , June 21, 2004. 3763 [RFC2119] 3764 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3765 Levels", RFC 2119 , March 1997 3767 [RFC2396] 3768 Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource 3769 Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 3771 [RFC2717] 3772 R. Petke and I. King, "Registration Procedures for URL Scheme 3773 Names", RFC 2717, November 1999. 3775 [RFC2910] 3776 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3777 Printing Protocol/1.1: Encoding and Transport", RFC 2910, September 3778 2000. 3780 [RFC2911] 3781 deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, 3782 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 3783 September 2000. 3785 [RFC3381] 3786 Hastings, T., Lewis, H., and R. Bergman, "IPP: Job Progress 3787 Attributes", RFC 3381, September 2002. 3789 22 Informative References 3791 [IANA-CON] 3792 Narte, T. and H. Alvestrand, "Guidelines for Writing an IANA 3793 Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 3795 [ipp-not-req] 3796 deBry, R., Lewis, H., and T. Hastings, "Internet Printing 3797 Protocol/1.1: Requirements for IPP Notifications", , June 21, 2004. 3800 [RFC2565] 3801 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3802 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 3803 1999. 3805 [RFC2566] 3806 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., and P. 3807 Powell, "Internet Printing Protocol/1.0: Model and Semantics", RFC 3808 2566, April 1999. 3810 [RFC2567] 3811 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3812 2567, April 1999. 3814 [RFC2568] 3815 Zilles, S., "Rationale for the Structure and Model and Protocol for 3816 the Internet Printing Protocol", RFC 2568, April 1999. 3818 [RFC2569] 3819 Herriot, R., Hastings, T., Jacobs, N., and J. Martin, "Mapping 3820 between LPD and IPP Protocols", RFC 2569, April 1999. 3822 [RFC2616] 3823 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 3824 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol - 3825 HTTP/1.1", RFC 2616, June 1999. 3827 [RFC3196] 3828 Hastings, T., Manros, C., Zehler, P., Kugler, C., and H. Holst, 3829 "Internet Printing Protocol/1.1: Implementer's Guide", RFC3196, 3830 November 2001. 3832 23 IANA Considerations 3834 This section contains the registration information for IANA to add to 3835 the IPP Registry according to the procedures defined in RFC 2911 3836 [RFC2911] section 6 to cover the definitions in this document. In 3837 addition, this section defines how Events and Delivery Methods will 3838 be registered when they are defined in other documents. The 3839 resulting registrations will be published in the 3840 http://www.iana.org/assignments/ipp-registrations registry. 3842 Note to RFC Editors: Replace RFC NNNN below (but not RFC xxxx) 3843 with the RFC number for this document, so that it accurately 3844 reflects the content of the information for the IANA Registry. 3846 23.1 Attribute Registrations 3848 The following table lists all the attributes defined in this 3849 document. These are to be registered according to the procedures in 3850 RFC 2911 [RFC2911] section 6.2. 3852 Subscription Template attributes: Reference Section 3853 --------------------------------- --------- ------- 3854 notify-attributes (1setOf type2 keyword) [RFCNNNN] 5.3.4 3855 notify-attributes-supported (1setOf type2 keyword) 3856 [RFCNNNN] 5.3.4.1 3857 notify-charset (charset) [RFCNNNN] 5.3.6 3858 notify-events (1setOf type2 keyword) [RFCNNNN] 5.3.3 3859 notify-events-default (1setOf type2 keyword) [RFCNNNN] 5.3.3.1 3860 notify-events-supported (1setOf type2 keyword) [RFCNNNN] 5.3.3.2 3861 notify-lease-duration (integer(0:67108863)) [RFCNNNN] 5.3.8 3862 notify-lease-duration-default (integer(0:67108863)) 3863 [RFCNNNN] 5.3.8.1 3864 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 3865 rangeOfInteger(0:67108863))) [RFCNNNN] 5.3.8.2 3866 notify-max-events-supported (integer(2:MAX)) [RFCNNNN] 5.3.3.3 3867 notify-natural-language (naturalLanguage) [RFCNNNN] 5.3.7 3868 notify-pull-method (type2 keyword) [RFCNNNN] 5.3.2 3869 notify-pull-method-supported (1setOf type2 keyword) 3870 [RFCNNNN] 5.3.2.1 3871 notify-recipient-uri (uri) [RFCNNNN] 5.3.1 3872 notify-schemes-supported (1setOf uriScheme) [RFCNNNN] 5.3.1.1 3873 notify-time-interval (integer(0:MAX)) [RFCNNNN] 5.3.9 3874 notify-user-data (octetString(63)) [RFCNNNN] 5.3.5 3876 Subscription Description Attributes: 3877 notify-job-id (integer(1:MAX))) [RFCNNNN] 5.4.6 3878 notify-lease-expiration-time (integer(0:MAX))) [RFCNNNN] 5.4.3 3879 notify-printer-up-time (integer(1:MAX))) [RFCNNNN] 5.4.4 3880 notify-printer-uri (uri)) [RFCNNNN] 5.4.5 3881 notify-sequence-number (integer (0:MAX))) [RFCNNNN] 5.4.2 3882 notify-subscriber-user-name (name(MAX))) [RFCNNNN] 5.4.7 3883 notify-subscription-id (integer (1:MAX))) [RFCNNNN] 5.4.1 3884 Printer Description Attributes: 3885 printer-state-change-date-time (dateTime)) [RFCNNNN] 6.2 3886 printer-state-change-time (integer(1:MAX))) [RFCNNNN] 6.1 3888 Attributes Only in Event Notifications 3889 notify-subscribed-event (type2 keyword) [RFCNNNN] 8.1 3890 notify-text (text(MAX)) [RFCNNNN] 8.2 3892 23.2 Additional Enum Attribute Value Registrations within the IPP 3893 registry 3895 The following table lists all the new enum attribute values defined 3896 in this document. These are to be registered within the IPP registry 3897 according to the procedures in RFC 2911 [RFC2911] section 6.1. 3899 Attribute 3900 Value Name Reference Section 3901 ------ ----------------------------- --------- ------- 3902 operations-supported (type2 enum) [RFC2911] 4.4.15 3903 0x0016 Create-Printer-Subscriptions [RFCNNNN] 7.1 3904 0x0017 Create-Job-Subscriptions [RFCNNNN] 7.1 3905 0x0018 Get-Subscription-Attributes [RFCNNNN] 7.1 3906 0x0019 Get-Subscriptions [RFCNNNN] 7.1 3907 0x001A Renew-Subscription [RFCNNNN] 7.1 3908 0x001B Cancel-Subscription [RFCNNNN] 7.1 3910 23.3 Operation Registrations 3912 The following table lists all of the operations defined in this 3913 document. These are to be registered according to the procedures in 3914 RFC 2911 [RFC2911] section 6.4. 3916 Operation Name Reference Section 3917 --------------------------------- --------- ------- 3918 Cancel-Subscription [RFCNNNN] 11.2.7 3919 Create-Job - Extensions [RFCNNNN] 11.1.3 3920 Create-Job-Subscriptions [RFCNNNN] 11.1.1 3921 Create-Printer-Subscriptions [RFCNNNN] 11.1.2 3922 Get-Printer-Attributes - Extensions [RFCNNNN] 11.2.3 3923 Get-Subscription-Attributes [RFCNNNN] 11.2.4 3924 Get-Subscriptions [RFCNNNN] 11.2.5 3925 Print-Job - Extensions [RFCNNNN] 11.1.3 3926 Print-URI - Extensions [RFCNNNN] 11.1.3 3927 Renew-Subscription [RFCNNNN] 11.2.6 3928 Validate-Job Operation - Extensions [RFCNNNN] 11.2.2 3930 23.4 Status code Registrations 3932 The following table lists all the status codes defined in this 3933 document. These are to be registered according to the procedures in 3934 RFC 2911 [RFC2911] section 6.6. 3936 Value Status Code Name Reference Section 3937 ----- ---------------------------- --------- ------- 3938 0x0000:0x00FF - Successful: 3939 0x0003 successful-ok-ignored-subscriptions [RFCNNNN] 12.1 3941 0x0400:0x04FF - Client Error: 3942 0x0414 client-error-ignored-all-subscriptions [RFCNNNN] 12.2 3944 23.5 Attribute Group tag Registrations 3946 The following table lists all the attribute group tags defined in 3947 this document. These are to be registered according to the 3948 procedures in RFC 2911 [RFC2911] section 6.5. 3950 Value Attribute Group Tag Name Reference Section 3951 ----- -------------------------------- -------- ------- 3952 0x06 subscription-attributes-tag [RFCNNNN] 14 3953 0x07 event-notification-attributes-tag [RFCNNNN] 14 3955 23.6 Registration of Events 3957 The following table lists all the Events defined in this document as 3958 type2 keywords to be used with the "notify-events", "notify-events- 3959 default", and "notify-events-supported" Subscription Template 3960 attributes (see section 5.3.3)). Rather than creating a separate 3961 section in the IPP Registry for Events, these event keywords will be 3962 registered according to the procedures of [RFC2911] section 7.1 as 3963 additional keyword attribute values for use with the "notify-events" 3964 Subscription Template attribute (see section 5.3.3), i.e., registered 3965 as keyword values for the "notify-events", "notify-events-default", 3966 and "notify-events-supported" attributes: 3968 Attribute (attribute syntax) 3969 Value Reference Section 3970 --------------------- --------- ------- 3971 notify-events (1setOf type2 keyword) [RFCNNNN] 5.3.3 3972 notify-events-default (1setOf type2 keyword) [RFCNNNN] 5.3.3.1 3973 notify-events-supported (1setOf type2 keyword) [RFCNNNN] 5.3.3.2 3974 notify-subscribed-event (type2 keyword) [RFCNNNN] 8.1 3975 No Events: 3976 none [RFCNNNN] 5.3.3.4.1 3977 Printer Events: 3978 printer-state-changed [RFCNNNN] 5.3.3.4.2 3979 printer-restarted [RFCNNNN] 5.3.3.4.2 3980 printer-shutdown [RFCNNNN] 5.3.3.4.2 3981 printer-stopped [RFCNNNN] 5.3.3.4.2 3982 printer-config-changed [RFCNNNN] 5.3.3.4.2 3983 printer-media-changed [RFCNNNN] 5.3.3.4.2 3984 printer-finishings-changed [RFCNNNN] 5.3.3.4.2 3985 printer-queue-order-changed [RFCNNNN] 5.3.3.4.2 3986 Job Events: 3987 job-state-changed [RFCNNNN] 5.3.3.4.3 3988 job-created [RFCNNNN] 5.3.3.4.3 3989 job-completed [RFCNNNN] 5.3.3.4.3 3990 job-stopped [RFCNNNN] 5.3.3.4.3 3991 job-config-changed [RFCNNNN] 5.3.3.4.3 3992 job-progress [RFCNNNN] 5.3.3.4.3 3994 23.7 Registration of Event Notification Delivery Methods 3996 This section describes the requirements and procedures for 3997 registration and publication of Event Notification Delivery Methods 3998 and for the submission of such proposals. 4000 23.7.1 Requirements for Registration of Event Notification Delivery 4001 Methods 4003 Registered IPP Event Notification Delivery Methods are expected to 4004 follow a number of requirements described below. 4006 23.7.1.1 Required Characteristics 4008 A Delivery Method Document MUST either (1) contain all of the 4009 semantics of the Delivery Method or (2) contain the IPP Delivery 4010 Method registration requirements and a profile of some other protocol 4011 that in combination is the Delivery Method (e.g., mailto). The 4012 Delivery Method Document (and any documents it requires) MUST define 4013 either (1) a URL for a Push Delivery Method that the meets the 4014 requirements of [RFC2717]. or (2) a keyword for a Pull Delivery 4015 method. 4017 IPP Event Notification Delivery Method Documents MUST meet the 4018 requirements of this document (see sections 9 and 10). 4020 In addition, a Delivery Method Document MUST contain the following 4021 information: 4023 Type of registration: IPP Event Notification Delivery Method 4024 Name of this delivery method: 4025 Proposed URL scheme name of this Push Delivery Method or the 4026 keyword name of this Pull Delivery Method: 4027 Name of proposer: 4028 Address of proposer: 4029 Email address of proposer: 4030 Is this delivery method REQUIRED or OPTIONAL for conformance to the 4031 IPP Event Notification and Subscriptions document: 4032 Is this delivery method defining Machine Consumable and/or Human 4033 Consumable content: 4035 23.7.1.2 Naming Requirements 4037 Exactly one (URL scheme or keyword) name MUST be assigned to each 4038 Delivery Method. 4040 Each assigned name MUST uniquely identify a single Delivery Method. 4041 All Push Delivery Method names MUST conform to the rules for URL 4042 scheme names, according to [RFC2396] and [RFC2717] for schemes in the 4043 IETF tree. All Pull Delivery Method names MUST conform to the rules 4044 for keywords according to [RFC2911]. 4046 23.7.1.3 Functionality Requirements 4048 Delivery Methods MUST function as a protocol that is capable of 4049 delivering (push or pull) IPP Event Notifications to Notification 4050 Recipients. 4052 23.7.1.4 Usage and Implementation Requirements 4054 Use of a large number of Delivery Methods may hamper 4055 interoperability. However, the use of a large number of undocumented 4056 and/or unlabelled Delivery Methods hampers interoperability even 4057 more. 4059 A Delivery Method should therefore be registered ONLY if it adds 4060 significant functionality that is valuable to a large community, OR 4061 if it documents existing practice in a large community. Note that 4062 Delivery Methods registered for the second reason should be 4063 explicitly marked as being of limited or specialized use and should 4064 only be used with prior bilateral agreement. 4066 23.7.1.5 Publication Requirements 4068 Delivery Method Documents MUST be published in a standards track, 4069 informational, or experimental RFCs. 4071 23.7.2 Registration Procedure 4073 The IPP WG is developing a small number of Delivery Methods which are 4074 intended to be published as standards track RFCs. However, some 4075 parties may wish to register additional Delivery Methods in the 4076 future. This section describes the procedures for these additional 4077 Delivery Methods. 4079 23.7.2.1 Present the proposal to the Community 4081 First the Delivery Method Document MUST be an Internet-Draft with a 4082 target category of standards track, informational, or experimental. 4083 The same MUST be true for any documents that it references. 4085 Deliver the proposed Delivery Method Document proposal to the 4086 "ipp@pwg.org" mailing list. This mailing list has been established 4087 by [RFC2911] for reviewing proposed registrations and discussing 4088 other IPP matters. Proposed Delivery Method Documents are not 4089 formally registered and MUST NOT be used until approved. 4091 The intent of the public posting is to solicit comments and feedback 4092 on the definition and suitability of the Delivery Method and the name 4093 chosen for it over a four week period. 4095 23.7.2.2 Delivery Method Reviewer 4097 The Delivery Method Reviewer is the same person who has been 4098 appointed by the IETF Application Area Director(s) as the IPP 4099 Designated Expert according to [RFC2911] and [IANA-CON]. When the 4100 four week period is over and the IPP Designated Expert is convinced 4101 that consensus has been achieved, the IPP Designated Expert either 4102 approves the request for registration or rejects it. Rejection may 4103 occur because of significant objections raised on the list or 4104 objections raised externally. 4106 Decisions made by the Reviewer must be posted to the ipp@pwg.org 4107 mailing list within 14 days. Decisions made by the Reviewer may be 4108 appealed to the IESG. 4110 23.7.2.3 IANA Registration 4112 Provided that the Delivery Method registration proposal has either 4113 passed review or has been successfully appealed to the IESG, the IANA 4114 will be notified by the delivery method reviewer and asked to 4115 register the Delivery Method and make it available to the community. 4117 23.7.3 Delivery Method Document Registrations 4119 Each Push Delivery Method Document defines a URI scheme. Such a URI 4120 scheme is used in a URI value of the "notification-recipient" (uri) 4121 Subscription Template attribute (see section 5.3.1) and the uriScheme 4122 value of the "notify-schemes-supported" (1setOf uriScheme 5.3.1.1) 4123 Printer attribute(see section ). Rather than creating a separate 4124 section in the IPP Registry for Delivery Methods, Push Delivery 4125 Methods will be registered as an additional value of the "notify- 4126 schemes-supported" Printer attribute. These uriScheme values will be 4127 registered according to the procedures of [RFC2911] section 7.1 for 4128 additional attribute values. Therefore, the IPP Registry entry for a 4129 Push Delivery Method will be of the form: 4131 Attribute 4132 Value Ref. Section 4133 --------------------- -------- ------- 4134 notify-schemes-supported (1setOf uriScheme) RFC xxxx 5.3.1.1 4135 RFC xxxx m.n 4137 Each Pull Delivery Method Document defines a keyword method which is 4138 registered as an additional value of the "notify-pull-method" and 4139 "notify-pull-method-supported" Printer attributes. These keyword 4140 values will be registered according to the procedures of [RFC2911] 4141 section 7.1 for additional attribute values. Therefore, the IPP 4142 Registry entry for a Pull Delivery Method will be of the form: 4144 Attribute 4145 Value Ref. Section 4146 --------------------- -------- ------- 4147 notify-pull-method (type2 keyword) [ipp-ntfy] 5.3.2 4148 notify-pull-method-supported (1setOf type2 keyword) 4149 [ipp-ntfy] 5.3.2.1 4150 RFC xxxx m.n 4152 23.7.4 Registration Template 4154 To: ipp@pwg.org 4155 Subject: Registration of a new Delivery Method 4157 Delivery Method name: 4159 (All Push Delivery Method names must be suitable for use as the value 4160 of a URL scheme in the IETF tree and all Pull Delivery Method names 4161 must be suitable IPP keywords according to [RFC2911]) 4163 Published specification(s): 4165 (A specification for the Delivery Method must be openly available 4166 that accurately describes what is being registered.) 4168 Person & email address to contact for further information: 4170 24 Intellectual Property 4172 The IETF takes no position regarding the validity or scope of any 4173 intellectual property or other rights that might be claimed to 4174 pertain to the implementation or use of the technology described in 4175 this document or the extent to which any license under such rights 4176 might or might not be available; neither does it represent that it 4177 has made any effort to identify any such rights. Information on the 4178 IETF's procedures with respect to rights in standards-track and 4179 standards-related documentation can be found in RFC 2028. Copies of 4180 claims of rights made available for publication and any assurances of 4181 licenses to be made available, or the result of an attempt made to 4182 obtain a general license or permission for the use of such 4183 proprietary rights by implementers or users of this specification can 4184 be obtained from the IETF Secretariat. 4186 The IETF invites any interested party to bring to its attention any 4187 copyrights, patents or patent applications, or other proprietary 4188 rights which may cover technology that may be required to practice 4189 this standard. Please address the information to the IETF Executive 4190 Director. 4192 25 Internationalization Considerations 4194 This IPP Notification specification continues support for the 4195 internationalization of [RFC2911] of attributes containing text 4196 strings and names. Allowing a Subscribing Client to specify a 4197 different natural language and charset for each Subscription Object 4198 increases the internationalization support. 4200 The Printer MUST be able to localize the content of Human Consumable 4201 Event Notifications and to localize the value of "notify-text" 4202 attribute in Machine Consumable Event Notifications that it delivers 4203 to Notification Recipients. For localization, the Printer MUST use 4204 the value of the "notify-charset" attribute and the "notify-natural- 4205 language" attribute in the Subscription Object supplied by the 4206 Subscribing Client. 4208 26 Security Considerations 4210 Clients submitting Notification requests to the IPP Printer have the 4211 same security issues as submitting an IPP/1.1 print job request (see 4212 [RFC2911] section 3.2.1 and section 8). The same mechanisms used by 4213 IPP/1.1 can therefore be used by the client Notification submission. 4214 Operations that require authentication can use the HTTP 4215 authentication. Operations that require privacy can use the HTTP/TLS 4216 privacy. As with IPP/1.1 Print Job Objects, if there is no security 4217 on Subscription Objects, sequential assignment of subscription-ids 4218 exposes the system to a passive traffic monitoring threat. 4220 26.1 Client access rights 4222 The Subscription Object access control model is the same as the 4223 access control model for Job objects. The client MUST have the 4224 following access rights for the indicated Subscription operations: 4226 1. Create-Job-Subscriptions (see section 11.1.1): A Per-Job 4227 Subscription object is associated with a Job. To create Per-Job 4228 Subscription Objects, the authenticated user (see [RFC2911] 4229 section 8.3) performing this operation MUST (1) be the job 4230 owner, (2) have Operator or Administrator access rights for this 4231 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 4232 authorized by the Printer's administrator-configured security 4233 policy to create Per-Job Subscription Objects for the target 4234 job. 4236 2. Create-Printer-Subscriptions (see section 11.1.2): A Per- 4237 Printer Subscription object is associated with the Printer. To 4238 create Per-Printer Subscription Objects, the authenticated user 4239 (see [RFC2911] section 8.3) performing this operation MUST (1) 4240 have Operator or Administrator access rights for this Printer 4241 (see [RFC2911] sections 1 and 8.5) or (2) be otherwise 4242 authorized by the Printer's administrator-configured security 4243 policy to create Per-Printer Subscription Objects for this 4244 Printer. 4246 3. Get-Subscription-Attributes (see section 11.2.4): The access 4247 control model for this operation is the same as that of the Get- 4248 Job-Attributes operation (see [RFC2911] section 3.3.4). The 4249 primary difference is that a Get-Subscription-Attributes 4250 operation is directed at a Subscription Object rather than at a 4251 Job object, and a returned attribute group contains Subscription 4252 Object attributes rather than Job object attributes. To query 4253 the specified Subscription Object, the authenticated user (see 4254 [RFC2911] section 8.3) performing this operation MUST (1) be the 4255 Subscription Object owner, (2) have Operator or Administrator 4256 access rights for this Printer (see [RFC2911] sections 1 and 4257 8.5), or (3) be otherwise authorized by the Printer's 4258 administrator-configured security policy to query the 4259 Subscription Object for the target job. Furthermore, the 4260 Printer's security policy MAY limit which attributes are 4261 returned, in a manner similar to the Get-Job-Attributes 4262 operation (see [RFC2911] end of section 3.3.4.2). 4264 4. Get-Subscriptions (see section 11.2.5): The access control 4265 model for this operation is the same as that of the Get-Jobs 4266 operation (see [RFC2911] section 3.2.6). The primary difference 4267 is that the operation is directed at Subscription Objects rather 4268 than at Job objects, and the returned attribute groups contain 4269 Subscription Object attributes rather than Job object 4270 attributes. To query Per-Job Subscription Objects of the 4271 specified job (client supplied the "notify-job-id" operation 4272 attribute - see section 11.2.5.1.1), the authenticated user (see 4273 [RFC2911] section 8.3) performing this operation MUST (1) be the 4274 Subscription Object owner, (2) have Operator or Administrator 4275 access rights for this Printer (see [RFC2911] sections 1 and 4276 8.5), or (3) be otherwise authorized by the Printer's 4277 administrator-configured security policy to query the 4278 Subscription Object for the target job. To query Per-Printer 4279 Subscription Objects of the Printer (client omits the "notify- 4280 job-id" operation attribute - see section 11.2.5.1.1), the 4281 authenticated user (see [RFC2911] section 8.3) performing this 4282 operation MUST (1) have Operator or Administrator access rights 4283 for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be 4284 otherwise authorized by the Printer's administrator-configured 4285 security policy to query Per-Printer Subscription Objects for 4286 the target Printer. Furthermore, the Printer's security policy 4287 MAY limit which attributes are returned, in a manner similar to 4288 the Get-Job-Attributes operation (see [RFC2911] end of section 4289 3.2.6.2). 4291 5. Renew-Subscriptions (see section 11.2.6): The authenticated 4292 user (see [RFC2911] section 8.3) performing this operation MUST 4293 (1) be the owner of the Per-Printer Subscription Object, (2) 4294 have Operator or Administrator access rights for the Printer 4295 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 4296 authorized by the Printer's administrator-configured security 4297 policy to renew Per-Printer Subscription Objects for the target 4298 Printer 4300 6. Cancel-Subscription (see section 11.2.7): The authenticated 4301 user (see [RFC2911] section 8.3) performing this operation MUST 4302 (1) be the owner of the Subscription Object, (2) have Operator 4303 or Administrator access rights for the Printer (see [RFC2911] 4304 sections 1 and 8.5), or (3) be otherwise authorized by the 4305 Printer's administrator-configured security policy to cancel the 4306 target Subscription Object. 4308 The standard security concerns (delivery to the right user, privacy 4309 of content, tamper proof content) apply to each Delivery Method. 4310 Some Delivery Methods are more secure than others. Each Delivery 4311 Method Document MUST discuss its Security Considerations. 4313 26.2 Printer security threats 4315 Notification trap door: If a Printer supports the OPTIONAL "notify- 4316 attributes" Subscription Template attribute (see section 5.3.4) where 4317 the client can request that the Printer return any specified Job, 4318 Printer, and Subscription object attributes, the Printer MUST apply 4319 the same security policy to these requested attributes in the Get- 4320 Notifications request as it does for the Get-Jobs, Get-Job- 4321 Attributes, Get-Printer-Attributes, and Get-Subscription-Attributes 4322 requests. 4324 26.3 Notification Recipient security threats 4326 Unwanted Events Notifications (spam): For any Push Delivery Method, 4327 by far the biggest security concern is the abuse of notification: 4328 delivering unwanted Event Notifications to third parties (i.e., 4329 spam). The problem is made worse by notification addresses that may 4330 be redistributed to multiple parties. There exist scenarios where 4331 third party notification is used (see Scenario #2 and #3 in [ipp-not- 4332 req]). Any fully secure solution would require active agreement of 4333 all recipients before delivering anything. 4335 27 Contributors 4337 The following people made significant contributions to the design and 4338 review of this specification: 4340 Scott A. Isaacson 4341 Novell, Inc. 4342 122 E 1700 S 4343 Provo, UT 84606 4345 Phone: 801-861-7366 4346 Fax: 801-861-2517 4347 e-mail: sisaacson@novell.com 4349 Roger deBry 4350 Utah Valley State College 4351 Orem, UT 84058 4353 Phone: (801) 222-8000 4354 EMail: debryro@uvsc.edu 4356 Jay Martin 4357 Underscore Inc. 4358 9 Jacqueline St. 4359 Hudson, NH 03051-5308 4360 603-889-7000 4361 fax: 775-414-0245 4362 e-mail: jkm@underscore.com 4364 Michael Shepherd 4365 Xerox Corporation 4366 800 Phillips Road MS 128-51E 4367 Webster, NY 14450 4369 Phone: 716-422-2338 4370 Fax: 716-265-8871 4371 e-mail: mshepherd@usa.xerox.com 4372 Ron Bergman 4373 Hitachi Koki Imaging Solutions 4374 1757 Tapo Canyon Road 4375 Simi Valley, CA 93063-3394 4377 Phone: 805-578-4421 4378 Fax: 805-578-4001 4379 Email: rbergma@hitachi-hkis.com 4381 28 Author's Addresses 4383 Robert Herriot 4384 Global Workflow Solutions 4385 706 Colorado Ave. 4386 Palo Alto, CA 94303 4388 Phone: 650-324-4000 4389 Email: bob@herriot.com 4391 Tom Hastings 4392 Xerox Corporation 4393 737 Hawaii St. ESAE 231 4394 El Segundo, CA 90245 4396 Phone: 310-333-6413 4397 Fax: 310-333-5514 4398 e-mail: hastings@cp10.es.xerox.com 4400 29 Description of the base IPP documents (Informative) 4402 The base set of IPP documents includes: 4404 Design Goals for an Internet Printing Protocol [RFC2567] 4405 Rationale for the Structure and Model and Protocol for the Internet 4406 Printing Protocol [RFC2568] 4407 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 4408 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 4409 Internet Printing Protocol/1.1: Implementer's Guide [RFC3196] 4410 Mapping between LPD and IPP Protocols [RFC2569] 4412 The "Design Goals for an Internet Printing Protocol" document takes a 4413 broad look at distributed printing functionality, and it enumerates 4414 real-life scenarios that help to clarify the features that need to be 4415 included in a printing protocol for the Internet. It identifies 4416 requirements for three types of users: end users, operators, and 4417 administrators. It calls out a subset of end user requirements that 4418 are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator 4419 operations have been added to IPP/1.1 [RFC2911, RFC2910]. 4421 The "Rationale for the Structure and Model and Protocol for the 4422 Internet Printing Protocol" document describes IPP from a high level 4423 view, defines a roadmap for the various documents that form the suite 4424 of IPP specification documents, and gives background and rationale 4425 for the IETF IPP working group's major decisions. 4427 The "Internet Printing Protocol/1.1: Model and Semantics" document 4428 describes a simplified model with abstract objects, their attributes, 4429 and their operations. The model introduces a Printer and a Job. The 4430 Job supports multiple documents per Job. The model document also 4431 addresses how security, internationalization, and directory issues 4432 are addressed. 4434 The "Internet Printing Protocol/1.1: Encoding and Transport" document 4435 is a formal mapping of the abstract operations and attributes defined 4436 in the model document onto HTTP/1.1 [RFC2616]. It also defines the 4437 encoding rules for a new Internet MIME media type called 4438 "application/ipp". This document also defines the rules for 4439 transporting over HTTP a message body whose Content-Type is 4440 "application/ipp". This document defines the 'ipp' scheme for 4441 identifying IPP printers and jobs. 4443 The "Internet Printing Protocol/1.1: Implementer's Guide" document 4444 gives insight and advice to implementers of IPP clients and IPP 4445 objects. It is intended to help them understand IPP/1.1 and some of 4446 the considerations that may assist them in the design of their client 4447 and/or IPP object implementations. For example, a typical order of 4448 processing requests is given, including error checking. Motivation 4449 for some of the specification decisions is also included. 4451 The "Mapping between LPD and IPP Protocols" document gives some 4452 advice to implementers of gateways between IPP and LPD (Line Printer 4453 Daemon) implementations. 4455 30 Full Copyright Statement 4457 Copyright (C) The Internet Society (1998,1999,2000,2001,2002,2003). 4458 All Rights Reserved 4460 This document and translations of it may be copied and furnished to 4461 others, and derivative works that comment on or otherwise explain it 4462 or assist in its implementation may be prepared, copied, published 4463 and distributed, in whole or in part, without restriction of any 4464 kind, provided that the above copyright notice and this paragraph are 4465 included on all such copies and derivative works. However, this 4466 document itself may not be modified in any way, such as by removing 4467 the copyright notice or references to the Internet Society or other 4468 Internet organizations, except as needed for the purpose of 4469 developing Internet standards in which case the procedures for 4470 copyrights defined in the Internet Standards process must be 4471 followed, or as required to translate it into languages other than 4472 English. 4474 The limited permissions granted above are perpetual and will not be 4475 revoked by the Internet Society or its successors or assigns. 4477 This document and the information contained herein is provided on an 4478 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4479 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4480 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4481 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4482 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4484 Acknowledgement 4486 Funding for the RFC Editor function is currently provided by the 4487 Internet Society.