idnits 2.17.1 draft-ietf-ipp-not-spec-10.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 3857 has weird spacing: '...reation opera...' == Line 4077 has weird spacing: '...FC xxxx m.n...' == Line 4215 has weird spacing: '...FC xxxx m.n...' == Line 4230 has weird spacing: '...FC xxxx m.n...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Unrecognized Status in '[Target Category: standards track]', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 10, 2002) is 7866 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) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2717 (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2910 (Obsoleted by RFC 8010) ** Obsolete normative reference: RFC 2911 (Obsoleted by RFC 8011) ** Obsolete normative reference: RFC 3381 (Obsoleted by RFC 8011) -- Obsolete informational reference (is this intentional?): RFC 2434 (ref. 'IANA-CON') (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 2565 (Obsoleted by RFC 2910) -- Obsolete informational reference (is this intentional?): RFC 2566 (Obsoleted by RFC 2911) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 8 errors (**), 0 flaws (~~), 8 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Printing Protocol WG R. Herriot 3 INTERNET-DRAFT consultant 4 T. Hastings 5 Updates RFC 2910 and 2911 Xerox Corporation 6 [Target Category: standards track] October 10, 2002 7 Expires: April 10, 2003 9 Internet Printing Protocol (IPP): 10 Event Notifications and Subscriptions 12 Copyright (C) The Internet Society (2002). All Rights Reserved. 14 Status of this Memo 16 This document is an Internet-Draft and is in full conformance with 17 all provisions of Section 10 of RFC 2026. Internet-Drafts are 18 working documents of the Internet Engineering Task Force (IETF), its 19 areas, and its working groups. Note that other groups may also 20 distribute working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress". 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.html 29 The list of Internet-Draft Shadow Directories can be accessed as 30 http://www.ietf.org/shadow.html. 32 Abstract 34 This document describes an OPTIONAL extension to the Internet 35 Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). 36 This extension allows a client to subscribe to printing related 37 Events. Subscriptions are modeled as Subscription Objects. The 38 Subscription Object specifies that when one of the specified Events 39 occurs, the Printer delivers an asynchronous Event Notification to 40 the specified Notification Recipient via the specified Push or Pull 41 Delivery Method (i.e., protocol). 43 A client associates Subscription Objects with a particular Job by 44 performing the Create-Job-Subscriptions operation or by submitting a 45 Job with subscription information. A client associates Subscription 46 Objects with the Printer by performing a Create-Printer-Subscriptions 47 operation. Four other operations are defined for Subscription 48 Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- 49 Subscription, and Cancel-Subscription. 51 Table of Contents 53 1 Introduction.....................................................7 54 1.1 Notification Overview..........................................7 56 2 Models for Notification.........................................10 57 2.1 Model for Simple Notification (Normative).....................10 58 2.2 Additional Models for Notification (Informative)..............11 60 3 Terminology.....................................................11 61 3.1 Conformance Terminology.......................................11 62 3.2 Other Terminology.............................................11 64 4 Object Relationships............................................14 65 4.1 Printer and Per-Printer Subscription Objects..................14 66 4.2 Printer, Job and Per-Job Subscription Objects.................14 68 5 Subscription Object.............................................15 69 5.1 Rules for Support of Subscription Template Attributes.........15 70 5.2 Rules for Processing Subscription Template Attributes.........16 71 5.3 Subscription Template Attributes..............................20 72 5.3.1 notify-recipient-uri (uri)..................................22 73 5.3.1.1 notify-schemes-supported (1setOf uriScheme)..............23 74 5.3.2 notify-pull-method (type2 keyword)..........................23 75 5.3.2.1 notify-pull-method-supported (1setOf type2 keyword).......24 76 5.3.3 notify-events (1setOf type2 keyword)........................24 77 5.3.3.1 notify-events-default (1setOf type2 keyword)..............24 78 5.3.3.2 notify-events-supported (1setOf type2 keyword)............25 79 5.3.3.3 notify-max-events-supported (integer(2:MAX))..............25 80 5.3.3.4 Standard Values for Subscribed Events.....................25 81 5.3.3.4.1 No Events...............................................25 82 5.3.3.4.2 Subscribed Printer Events...............................26 83 5.3.3.4.3 Subscribed Job Events...................................27 84 5.3.3.5 Rules for Matching of Subscribed Events...................28 85 5.3.3.5.1 Rules for Matching of Printer Events....................29 86 5.3.3.5.2 Rules for Matching of Job Events........................29 87 5.3.3.5.3 Special Cases for Matching Rules........................30 88 5.3.4 notify-attributes (1setOf type2 keyword)....................31 89 5.3.4.1 notify-attributes-supported (1setOf type2 keyword)........32 90 5.3.5 notify-user-data (octetString(63))..........................32 91 5.3.6 notify-charset (charset)....................................33 92 5.3.7 notify-natural-language (naturalLanguage)...................33 93 5.3.8 notify-lease-duration (integer(0:67108863)).................34 94 5.3.8.1 notify-lease-duration-default (integer(0:67108863)).......35 95 5.3.8.2 notify-lease-duration-supported (1setOf (integer(0: 67108863) 96 | rangeOfInteger(0:67108863)))....................................35 97 5.3.9 notify-time-interval (integer(0:MAX)).......................35 98 5.4 Subscription Description Attributes...........................36 99 5.4.1 notify-subscription-id (integer (1:MAX))...................37 100 5.4.2 notify-sequence-number (integer (0:MAX))....................37 101 5.4.3 notify-lease-expiration-time (integer(0:MAX))...............38 102 5.4.4 notify-printer-up-time (integer(1:MAX)).....................39 103 5.4.5 notify-printer-uri (uri)....................................39 104 5.4.6 notify-job-id (integer(1:MAX))..............................40 105 5.4.7 notify-subscriber-user-name (name(MAX)).....................40 107 6 Printer Description Attributes Related to Notification..........41 108 6.1 printer-state-change-time (integer(1:MAX))....................41 109 6.2 printer-state-change-date-time (dateTime).....................41 111 7 New Values for Existing Printer Description Attributes..........42 112 7.1 operations-supported (1setOf type2 enum)......................42 114 8 Attributes Only in Event Notifications..........................42 115 8.1 notify-subscribed-event (type2 keyword).......................43 116 8.2 notify-text (text(MAX)).......................................43 118 9 Event Notification Content......................................43 119 9.1 Content of Machine Consumable Event Notifications.............46 120 9.1.1 Event Notification Content Common to All Events.............47 121 9.1.2 Additional Event Notification Content for Job Events........49 122 9.1.3 Additional Event Notification Content for Printer Events....50 123 9.2 Content of Human Consumable Event Notification................50 124 9.2.1 Event Notification Content Common to All Events.............51 125 9.2.2 Additional Event Notification Content for Job Events........53 126 9.2.3 Additional Event Notification Content for Printer Events....54 128 10 Delivery Methods...............................................54 130 11 Operations for Notification....................................57 131 11.1 Subscription Creation Operations.............................57 132 11.1.1 Create-Job-Subscriptions Operation.........................57 133 11.1.1.1 Create-Job-Subscriptions Request.........................58 134 11.1.1.1.1 notify-job-id (integer(1:MAX)).........................58 135 11.1.1.2 Create-Job-Subscriptions Response........................59 136 11.1.2 Create-Printer-Subscriptions operation.....................60 137 11.1.2.1 Create-Printer-Subscriptions Request.....................60 138 11.1.2.2 Create-Printer-Subscriptions Response....................61 139 11.1.3 Job Creation Operations - Extensions for Notification......61 140 11.1.3.1 Job Creation Request.....................................62 141 11.1.3.2 Job Creation Response....................................62 142 11.2 Other Operations.............................................63 143 11.2.1 Restart-Job Operation - Extensions for Notification........63 144 11.2.2 Validate-Job Operation - Extensions for Notification.......64 145 11.2.3 Get-Printer-Attributes - Extensions for Notification.......64 146 11.2.4 Get-Subscription-Attributes operation......................65 147 11.2.4.1 Get-Subscription-Attributes Request......................65 148 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)).............66 149 11.2.4.1.2 "requested-attributes" (1setOf keyword)................66 150 11.2.4.2 Get-Subscription-Attributes Response.....................66 151 11.2.5 Get-Subscriptions operation................................68 152 11.2.5.1 Get-Subscriptions Request................................68 153 11.2.5.1.1 "notify-job-id" (integer(1:MAX)).......................69 154 11.2.5.1.2 "limit" (integer(1:MAX))...............................69 155 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword)..........69 156 11.2.5.1.4 "my-subscriptions" (boolean)...........................70 157 11.2.5.2 Get-Subscriptions Response...............................70 158 11.2.6 Renew-Subscription operation...............................71 159 11.2.6.1 Renew-Subscription Request...............................71 160 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)).............72 161 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX))...............72 162 11.2.6.2 Renew-Subscription Response..............................72 163 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX))...............73 164 11.2.7 Cancel-Subscription operation..............................73 165 11.2.7.1 Cancel-Subscription Request..............................74 166 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)).............74 167 11.2.7.2 Cancel-Subscription Response.............................75 169 12 Status Codes...................................................75 170 12.1 successful-ok-ignored-subscriptions (0x0003).................75 171 12.2 client-error-ignored-all-subscriptions (0x0414)..............76 173 13 Status Codes in Subscription Attributes Groups.................76 174 13.1 client-error-uri-scheme-not-supported (0x040C)...............76 175 13.2 client-error-attributes-or-values-not-supported (0x040B).....77 176 13.3 client-error-too-many-subscriptions (0x0415).................77 177 13.4 successful-ok-too-many-events (0x0005).......................77 178 13.5 successful-ok-ignored-or-substituted-attributes (0x0001).....77 180 14 Encodings of Additional Attribute Tags.........................77 182 15 Conformance Requirements.......................................78 183 15.1 Conformance requirements for clients.........................78 184 15.2 Conformance requirements for Printers........................78 186 16 Appendix A - Model for Notification with Cascading Printers 187 (Informative).....................................................79 189 17 Appendix B - Distributed Model for Notification (Informative)..81 191 18 Appendix C - Extended Notification Recipient (Informative).....82 193 19 Appendix D - Details about Conformance Terminology (Normative).83 195 20 Appendix E - Object Model for Notification (Normative).........83 196 20.1 Object relationships.........................................84 197 20.2 Printer Object and Per-Printer Subscription Objects..........85 198 20.3 Job Object and Per-Job Subscription Objects..................85 200 21 Appendix F - Per-Job versus Per-Printer Subscription Objects 201 (Normative).......................................................85 203 22 Normative References...........................................86 205 23 Informative References.........................................87 207 24 IANA Considerations............................................87 208 24.1 Attribute Registrations......................................88 209 24.2 Additional Enum Attribute Value Registrations................89 210 24.3 Operation Registrations......................................89 211 24.4 Status code Registrations....................................90 212 24.5 Attribute Group tag Registrations............................90 213 24.6 Registration of Events.......................................90 214 24.7 Registration of Event Notification Delivery Methods..........91 215 24.7.1 Requirements for Registration of Event Notification Delivery 216 Methods................................................91 217 24.7.1.1 Required Characteristics.................................91 218 24.7.1.2 Naming Requirements......................................91 219 24.7.1.3 Functionality Requirements...............................92 220 24.7.1.4 Usage and Implementation Requirements....................92 221 24.7.1.5 Publication Requirements.................................92 222 24.7.2 Registration Procedure.....................................92 223 24.7.2.1 Present the proposal to the Community....................92 224 24.7.2.2 Delivery Method Reviewer.................................93 225 24.7.2.3 IANA Registration........................................93 226 24.7.3 Delivery Method Document Registrations.....................93 227 24.7.4 Registration Template......................................94 229 25 Internationalization Considerations............................94 231 26 Security Considerations........................................95 232 26.1 Client access rights.........................................95 233 26.2 Printer security threats.....................................97 234 26.3 Notification Recipient security threats......................97 236 27 Contributors...................................................97 238 28 Author's Addresses.............................................98 240 29 Appendix G - Description of the base IPP documents (Informative)99 242 30 Appendix H - Full Copyright Statement (Informative)...........100 244 Tables 245 Table 1 - Subscription Template Attributes........................22 246 Table 2 - Subscription Description Attributes.....................37 247 Table 3 - Printer Description Attributes Associated with Notification 248 ..............................................................41 249 Table 4 - Operation-id assignments................................42 250 Table 5 - Attributes in Event Notification Content................48 251 Table 6 - Additional Event Notification Content for Job Events....49 252 Table 7 - Combinations of Events and Subscribed Events for "job- 253 impressions-completed" ........................................49 254 Table 8 - Additional Event Notification Content for Printer Events50 255 Table 9 - Printer Name in Event Notification Content..............52 256 Table 10 - Event Name in Event Notification Content...............52 257 Table 11 - Event Time in Event Notification Content...............52 258 Table 12 - Job Name in Event Notification Content.................53 259 Table 13 - Job State in Event Notification Content................53 260 Table 14 - Printer State in Event Notification Content............54 261 Table 15 - Information about the Delivery Method..................55 262 Table 16 - Printer Conformance Requirements for Operations........79 264 Figures 265 Figure 1 - Model for Notification.................................10 266 Figure 2 - Model for Notification with Cascading Printers.........80 267 Figure 3 - Opaque Use of a Notification Server Transparent to the 268 Client ........................................................81 269 Figure 4 - Use of an Extended Notification Recipient transparent to 270 the Printer ...................................................82 271 Figure 5 - Object Model for Notification..........................84 273 1 Introduction 275 This IPP notification specification is an OPTIONAL extension to 276 Internet Printing Protocol/1.1: Model and Semantics [RFC2911, 277 RFC2910]. See Appendix 29 for a description of the base IPP 278 documents. This document in combination with the following documents 279 is intended to meet the most important notification requirements 280 described in [ipp-not-req]: 282 Internet Printing Protocol (IPP): "Job Progress Attributes" 283 [RFC3381] 284 Internet Printing Protocol (IPP): "The 'ippget' Delivery Method 285 for Event Notifications" [ipp-get-method] 287 This specification REQUIRES that clients and Printers support the 288 'ippget' Pull Delivery Method [ipp-get-method]. Conforming client 289 and Printer implementations MAY support additional Push or Pull 290 Delivery Methods as well. Note: this document does not define any 291 Delivery Methods itself, but it does define the rules for conformance 292 for Delivery Method Documents and their registration with IANA (see 293 section 24.7.3). 295 Refer to the Table of Contents for the layout of this document. 297 1.1 Notification Overview 299 This document defines operations that a client can perform in order 300 to create Subscription Objects in a Printer and carry out other 301 operations on them. A Subscription Object represents a Subscription 302 abstraction. The Subscription Object specifies that when one of the 303 specified Events occurs, the Printer delivers an asynchronous Event 304 Notification to the specified Notification Recipient via the 305 specified Delivery Method (i.e., protocol). 307 When a client (called a Subscribing Client) performs an operation 308 that creates a Subscription Object, the operation contains one or 309 more Subscription Template Attributes Groups. Each such group holds 310 information used by the Printer to initialize a newly created 311 Subscription Object. The Printer creates one Subscription Object for 312 each Subscription Template Attributes Group in the operation. This 313 group is like the Job Template Attributes group defined in [RFC2911]. 314 The following is an example of the information included in a 315 Subscription Template Attributes Group (see section 5 for details on 316 the Subscription Object attributes): 318 1.The names of Subscribed Events that are of interest to the 319 Notification Recipient. 321 2.The address (URL) of one Notification Recipient for a Push 322 Delivery Method or the method for a Pull Delivery Method. 323 3.The Delivery Method (i.e., the protocol) which the Printer uses 324 to deliver the Event Notification. 325 4.Some opaque data that the Printer delivers to the Notification 326 Recipient in the Event Notification. For example, the 327 Notification Recipient might use this opaque data as a 328 forwarding address for the Event Notification. 329 5.The charset to use in text fields within an Event Notification 330 6.The natural language to use in the text fields of the Event 331 Notification 332 7.The requested lease time in seconds for the Subscription Object 333 An operation that creates a Subscription Object is called a 334 Subscription Creation Operation. These operations include the 335 following operations (see section 11.1 for further details): 337 - Job Creation operation: When a client performs such an 338 operation (Print-Job, Print-URI, and Create-Job), a client can 339 include zero or more Subscription Template Attributes Groups in 340 the request. The Printer creates one Subscription Object for 341 each Subscription Template Attributes Group in the request, and 342 the Printer associates each such Subscription Object with the 343 newly created Job. This document extends these operations' 344 definitions in [RFC2911] by adding Subscription Template 345 Attributes Groups in the request and Subscription Attributes 346 Groups in the response. 348 - Create-Job-Subscriptions operation: A client can include one or 349 more Subscription Template Attributes Groups in the request. 350 The Printer creates one Subscription Object for each 351 Subscription Template Attributes Group and associates each with 352 the job that is the target of this operation. 354 - Create-Printer-Subscriptions operation: A client can include 355 one or more Subscription Template Attributes Groups in the 356 request. The Printer creates one Subscription Object for each 357 Subscription Template Attributes Group and associates each with 358 the Printer that is the target of this operation. 360 For each of the above operations: 362 - the Printer associates a Subscription Object with the Printer 363 or a specific Job. When a Subscription Object is associated 364 with a Job Object, it is called a Per-Job Subscription Object. 365 When a Subscription Object is associated with a Printer Object, 366 it is called a Per-Printer Subscription Object. 368 - the response contains one Subscription Attributes Group for 369 each Subscription Template Attributes Group in the request and 370 in the same order. When the Printer successfully creates a 371 Subscription Object, its corresponding Subscription Attributes 372 Group contains the "notify-subscription-id" attribute. This 373 attribute uniquely identifies the Subscription Object and is 374 analogous to a "job-id" for a Job object. Some operations 375 described below use the "notify-subscription-id" to identify 376 the target Subscription Object. 378 This document defines the following additional operations (see 379 section 11.2 for further details): 381 - Restart-Job operation: When a client performs the Restart-Job 382 operation [RFC2911], the Printer re-uses the same Job and its 383 Subscription Objects. 385 - Validate-Job operation: When a client performs this operation, 386 a client can include zero or more Subscription Template 387 Attributes Groups in the request. The Printer determines if it 388 could create one Subscription Object for each Subscription 389 Template Attributes Group in the request. This document 390 extends this operation's definition in [RFC2911] by adding 391 Subscription Template Attributes Groups in the request and 392 Subscription Attributes Groups in the response. 394 - Get-Subscription-Attributes operation: This operation allows a 395 client to obtain the specified attributes of a target 396 Subscription Object. 398 - Get-Subscriptions operation: This operation allows a client to 399 obtain the specified attributes of all Subscription Objects 400 associated with the Printer or a specified Job. 402 - Renew-Subscription operation: This operation renews the lease 403 on the target Per-Printer Subscription Object before it 404 expires. A newly created Per-Printer Subscription Object 405 receives an initial lease. It is the duty of the client to use 406 this operation frequently enough to preserve a Per-Printer 407 Subscription Object. The Printer deletes a Per-Printer 408 Subscription Object when its lease expires. A Per-Job 409 Subscription Object last exactly as long as its associated Job 410 Object and thus doesn't have a lease. 412 - Cancel-Subscription operation: This operation (1) cancels the 413 lease on the specified Per-Printer Subscription Object and 414 thereby deletes the Per-Printer Subscription Object or (2) 415 deletes the Per-Job Subscription Object. 417 When an Event occurs, the Printer finds all Subscription Objects 418 listening for the Event (see section 9 for details on finding such 419 Subscription Objects). For each such Subscription Object, the 420 Printer: 422 a)generates an Event Notification with information specified in 423 section 9, AND 424 b)either: 425 i) If the Delivery Method is a Push Delivery Method as 426 indicated by the presence of the Subscription Object's 427 "notify-recipient-uri" attribute, delivers the Event 428 Notification using the Delivery Method and target address 429 identified in the Subscription Object's "notify-recipient- 430 uri" attribute, OR 431 ii) If the Delivery Method is a Pull Delivery Method as 432 indicated by the presence of the Subscription Object's 433 "notify-pull-method" attribute, saves Event Notification 434 for a time period called the Event Life defined by the 435 Delivery Method, i.e., the Notification Recipient is 436 expected to fetch the Event Notifications. 438 2 Models for Notification 440 2.1 Model for Simple Notification (Normative) 442 As part of a Subscription Creation Operation, an IPP Printer (i.e., 443 located in an output device or a server) creates one or more 444 Subscription Objects. In a Subscription Creation Operation, the 445 client specifies the Notification Recipient to which the Printer is 446 to deliver Event Notifications. A Notification Recipient can be the 447 Subscribing Client or a third party. 449 Figure 1 shows the Notification model for a simple Client-Printer 450 relationship. 452 embedded printer: 453 output device or server 454 PDA, desktop, or server +---------------+ 455 +--------+ | ########### | 456 | client |-----Subscription ---------># Printer # | 457 +--------+ Creation Operation | # Object # | 458 +------------+ | #####|##### | 459 |Notification| +-------|-------+ 460 |Recipient |<----IPP Event Notifications----+ 461 +------------+ (Job and/or Printer Events) 463 Figure 1 - Model for Notification 465 2.2 Additional Models for Notification (Informative) 467 Additional models have been proposed (see Appendices 16, 17, and 18). 469 3 Terminology 471 This section defines terminology used throughout this document. 472 Other terminology is defined in [RFC2911]. 474 3.1 Conformance Terminology 476 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 477 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 478 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 479 12.1. If an implementation supports the extension defined in this 480 document, then these terms apply; otherwise, they do not. These 481 terms define conformance to this document only; they do not affect 482 conformance to other documents, unless explicitly stated otherwise. 483 See Appendix 19 for complete details. 485 Note: a feature that is OPTIONAL in this document becomes REQUIRED if 486 the Printer implements a Delivery Method that REQUIRES the feature. 488 READ-ONLY - an adjective used in an attribute definition to indicate 489 that an IPP Printer MUST NOT allow the attribute's value to be 490 modified. 492 3.2 Other Terminology 494 This document uses the same terminology as [RFC2911], such as 495 "client", "Printer", "attribute", "attribute value", "keyword", 496 "operation", "request", "response", "administrator", "operator", and 497 "support". In addition, the following terms are defined for use in 498 this document and the Delivery Method Documents: 500 Compound Event Notification - two or more Event Notifications that a 501 Printer delivers together as a single request or response. The 502 Delivery Method Document specifies whether the Delivery Method 503 supports Compound Event Notifications. 505 Delivery Method - the mechanism by which the Printer delivers an 506 Event Notification. 508 Delivery Method Document - a document, separate from this document, 509 that defines a Delivery Method. 511 Event - some occurrence (either expected or unexpected) within the 512 printing system of a change of state, condition, or configuration of 513 a Job or Printer object. An Event occurs only at one instant in time 514 and does not span the time the physical Event takes place. For 515 example, jam-occurred and jam-cleared are two distinct, instantaneous 516 Events, even though the jam may last for a while. 518 Event Life - For a Pull Delivery Method, the length of time in 519 seconds after an Event occurs during which the Printer will retain 520 that Event for delivery in an Event Notification. After the Event 521 Life expires, the Printer will no longer deliver an Event 522 Notification for that Event in such a response. 524 Event Notification - the information about an Event that the Printer 525 delivers when an Event occurs. 527 Event Notification Attributes Group - The attributes group which is 528 used to deliver an Event Notification in a request (Push 529 Delivery Methods) or a response (Pull Delivery Methods). 531 Human Consumable Event Notification - localized text for human 532 consumption only. There is no standardized format and thus programs 533 should not try to parse this text. 535 Job Creation operation - One of the operations that creates a Job 536 object: Print-Job, Print-URI and Create-Job. The Restart-Job 537 operation [RFC2911] is not considered a Job Creation operation, since 538 the Printer re-uses the existing Job object. The Validate-Job 539 operation is not considered a Job Creation operation because no Job 540 object is created. Therefore, when a statement also applies to 541 either the Restart-Job and/or the Validate-Job operation, they are 542 mentioned explicitly. 544 Job Event - an Event caused by some change in a particular job on the 545 Printer, e.g., 'job-completed'. 547 Machine Consumable Event Notification - bytes for program 548 consumption. The bytes are formatted according to the Delivery 549 Method document. 551 Notification - when not in the phrases 'Event Notification' and 552 'Notification Recipient' - the concepts of this specification, i.e., 553 Events, Subscription Objects, and Event Notifications. 555 Notification Recipient - the entity to which the Printer delivers an 556 Event Notification. For Push Delivery Methods, the IPP Printer sends 557 the Notifications to a Notification Recipient. For Pull Delivery 558 Methods, the Notification Recipient is acting in the role of an IPP 559 client and requests Event Notifications and so the terms "client" and 560 "Notification Recipient" are used interchangeably with such Delivery 561 Methods. For example, see [ipp-get-method]. 563 Per-Job Subscription Object - A Subscription Object that is 564 associated with a single Job. The Create-Job-Subscriptions operation 565 and Job Creation operations create such an object. 567 Per-Printer Subscription Object - A Subscription Object that is 568 associated with the Printer as a whole. The Create-Printer- 569 Subscriptions operation creates such an object. 571 Printer Event - an Event caused by some change in the Printer that is 572 not specific to a job, e.g., 'printer-state-changed'. 574 Pull Delivery Method - The Printer saves Event Notifications for some 575 event life time and expects the Notification Recipient to request 576 Event Notifications. The Printer delivers the Event Notifications in 577 a response to such a request. 579 Push Delivery Method -The Printer delivers the Event Notification 580 shortly after an Event occurs. 582 Subscribed Event - an Event that the Subscribing Client expresses 583 interest in by making it a value of the "notify-events" attribute on 584 a Subscription Object. 586 Subscribed Job Event - a Subscribed Event that is a Job Event. 588 Subscribed Printer Event - a Subscribed Event that is a Printer 589 Event. 591 Subscribing Client - The client that creates the Subscription Object. 593 Subscription Attributes Group - The attributes group in a response 594 that contains Subscription Object attributes. 596 Subscription Creation Operation - An operation that creates a 597 Subscription Object: Job Creation operations, Create-Job- 598 Subscriptions operation, Create-Printer-Subscriptions operation. In 599 the context of a Job Creation operation, a Subscription Creation 600 Operation is the part of the Job Creation operation that creates one 601 or more Subscription objects. The Restart-Job operation [RFC2911] is 602 not considered a Subscription Creation Operation, since the Printer 603 re-uses the Job's existing Subscription Objects, rather than creating 604 any new Subscription Objects. 606 Subscription Creation Request - The request portion of a Subscription 607 Creation Operation. 609 Subscription Description Attributes - Subscription Object attributes 610 that a Printer supplies during a Subscription Creation Operation. 612 Subscription Object - An object containing a set of attributes that 613 indicate: the Notification Recipient (for Push Delivery Method 614 only), the Delivery Method, the Subscribed Events that cause the 615 Printer to deliver an Event Notification, and the information to 616 include in an Event Notification. 618 Subscription Template Attributes - Subscription Object attributes 619 that a client can supply in a Subscription Creation Operation and 620 associated Printer Object attributes that specify supported and 621 default values for the Subscription Object attributes. 623 Subscription Template Attributes Group - The attributes group in a 624 request that contains Subscription Object attributes that are 625 Subscription Template Attributes. 627 4 Object Relationships 629 This section defines the object relationships between the Printer, 630 Job, and Subscription Objects. It does not define the 631 implementation. For an illustration of these relationships, see 632 Appendix 20. 634 4.1 Printer and Per-Printer Subscription Objects 636 1.A Printer object can be associated with zero or more Per-Printer 637 Subscription Objects. 639 2.Each Per-Printer Subscription Object is associated with exactly 640 one Printer object. 642 4.2 Printer, Job and Per-Job Subscription Objects 644 1.A Printer object is associated with zero or more Job objects. 646 2.Each Job object is associated with exactly one Printer object. 648 3.A Job object is associated with zero or more Per-Job Subscription 649 Objects. 651 4.Each Per-Job Subscription Object is associated with exactly one 652 Job object. 654 5 Subscription Object 656 A Subscribing Client creates a Subscription Object with a 657 Subscription Creation Operation in order to indicate its interest in 658 certain Events. See section 11 for a description of these 659 operations. When an Event occurs, the Subscription Object specifies 660 to the Printer where to deliver Event Notifications for Push Delivery 661 Methods only, how to deliver them, and what to include in them. See 662 section 9 for details on the contents of an Event Notification. 664 Using the IPP Job Template attributes as a model (see [RFC2911] 665 section 4.2), the attributes of a Subscription Object are divided 666 into two categories: Subscription Template Attributes and 667 Subscription Description Attributes. 669 Subscription Template attributes are, in turn, like the Job Template 670 attributes, divided into 672 1.Subscription Object attributes that a client can supply in a 673 Subscription Creation Request and 675 2.their associated Printer Object attributes that specify 676 supported and default values for the Subscription Object 677 attributes 679 The remainder of this section specifies general rules for 680 Subscription Template Attributes and describes each attribute in a 681 Subscription Object. 683 5.1 Rules for Support of Subscription Template Attributes 685 Subscription Template Attributes are fundamental to the Notification 686 model described in this specification. The client supplies these 687 attributes in Subscription Creation Operations and the Printer uses 688 these attributes to populate a newly created Subscription Object. 690 Subscription Objects attributes that are Subscription Template 691 Attributes conform to the following rules: 693 1.Each attribute's name starts with the prefix string "notify-" 694 and this document calls such attributes "notify-xxx". 696 2.For each "notify-xxx" Subscription Object attribute defined in 697 column 1 of Table 1 in section 5.3, Table 1 specifies 698 corresponding Printer attributes: "notify-xxx-default", "notify- 699 xxx-supported", "yyy-supported" and "notify-max-xxx-supported" 700 defined in column 2 of Table 1. Note "xxx" stands for the same 701 string in each case and "yyy" stands for some other string. 703 3.If a Printer supports "notify-xxx" in column 1 of Table 1, then 704 the Printer MUST support all associated attributes specified in 705 column 2 of Table 1. For example, Table 1 shows that if the 706 Printer supports "notify-events", it MUST support "notify- 707 events-default", "notify-events-supported" and "notify-max- 708 events-supported". 710 4.If a Printer does not support "notify-xxx" in column 1 of Table 711 1, then the Printer MUST NOT support any associated "notify-yyy" 712 attributes specified in column 2 of Table 1. For example, Table 713 1 shows that if the Printer doesn't support "notify-events", it 714 MUST NOT support "notify-events-default", "notify-events- 715 supported" and "notify-max-events-supported". Note this rule 716 does not apply to attributes whose names do not start with the 717 string "notify-" and are thus defined in another object and used 718 by other attributes. 720 5.Most "notify-xxx" attributes have a corresponding "yyy- 721 supported" attribute that specifies the supported values for 722 "notify-xxx". Column 2 of Table 1 specifies the name of each 723 "yyy-supported" attribute. The naming rules of IPP/1.1 (see 724 [RFC2911]) are used when "yyy-supported" is "notify-xxx- 725 supported". 727 6.Some "notify-xxx" attributes have a corresponding "notify-xxx- 728 default" attribute that specifies the value for "notify-xxx" if 729 the client does not supply it. Column 2 of Table 1 specifies 730 the name of each "notify-xxx-default" attribute. The naming 731 rules of IPP/1.1 (see [RFC2911]) are used. 733 If a client wishes to present an end user with a list of supported 734 values from which to choose, the client SHOULD query the Printer for 735 its supported value attributes. The client SHOULD also query the 736 default value attributes. If the client then limits selectable 737 values to only those values that are supported, the client can 738 guarantee that the values supplied by the client in the create 739 request all fall within the set of supported values at the Printer. 740 When querying the Printer, the client MAY enumerate each attribute by 741 name in the Get-Printer-Attributes Request, or the client MAY just 742 supply the 'subscription-template' group name in order to get the 743 complete set of supported attributes (both supported and default 744 attributes - see section 11.2.3). 746 5.2 Rules for Processing Subscription Template Attributes 748 This section defines a detailed set of rules that a Printer follows 749 when it processes Subscription Template Attributes in a Subscription 750 Creation Request. These rules are similar to the rules for 751 processing Operation attributes in [RFC2911]. That is, the Printer 752 may or may not support an attribute and a client may or may not 753 supply the attribute. Some combinations of these cases are OK. 754 Others return warnings or errors, and perhaps a list of unsupported 755 attributes. 757 A Printer MUST implement the following behavior for processing 758 Subscription Template Attributes in a Subscription Creation Request: 760 1.If a client supplies a "notify-xxx" attribute from column 1 of 761 Table 1 and the Printer supports it and its value, the Printer 762 MUST populate the attribute on the created Subscription Object. 764 2.If a client supplies a "notify-xxx" attribute from column 1 of 765 Table 1 and the Printer doesn't support it or its value, the 766 Printer MUST NOT populate the attribute on the created 767 Subscription Object with it. The Printer MUST do one of the 768 following: 770 a) If the value of the "notify-xxx" attribute is unsupported, the 771 Printer MUST return the attribute with its value in the 772 Subscription Attributes Group of the response. 774 b) If "notify-xxx" is an unsupported attribute, the Printer MUST 775 return the attribute in the Subscription Attributes Group of the 776 response with the 'unsupported' out-of-band value. 778 Note: The rules of this step are the same as for Unsupported 779 Attributes [RFC2911] section 3.1.7. except that the unsupported 780 attributes are returned in the Subscription Attributes Group 781 rather than the Unsupported Attributes Group because Subscription 782 Creation Operations can create more than one Subscription Object). 784 3.If a client is REQUIRED to supply a "notify-xxx" attribute from 785 column 1 of Table 1 and the Printer doesn't support the supplied 786 value, the Printer MUST NOT create a Subscription Object. The 787 rules for Unsupported Attributes in step #2 still apply. 789 4.If a client does not supply a "notify-xxx" attribute from column 1 790 of Table 1 and the attribute is REQUIRED for the client to supply, 791 the Printer MUST reject the Subscription Creation Operation 792 (including Job Creation operations) without creating a 793 Subscription Object, and MUST return in the response: 795 c) the status code 'client-error-bad-request' AND 797 d) no Subscription Attribute Groups. 799 5.If a client does not supply a "notify-xxx" attribute from column 1 800 of Table 1 that is OPTIONAL for the client to supply, and column 2 801 of Table 1 either: 803 a) specifies a "notify-xxx-default" attribute, the Printer MUST 804 behave as if the client had supplied the "notify-xxx-default" 805 attribute (see step #1) and populate the Subscription object 806 with the value of the "notify-xxx-default" attribute as part of 807 the Subscription Creation operation (unlike Job Template 808 attributes where the Printer does not populate the Job object 809 with defaults - see [RFC2911]) OR 811 b) does not specify a "notify-xxx-default" attribute, the Printer 812 MUST populate the "notify-xxx" attribute on the Subscription 813 Object according to the definition of the "notify-xxx" attribute 814 in a section 5.3. For some attributes, the "notify-xxx" is 815 populated with the value of some other attribute, and for 816 others, the "notify-xxx" is NOT populated on the Subscription 817 object at all. 819 6.A Printer MUST create a Subscription Object for each Subscription 820 Template Attributes group in a request unless the Printer: 822 a) encounters some attributes in a Subscription Template Attributes 823 Group that require the Printer not to create the Subscription 824 Object OR 826 b) would create a Per-Job Subscription Object when it doesn't have 827 space for another Per-Job Subscription Object OR 829 c) would create a Per-Printer Subscription Object when it doesn't 830 have space for another Per-Printer Subscription Object. 832 7.A response MUST contain one Subscription Attributes Group for each 833 Subscription Template Attributes Group in the request (and in the 834 same order) whether the Printer creates a Subscription Object from 835 the Subscription Template Attributes Group or not. However, the 836 attributes in each Subscription Attributes Group can be in any 837 order. 839 8.The Printer MUST populate each Subscription Attributes Group of 840 the response such that each contains: 842 a) the "notify-subscription-id" attribute (see section 5.4.1), if 843 and only if the Printer creates a Subscription Object. 845 b) the "notify-lease-duration" attribute (see section 5.3.8), if 846 and only if the Printer creates a Per-Printer Subscription 847 Object. The value of this attribute is the value of the 848 Subscription Object's "notify-lease-duration" attribute. This 849 value MAY be different from the client-supplied value (see 850 section 5.3.8). If a client supplies this attribute in the 851 creation of a Per-Job Subscription Object, it MUST appear in 852 this group with the out-of-band value 'unsupported' to indicate 853 that the Printer doesn't support it in this context. 855 c) all of the unsupported Subscription Template Attributes from 856 step #2. Note, they are not returned in the Unsupported 857 Attributes Group in order to separate the unsupported attributes 858 for each Subscription Object. 860 d) the "notify-status-code" attribute if the Printer does not 861 create the Subscription Object or if there are unsupported 862 attributes from step #2. The possible values of the "notify- 863 status-code" attribute are shown below (see section 13 for more 864 details). The Printer returns the first value in the list below 865 that describes the status. 867 'client-error-uri-scheme-not-supported': the Subscription 868 Object was not created because the scheme of the "notify- 869 recipient-uri" attribute is not supported. See section 870 13.1 for more details about this status code. See step #3 871 in this section for the case that causes this error, and 872 the resulting step #6a) that causes the Printer not to 873 create the Subscription Object. 875 'client-error-attributes-or-values-not-supported': the 876 Subscription Object was not created because the method of 877 the "notify-pull-method" attribute is not supported. See 878 section 13.1 for more details about this status code. See 879 step #3 in this section for the case that causes this 880 error, and the resulting step #6a) that causes the Printer 881 not to create the Subscription Object. 883 'client-error-too-many-subscriptions': the Subscription 884 Object was not created because the Printer has no space for 885 additional Subscription Objects. The client SHOULD try 886 again later. See section 13.3 for more details about this 887 status code. See steps #6b) and #6c) in this section for 888 the cases that causes this error. 890 'successful-ok-too-many-events': the Subscription Object was 891 created without the "notify-events" values included in this 892 Subscription Attributes Group because the "notify-events" 893 attribute contains too many values. See section 13.4 for 894 more details about this status code. See step #2 in this 895 section and section 5.3.3 for the cases that cause this 896 status code. 898 'successful-ok-ignored-or-substituted-attributes' : the 899 Subscription Object was created but some supplied 900 Subscription Template Attributes are unsupported. These 901 unsupported attributes are also in the Subscription 902 Attributes Group. See section 13.5 for more details about 903 this status code. See step #2 in this section for the 904 cases that cause this status code. 906 9.The Printer MUST validate all Subscription Template Attributes and 907 MUST return all unsupported attributes and values in the 908 corresponding Subscription Attributes Group of the response (see 909 step #2) unless it determines that it could not create additional 910 Subscription Objects because of condition #6b) or condition #6c). 911 Then, the Printer NEED NOT validate these additional Subscription 912 Template Attributes and the client MUST NOT expect to find 913 unsupported attributes from step #2 in such additional 914 Subscription Attribute Groups. 916 5.3 Subscription Template Attributes 918 This section contains the Subscription Template Attributes defined 919 for the Subscription and Printer objects. 921 Table 1 below shows the Subscription Template Attributes and has two 922 columns: 924 - Attribute in Subscription Object: the name and attribute syntax 925 of each Subscription Object Attribute that is a Subscription 926 Template Attribute 928 - Default and Supported Printer Attributes: the default attribute 929 and supported Printer attributes that are associated with the 930 attribute in column 1. 932 The "notify-recipient-uri" attribute is for use with Push Delivery 933 Methods. The "notify-pull-method" attribute is for use with Pull 934 Delivery Methods. 936 For Push Delivery Methods, a Printer MUST support all attributes in 937 Table 1 below except for "notify-pull-method" and "notify-attributes" 938 (and "notify-pull-method-supported" and "notify-attributes- 939 supported"). For Pull Delivery Methods, a Printer MUST support all 940 attributes in Table 1 below except for "notify-recipient-uri" and 941 "notify-attributes" (and "notify-schemes-supported" and "notify- 942 attributes-supported"). If a Printer supports both Push and Pull 943 Delivery Methods, then it MUST support both "notify-recipient-uri" 944 and "notify-pull-method" attributes. 946 For Pull Delivery Methods, a client MUST supply "notify-recipient- 947 uri" and MAY omit any of the rest of the attributes in column 1 of 948 Table 1 in a Subscription Creation Request. For Push Delivery 949 Methods, a client MUST supply "notify-pull-method" and MAY omit any 950 of the rest of the attributes in column 1 of Table 1 in a 951 Subscription Creation Request. A client MUST NOT supply both 952 "notify-recipient-uri" and "notify-pull-method" attributes in the 953 same Subscription Creation Request. 955 Note: The Default and Supported Printer attributes listed in column 956 2 of Table 1 do not have separate sections in this specification 957 defining their semantics. Instead, the section for the corresponding 958 Subscription Object attribute (column 1 of Table 1) contains the 959 semantics of these Printer attributes. This approach follows the 960 precedence of the Job Template attributes in section 4.2 of [RFC2911] 961 where the corresponding "xxx-default" and "xxx-supported" Printer 962 attributes are defined in the same section as the "xxx" Job 963 attribute. 965 Table 1 - Subscription Template Attributes 967 Attribute in Subscription Default and Supported Printer 968 Object Attributes 970 notify-recipient-uri (uri) * notify-schemes-supported (1setOf 971 uriScheme) 973 notify-pull-method (type2 notify-pull-method-supported (1setOf 974 keyword) ** type2 keyword) 976 notify-events (1setOf type2 notify-events-default (1setOf type2 977 keyword) keyword) 978 notify-events-supported (1setOf type2 979 keyword) 980 notify-max-events-supported 981 (integer(2:MAX)) 983 notify-attributes (1setOf notify-attributes-supported (1setOf 984 type2 keyword) type2 keyword) 986 notify-user-data 987 (octetString(63)) 989 notify-charset (charset) charset-supported (1setOf charset) 991 notify-natural-language generated-natural-language-supported 992 (naturalLanguage) (1setOf naturalLanguage) 994 notify-lease-duration notify-lease-duration-default 995 (integer(0:MAX)) (integer(0:67108863)) 996 notify-lease-duration-supported 997 (1setOf (integer(0: 67108863) | 998 rangeOfInteger(0:67108863))) 1000 notify-time-interval 1001 (integer(0:MAX)) 1003 * "notify-recipient-uri" is for Push Delivery Methods only. 1004 ** "notify-pull-method" is for Pull Delivery Methods only. 1006 5.3.1 notify-recipient-uri (uri) 1008 This attribute's value is a URL, which is a special case of a URI. 1009 Its value consists of a scheme and an address. The address specifies 1010 the Notification Recipient and the scheme specifies the Push Delivery 1011 Method for each Event Notification associated with this Subscription 1012 Object. 1014 If a Printer supports any Push Delivery Methods, a Printer MUST 1015 support this attribute and return the value as supplied by the client 1016 (no case conversion or other canonicalization) in any operation 1017 response that includes this attribute. 1019 For a Push Delivery Method, a client MUST supply this attribute in a 1020 Subscription Creation Operation. Thus there is no need for a default 1021 Printer attribute. 1023 The URI scheme of the value of this attribute on a Subscription 1024 object MUST be a value of the "notify-schemes-supported (1setOf 1025 uriScheme)" Printer attribute (see section 5.3.1.1). Note: According 1026 to [RFC2396] the ":" terminates the scheme and so is not part of the 1027 scheme. Therefore, values of the "notify-schemes-supported" Printer 1028 attribute do not include the ":" character. 1030 If the client supplies an unsupported scheme in the value of this 1031 attribute, then the Printer MUST NOT create the Subscription Object 1032 and MUST return the "notify-status-code" attribute with the 'client- 1033 error-uri-scheme-not-supported' value in the Subscription Attributes 1034 Group in the response. 1036 The Printer MUST treat the address part of this attribute as opaque. 1038 5.3.1.1 notify-schemes-supported (1setOf uriScheme) 1040 This attribute contains the URI schemes supported in the "notify- 1041 recipient-uri" Subscription Template attribute. See sections 5.1 and 1042 5.2 for the behavior of "xxx-supported" Subscription Template Printer 1043 attributes. 1045 5.3.2 notify-pull-method (type2 keyword) 1047 This attribute's value is a type2 keyword indicating which Pull 1048 Delivery Method is to be used. 1050 Since a Printer MUST support the 'ippget' Pull Delivery Method [ipp- 1051 get-method] (see section 15), a Printer MUST support this attribute 1052 and return the value as supplied by the client in any operation 1053 response that includes this attribute. 1055 For a Pull Delivery Method, a client MUST supply this attribute in a 1056 Subscription Creation Operation. Thus there is no need for a default 1057 Printer attribute. 1059 The keyword value of this attribute on a Subscription object MUST be 1060 a value of the "notify-pull-method-supported (1setOf type2 keyword)" 1061 Printer attribute. 1063 If the client supplies an unsupported method in the value of this 1064 attribute, then the Printer MUST NOT create the Subscription Object 1065 and MUST return the "notify-status-code" attribute with the 'client- 1066 error-attributes-or-values-not-supported' value in the Subscription 1067 Attributes Group in the response. 1069 5.3.2.1 notify-pull-method-supported (1setOf type2 keyword) 1071 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1072 Subscription Template Printer attributes. 1074 5.3.3 notify-events (1setOf type2 keyword) 1076 This attribute contains a set of Subscribed Events. When an Event 1077 occurs and it "matches" a value of this attribute, the Printer 1078 delivers an Event Notification using information in the Subscription 1079 Object. The details of "matching" are described subsection 5.3.3.5. 1081 A Printer MUST support this attribute. 1083 A client MAY supply this attribute in a Subscription Creation 1084 Operation. If the client does not supply this attribute in 1085 Subscription Creation Operation, the Printer MUST populate this 1086 attribute on the Subscription Object with its "notify-events-default" 1087 attribute value. 1089 Each keyword value of this attribute on a Subscription Object MUST be 1090 a value of the "notify-events-supported (1setOf type2 keyword)" 1091 Printer attribute. 1093 The number of values of this attribute MUST NOT exceed the value of 1094 the "notify-max-events-supported" attribute. A Printer MUST support 1095 at least 2 values per Subscription Object. If the number of values 1096 supplied by a client in a Subscription Creation Operation exceeds the 1097 value of this attribute, the Printer MUST treat extra values as 1098 unsupported values and MUST use the value of 'successful-ok-too-many- 1099 events' for the "notify-status-code" attribute in the Subscription 1100 Attributes Group of the response. 1102 5.3.3.1 notify-events-default (1setOf type2 keyword) 1104 See sections 5.1 and 5.2 for the behavior of "xxx-default" 1105 Subscription Template Printer attributes. 1107 5.3.3.2 notify-events-supported (1setOf type2 keyword) 1109 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1110 Subscription Template Printer attributes. 1112 5.3.3.3 notify-max-events-supported (integer(2:MAX)) 1114 This attribute specified the maximum number of events that the 1115 Printer supports for the "notify-events" Subscription Template 1116 attribute. See sections 5.1 and 5.2 for the behavior of "xxx- 1117 supported" Subscription Template Printer attributes. 1119 5.3.3.4 Standard Values for Subscribed Events 1121 Each value of this attribute is a keyword and it specifies a 1122 Subscribed Event that represents certain changes. Some keywords 1123 represent a subset of changes of another keyword, e.g., 'job- 1124 completed' is an Event value which is a sub-value of 'job-state- 1125 change'. See section 5.3.3.5 for the case where this attribute 1126 contains both a value and a sub-value. 1128 The values in this section are divided into three categories: No 1129 Events, Job Events and Printer Events. 1131 A Printer MUST support the Events indicated as "REQUIRED" and MAY 1132 support the Events indicated as "OPTIONAL". 1134 5.3.3.4.1 No Events 1136 The standard and only keyword value for No Events is: 1138 'none': REQUIRED - no Event Notifications for any Events. As the 1139 sole value of "notify-events-supported", this value means that the 1140 Printer does not support the delivery of Event Notifications. As 1141 the sole value of "notify-events-default", this value means that a 1142 client MUST specify the "notify-events" attribute in order for a 1143 Subscription Creation Operation to succeed. If the Printer 1144 receives this value as the sole value of a Subscription Creation 1145 Operation, it does not create a Subscription Object. If a Printer 1146 receives this value with other values of a Subscription Creation 1147 Operation, the Printer MUST treat this value as an unsupported 1148 value. 1150 5.3.3.4.2 Subscribed Printer Events 1152 The standard keyword values for Subscribed Printer Events are: 1154 'printer-state-changed': REQUIRED - the Printer changed state from 1155 any state to any other state. Specifically, the value of the 1156 Printer's "printer-state", "printer-state-reasons" or "printer-is- 1157 accepting-jobs" attributes changed. 1159 This Subscribed Event value has the following sub-values: 1160 'printer-restarted' and 'printer-shutdown'. A client can listen 1161 for any of these sub-values if it doesn't want to listen to all 1162 printer-state changes: 1164 'printer-restarted': OPTIONAL - when the printer is powered 1165 up . 1167 'printer-shutdown': OPTIONAL - when the device is being 1168 powered down . 1170 'printer-stopped: REQUIRED - when the printer stops printing, 1171 i.e. the value of the "printer-state" Printer attribute 1172 becomes 'stopped'. 1174 'printer-config-changed': OPTIONAL - when the configuration of a 1175 Printer has changed, i.e., the value of the "printer-message-from- 1176 operator" or any "configuration" Printer attribute has changed. A 1177 "configuration" Printer attribute is an attribute which can change 1178 value because of some human interaction either direct or indirect, 1179 and which is not covered by one of the other Events in this 1180 section. Examples of "configuration" Printer attributes are any 1181 of the Job Template attributes, such as "xxx-supported", "xxx- 1182 ready" and "xxx-default". The client has to perform a Get- 1183 Printer-Attributes to find out the new values of these changed 1184 attributes. This Event is useful for GUI clients and drivers to 1185 update the available printer capabilities to the user. 1187 This Event value has the following sub-values: 'printer-media- 1188 changed' and 'printer-finishings-changed'. A client can listen 1189 for any of these sub-values if it doesn't want to listen to all 1190 printer-configuration changes: 1192 'printer-media-changed': OPTIONAL - when the media loaded on 1193 a printer has been changed, i.e., the "media-ready" 1194 attribute has changed. This Event includes two cases: an 1195 input tray that goes empty and an input tray that receives 1196 additional media of the same type or of a different type. 1197 The client must check the "media-ready" Printer attribute 1198 (see [RFC2911] section 4.2.11) separately to find out what 1199 changed. 1201 'printer-finishings-changed': OPTIONAL - when the finisher on 1202 a printer has been changed, i.e., the "finishings-ready" 1203 attribute has changed. This Event includes two cases: a 1204 finisher that goes empty and a finisher that is refilled 1205 (even if it is not full). The client must check the 1206 "finishings-ready" Printer attribute separately to find out 1207 what changed. 1209 'printer-queue-order-changed': OPTIONAL - the order of jobs in the 1210 Printer's queue has changed, so that an application that is 1211 monitoring the queue can perform a Get-Jobs operation to determine 1212 the new order. This Event does not include when a job enters the 1213 queue (the 'job-created' Event covers that) and does not include 1214 when a job leaves the queue (the 'job-completed' Event covers 1215 that). 1217 5.3.3.4.3 Subscribed Job Events 1219 The standard keyword values for Subscribed Job Events are: 1221 'job-state-changed': REQUIRED - the job has changed from any state 1222 to any other state. Specifically, the Printer delivers this Event 1223 whenever the value of the "job-state" attribute or "job-state- 1224 reasons" attribute changes. When a Job is removed from the Job 1225 Retention or Job History phases (see [RFC2911] section 4.3.7.1), 1226 no Event is generated. 1228 This Event value has the following sub-values: 'job-created', 1229 'job-completed' and 'job-stopped'. A client can listen for any of 1230 these sub-values if it doesn't want to listen to all 'job-state 1231 changes'. 1233 'job-created': REQUIRED - the Printer has accepted a Job 1234 Creation operation, a Restart-Job operation [RFC2911], or 1235 any job operation that creates a Job object from an 1236 existing Job object. The Printer populates the job's 1237 "time-at-creation" attribute value (see [RFC2911] section 1238 4.3.14.1). The Printer puts the job in the 'pending', 1239 'pending-held' or 'processing' states. 1241 'job-completed': REQUIRED - the job has reached one of the 1242 completed states, i.e., the value of the job's "job-state" 1243 attribute has changed to: 'completed', 'aborted', or 1244 'canceled'. The Job's "time-at-completed" and "date-time- 1245 at-completed" (if supported) attributes are set (see 1246 [RFC2911] section 4.3.14). When a Job completes, a 1247 Notification Recipient MAY query the Job using the Get-Job- 1248 Attributes operation. To allow such a query, the Printer 1249 retains the Job in the Job Retention and/or the Job History 1250 phases (see [RFC2911] section 4.3.7.1) for a suitable 1251 amount of time that depends on implementation and the 1252 Delivery Methods supported. The Printer also delivers this 1253 Event when a Job is removed with the Purge-Job operation 1254 (see [RFC2911] section 3.2.9). In this case, the Event 1255 Notification MUST report the 'job-state' as 'canceled' and 1256 the Job object is no longer present for query. 1258 'job-stopped: OPTIONAL - when the job stops printing, i.e. 1259 the value of the "job-state" Job attribute becomes 1260 'processing-stopped'. 1262 'job-config-changed': OPTIONAL - when the configuration of a job has 1263 changed, i.e., the value of the "job-message-from-operator" or any 1264 of the "configuration" Job attributes have changed. A 1265 "configuration" Job attribute is an attribute that can change 1266 value because of some human interaction either direct or indirect. 1267 Examples of "configuration" Job attributes are any of the job 1268 template attributes and the "job-name" attribute. The client 1269 performs a Get-Job-Attributes to find out the new values of the 1270 changed attributes. This Event is useful for GUI clients and 1271 drivers to update the job information to the user. 1273 'job-progress': OPTIONAL - when the Printer has completed Printing a 1274 sheet. See the separate [RFC3381] specification for additional 1275 attributes that a Printer MAY deliver in an Event Notification 1276 caused by this Event. The "notify-time-interval" attribute 1277 affects this Event by causing the Printer NOT to deliver an Event 1278 Notification every time a 'job-progress' Events occurs. See 1279 section 5.3.9 for full details. 1281 5.3.3.5 Rules for Matching of Subscribed Events 1283 When an Event occurs, the Printer MUST find each Subscription object 1284 whose "notify-events" attribute "matches" the Event. The rules for 1285 "matching" of Subscribed Events are described separately for Printer 1286 Events and for Job Events. This section also describes some special 1287 cases. 1289 5.3.3.5.1 Rules for Matching of Printer Events 1291 Given that the Printer causes Printer Event E to occur, for each 1292 Per-Job or Per-Printer Subscription S in the Printer, if E equals a 1293 value of this attribute in S or E is a sub-value of a value of this 1294 attribute in S, the Printer MUST generate an Event Notification. 1296 Consider the example. There are three Subscription Objects each with 1297 the Subscribed Printer Event 'printer-state-changed'. Subscription 1298 Object A is a Per-Printer Subscription Object. Subscription Object B 1299 is a Per-Job Subscription Object for Job 1, and Subscription Object C 1300 is a Per-Job Subscription Object for Job 2. When the Printer enters 1301 the 'stopped' state, the Printer delivers an Event Notification to 1302 the Notification Recipients of Subscription Objects A, B, and C 1303 because this is a Printer Event. Note if Job 1 has already 1304 completed, the Printer would not deliver an Event Notification for 1305 its Subscription Object, even if Job 1 is retained in the Job 1306 Retention and/or the Job History phases (see [RFC2911] section 1307 4.3.7.1). 1309 5.3.3.5.2 Rules for Matching of Job Events 1311 Given that Job J causes Job Event E to occur: 1313 1.For each Per-Printer Subscription S in the Printer, if E equals 1314 a value of this attribute in S or E is a sub-value of a value of 1315 this attribute in S, the Printer MUST generate an Event 1316 Notification. 1318 2.For each Per-Job Subscription S associated with Job J, if E 1319 equals a value of this attribute in S or E is a sub-value of a 1320 value of this attribute in S, the Printer MUST generate an Event 1321 Notification. 1323 3.For each Per-Job Subscription S that is NOT associated Job J, if 1324 E equals a value of this attribute in S or E is a sub-value of a 1325 value of this attribute in, the Printer MUST NOT generate an 1326 Event Notification from S. 1328 Consider the example: There are three Subscription Objects listening 1329 for the Job Event 'job-completed'. Subscription Object A is a Per- 1330 Printer Subscription Object. Subscription Object B is a Per-Job 1331 Subscription Object for Job 1, and Subscription Object C is a Per-Job 1332 Subscription Object for Job 2. In addition, Per-Printer Subscription 1333 Object D is listening for the Job Event 'job-state-changed'. When 1334 Job 1 completes, the Printer delivers an Event Notification to the 1335 Notification Recipient of Subscription Object A (because it is Per- 1336 Printer) and Subscription Object B because it is a Per-Job 1337 Subscription Object associated with the Job generating the Event. 1338 The Printer also delivers an Event Notification to the Notification 1339 Recipient of Subscription Object D because 'job-completed' is a sub- 1340 value of 'job-state-changed' - the value that Subscription Object D 1341 is listening for. The Printer does not deliver an Event Notification 1342 to the Notification Recipients of Subscription Object C because it is 1343 a Per-Job Subscription Object associated with some Job other than the 1344 Job generating the Event. 1346 5.3.3.5.3 Special Cases for Matching Rules 1348 This section contains rule for special cases. 1350 If an Event matches Subscribed Events in two different Subscription 1351 Objects and the Printer would deliver two identical Event 1352 Notifications (except for the "notify-subscription-id" attribute) to 1353 the same Notification Recipient using the same Delivery Method, the 1354 Printer MUST deliver both Event Notifications. That is, the Printer 1355 MUST NOT try to consolidate seemingly identical Event Notifications 1356 that occur in separate Subscription objects. Incidentally, the 1357 Printer MUST NOT reject Subscription Creation Operations that would 1358 create this scenario. 1360 If an Event matches two values of this "notify-events" attribute in a 1361 single Subscription object (e.g., a value and its sub-value), a 1362 Printer MAY deliver one Event Notification for each matched value in 1363 the Subscription Object or it MAY deliver only one Event Notification 1364 per Subscription Object. The rules in sections 5.3.3.5.1 and 1365 5.3.3.5.2 are purposefully flexible about the number of Event 1366 Notifications sent when Event E matches two or more values in a 1367 Subscription Object. 1369 Consider the example: There are two Per-Printer Subscription Objects 1370 when a Job completes. Subscription Object A has the Subscribed Job 1371 Event 'job-state-changed'. Subscription Object B has the Subscribed 1372 Job Events 'job-state-changed' and 'job-completed'. The Printer 1373 delivers an Event Notification to the Notification Recipient of 1374 Subscription Object A with the value of 'job-state-changed' for the 1375 "notify-subscribing-event" attribute. The Printer delivers either 1376 one or two Event Notifications to the Notification Recipient of 1377 Subscription Object B, depending on implementation. If it delivers 1378 two Event Notifications, one has the value of 'job-state-changed' 1379 for the "notify-subscribing-event" attribute, and the other has the 1380 value of 'job-completed' for the "notify-subscribing-event" 1381 attribute. If it delivers one Event Notification, it has the value 1382 of either 'job-state-changed' or 'job-completed' for the "notify- 1383 subscribing-event" attribute, depending on implementation. The 1384 algorithm for choosing such a value is implementation dependent. 1386 5.3.4 notify-attributes (1setOf type2 keyword) 1388 This attribute contains a set of attribute names. When a Printer 1389 delivers a Machine Consumable Event Notification, it includes a fixed 1390 set of attributes (see section 9.1). If this attribute is present 1391 and the Event Notification is Machine Consumable, the Printer also 1392 includes the attributes specified by this attribute. 1394 A Printer MAY support this attribute. 1396 A client MAY supply this attribute in a Subscription Creation 1397 Operation. If the client does not supply this attribute in 1398 Subscription Creation Operation or the Printer does not support this 1399 attribute, the Subscription Object either (1) MAY contain the 1400 "notify-attributes" attribute with a 'none' value or (2) NEED NOT 1401 contain the attribute at all. There is no "notify-attributes- 1402 default" Printer attribute. 1404 Each keyword value of this attribute on a Subscription Object MUST be 1405 a value of the "notify-attributes-supported (1setOf type2 keyword)" 1406 Printer attribute (see section 5.3.4.1). The "notify-attributes- 1407 supported" MAY contain any Printer attribute, Job attribute or 1408 Subscription Object attribute that the Printer supports in an Event 1409 Notification. It MUST NOT contain any of the attributes in Section 1410 9.1 that a Printer automatically puts in an Event Notification; it 1411 would be redundant. If a client supplies an attribute in Section 1412 9.1, the Printer MUST treat it as an unsupported attribute value of 1413 the "notify-attributes" attribute. 1415 The following rules apply to each keyword value N of the "notify- 1416 attributes" attribute: If the value N names: 1418 a)a Subscription attribute, the Printer MUST use the attribute N in 1419 the Subscription Object that is being used to generate the Event 1420 Notification. 1422 b)a Job attribute and the Printer is generating an Event 1423 Notification from a Per-Job Subscription Object S, the Printer 1424 MUST use the attribute N in the Job object associated with S. 1426 c)a Job attribute and the Printer is generating an Event 1427 Notification from a Per-Printer Subscription Object and the Event 1428 is: 1430 ? a Job Event, the Printer MUST use the attribute N in the Job 1431 object that caused the Event. 1433 ? a Printer Event, the Printer MUST use the attribute N in the 1434 active Job. 1436 If a Printer supports this attribute and a Subscription Object 1437 contains this attribute and the Delivery Method generates a Machine 1438 Consumable Event Notification, the Printer MUST include in each Event 1439 Notification: 1441 a)the attributes specified in section 9.1 and 1443 b)each attribute named by this attribute. 1445 The Printer MUST NOT use this attribute to generate a Human 1446 Consumable Event Notification. 1448 5.3.4.1 notify-attributes-supported (1setOf type2 keyword) 1450 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1451 Subscription Template Printer attributes. 1453 5.3.5 notify-user-data (octetString(63)) 1455 This attribute contains opaque data that some Delivery Methods 1456 include in each Machine Consumable Event Notification. The opaque 1457 data might contain, for example: 1459 - the identity of the Subscriber 1461 - a path or index to some Subscriber information 1463 - a key that identifies to the Notification Recipient the 1464 ultimate recipient of the Event Notification 1466 - the id for a Notification Recipient that had previously 1467 registered with an Instant Messaging Service 1469 A Printer MUST support this attribute. 1471 A client MAY supply this attribute in a Subscription Creation 1472 Operation. If the client does not supply this attribute in the 1473 Subscription Creation Operation, the Subscription Object either (1) 1474 MAY contain the "notify-user-data" attribute with a zero length value 1475 or (2) NEED NOT contain the attribute at all. There is no "notify- 1476 user-data-default" Printer attribute. 1478 There is no "notify-user-data-supported" Printer attribute. Rather, 1479 any octetString whose length does not exceed 63 octets is a supported 1480 value. If the length exceeds 63 octets, the Printer MUST treat it as 1481 an unsupported value. 1483 5.3.6 notify-charset (charset) 1485 This attribute specifies the charset to be used in the Event 1486 Notification content sent to the Notification Recipient, whether the 1487 Event Notification content is Machine Consumable or Human Consumable. 1489 A Printer MUST support this attribute. 1491 A client MAY supply this attribute in a Subscription Creation 1492 Operation. If the client does not supply this attribute in 1493 Subscription Creation Operation or supplies an unsupported value, the 1494 Printer MUST populate this attribute in the Subscription Object with 1495 the value of the "attributes-charset" operation attribute, which is a 1496 REQUIRED attribute in all IPP requests (see [RFC2911]). If the value 1497 of the "attributes-charset" attribute is unsupported, the Printer 1498 MUST populate this attribute in the Subscription Object with the 1499 value of the Printer's "charset-configured" attribute. There is no 1500 "notify-charset-default" Printer attribute. 1502 The value of this attribute on a Subscription Object MUST be a value 1503 of the "charset-supported (1setOf charset)" Printer attribute. 1505 5.3.7 notify-natural-language (naturalLanguage) 1507 This attribute specifies the natural language to be used in any human 1508 consumable text in the Event Notification content sent to the 1509 Notification Recipient, whether the Event Notification content is 1510 Machine Consumable or Human Consumable. 1512 A Printer MUST support this attribute. 1514 A client MAY supply this attribute in a Subscription Creation 1515 Operation. If the client does not supply this attribute in 1516 Subscription Creation Operation or supplies an unsupported value, the 1517 Printer MUST populate this attribute in the Subscription Object with 1518 the value of the "attributes-natural-language" operation attribute, 1519 which is a REQUIRED attribute in all IPP requests (see [RFC2911] 1520 section 3.1.4). If the value of the "attributes-natural-language" 1521 attribute is unsupported, the Printer MUST populate this attribute in 1522 the Subscription Object with the value of the Printer's "natural- 1523 language-configured" attribute (see [RFC2911] section 4.4.19). There 1524 is no "notify-natural-language-default" Printer attribute. 1526 The value of this attribute on a Subscription Object MUST be a value 1527 of the "generated-natural-language-supported (1setOf type2 1528 naturalLanguage)" Printer attribute (see [RFC2911] section 4.4.20). 1530 5.3.8 notify-lease-duration (integer(0:67108863)) 1532 This attribute specifies the duration of the lease (in seconds) 1533 associated with the Per-Printer Subscription Object at the time the 1534 Subscription Object was created or the lease was renewed. The 1535 duration of the lease is infinite if the value is 0, i.e., the lease 1536 never expires. See section 5.4.3 on "notify-lease-expiration-time 1537 (integer(0:MAX))" for more details. 1539 This attribute is not present on a Per-Job Subscription Object 1540 because the Subscription Object lasts exactly as long as the 1541 associated Job object. See discussion of the 'job-completed' event 1542 in section 5.3.3.4.3 about retention of the Job object after 1543 completion. 1545 A Printer MUST support this attribute. 1547 For a Subscription Object Creation operation of a Per-Job 1548 Subscription Object, the client MUST NOT supply this attribute. If 1549 the client does supply this attribute, the Printer MUST treat it as 1550 an unsupported attribute. 1552 For a Subscription Creation Operation of a Per-Printer Subscription 1553 Object or a Renew-Subscription operation, a client MAY supply this 1554 attribute. If the client does not supply this attribute, the Printer 1555 MUST populate this attribute with its "notify-lease-duration-default" 1556 (0:67108863) attribute value. If the client supplies this attribute 1557 with an unsupported value, the Printer MUST populate this attribute 1558 with a supported value, and this value SHOULD be as close as possible 1559 to the value requested by the client. Note: this rule implies that a 1560 Printer doesn't assign the value of 0 (infinite) unless the client 1561 requests it. 1563 After the Printer has populated this attribute with a supported 1564 value, the value represents the "granted duration" of the lease in 1565 seconds and the Printer updates the value of the Subscription 1566 Object's "notify-lease-expiration-time" attribute as specified in 1567 section 5.4.3. 1569 The value of this attribute on a Subscription Object MUST be a value 1570 of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) 1571 | rangeOfInteger(0:67108863))) Printer attribute. 1573 A Printer MAY require authentication in order to return the value of 1574 0 (the lease never expires) as one of the values of "notify-lease- 1575 duration-supported", and to allow 0 as a value of the "notify-lease- 1576 duration" attribute. 1578 Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1579 1 and is about 2 years in seconds. The value is considerably less 1580 than MAX so that there is virtually no chance of an overflow when the 1581 Printer adds it to the Printer's "printer-up-time" attribute value 1582 (see [RFC2911] section 4.4.29) to produce the "notify-lease- 1583 expiration-time" Subscription Description attribute value (see 1584 section 5.4.3). 1586 5.3.8.1 notify-lease-duration-default (integer(0:67108863)) 1588 See sections 5.1 and 5.2 for the behavior of "xxx-default" 1589 Subscription Template Printer attributes. 1591 5.3.8.2 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 1592 rangeOfInteger(0:67108863))) 1594 See sections 5.1 and 5.2 for the behavior of "xxx-supported" 1595 Subscription Template Printer attributes. 1597 5.3.9 notify-time-interval (integer(0:MAX)) 1599 The 'job-progress' Event occurs each time that a Printer completes a 1600 sheet. Some Notification Recipients do not want to receive an Event 1601 Notification every time this Event occurs. This attribute allows a 1602 Subscribing Client to request how often it wants to receive Event 1603 Notifications for 'job-progress' Events. The value of this attribute 1604 MAY be any nonnegative integer (0,MAX) indicating the minimum number 1605 of seconds between 'job-progress' Event Notifications. 1607 The Printer MUST support this attribute if and only if the Printer 1608 supports the 'job-progress' Event. 1610 A client MAY supply this attribute in a Subscription Creation 1611 Operation. If the client does not supply this attribute in the 1612 Subscription Creation Operation, the Subscription Object either (1) 1613 MAY contain the "notify-time-interval" attribute with a '0' value or 1614 (2) NEED NOT contain this attribute at all. There is no "notify- 1615 time-interval-default" Printer attribute. 1617 There is no "notify-time-interval-supported" Printer attribute. 1619 If the 'job-progress' Event occurs and a Subscription Object contains 1620 the 'job-progress' Event as a value of the 'notify-events' attribute, 1621 there are two cases to consider: 1623 1.This attribute is not present on the Subscription Object or has 1624 the value of 0. The Printer MUST generate and deliver an Event 1625 Notification (as is the case with other Events). 1627 2.This attribute is present with a nonzero value of N: 1629 a)If the Printer has not sent an Event Notification for the 'job- 1630 progress' Event for the associated Subscription Object within 1631 the past N seconds, the Printer MUST deliver an Event 1632 Notification for the Event that just occurred. Note when the 1633 Printer completes the first page of a Job, this rule implies 1634 that the Printer delivers an Event Notification for a Per-Job 1635 Subscription Object. 1637 b)Otherwise, the Printer MUST NOT generate or deliver an Event 1638 Notification for the associated Subscription Object. The 1639 Printer MUST NOT increase the value of the "notify-sequence- 1640 number" Subscription Object attribute (i.e., the sequence of 1641 values of the "notify-sequence-number" attribute counts the 1642 Event Notifications that the Printer sent and not the Events 1643 that do not cause an Event Notification to be sent). 1645 It is RECOMMENDED that a Subscribing Client use this attribute when 1646 it subscribes to the 'job-progress' Event, and that the value be 1647 sufficiently large to limit the frequency with which the Printer 1648 delivers Event Notifications requests. 1650 This attribute MUST NOT effect any Events other than 'job-progress'. 1652 5.4 Subscription Description Attributes 1654 Subscription Description Attributes are those attributes that a 1655 Printer adds to a Subscription Object at the time of its creation. 1657 A Printer MUST support all attributes in this Table 2. 1659 A client MUST NOT supply the attributes in Table 2 in a Subscription 1660 Template Attributes Group of a Subscription Creation Operation. 1661 There are no corresponding default or supported attributes. 1663 Table 2 - Subscription Description Attributes 1665 Subscription Object attributes: 1667 notify-subscription-id (integer(1:MAX)) 1669 notify-sequence-number (integer(0:MAX)) 1671 notify-lease-expiration-time (integer(0:MAX)) 1673 notify-printer-up-time (integer(1:MAX)) 1675 notify-printer-uri (uri) 1677 notify-job-id (integer(1:MAX)) 1679 notify-subscriber-user-name (name(MAX)) 1681 5.4.1 notify-subscription-id (integer (1:MAX)) 1683 This attribute identifies a Subscription Object instance with a 1684 number that is unique within the context of the Printer. The Printer 1685 generates this value at the time it creates the Subscription Object. 1687 A Printer MUST support this attribute. 1689 The Printer MAY assign the value of this attribute sequentially as it 1690 creates Subscription Objects. However, if there is no security on 1691 Subscription objects, sequential assignment exposes the system to a 1692 passive traffic monitoring threat. 1694 The Printer SHOULD avoid re-using recent values of this attribute 1695 during continuous operation of the Printer as well as across power 1696 cycles. Then a Subscribing Client is unlikely to find that a stale 1697 reference accesses a new Subscription Object. 1699 The 0 value is not permitted in order to allow for compatibility with 1700 "job-id" and with SNMP index values, which also cannot be 0. 1702 5.4.2 notify-sequence-number (integer (0:MAX)) 1704 The value of this attribute indicates the number of times that the 1705 Printer has generated and attempted to deliver an Event Notification 1706 for this Subscription object. When an Event Notification contains 1707 this attribute, the Notification Recipient can determine whether it 1708 missed some Event Notifications (i.e., numbers skipped) or received 1709 duplicates (i.e., same number twice). 1711 A Printer MUST support this attribute. 1713 When the Printer creates a Subscription Object, it MUST populate this 1714 attribute with a value of 0. This value indicates that the Printer 1715 has not sent any Event Notifications for this Subscription Object. 1717 Each time the Printer delivers a newly generated Event Notification, 1718 it MUST increase the value of this attribute by 1. For some Delivery 1719 Methods, the Printer MUST include this attribute in each Event 1720 Notification, and the value MUST be the value after it is increased 1721 by 1. That is, the value of this attribute in the first Event 1722 Notification after Subscription object creation MUST be 1, the second 1723 MUST be 2, etc. If a Delivery Method is defined such that the 1724 Notification Recipient returns a response, the Printer can re-try 1725 delivering an Event Notification a certain number of times with the 1726 same sequence number when the Notification Recipient fails to return 1727 a response. 1729 If a Subscription Object lasts long enough to reach the value of MAX, 1730 its next value MUST be 0, i.e., it wraps. 1732 5.4.3 notify-lease-expiration-time (integer(0:MAX)) 1734 This attribute specifies the time in the future when the lease on the 1735 Per-Printer Subscription Object will expire, i.e. the "printer-up- 1736 time" value at which the lease will expire. If the value is 0, the 1737 lease never expires. 1739 A Printer MUST support this attribute. 1741 When the Printer creates a Per-Job Subscription Object, this 1742 attribute MUST NOT be present - the Subscription Object lasts exactly 1743 as long as the associated Job object. See also the discussion of the 1744 'job-completed' event in section 5.3.3.4.3 about retention of the Job 1745 object after completion so that a Notification Recipient can query 1746 the Job object after receiving the 'job-completed' Event 1747 Notification. 1749 When the Printer creates a Per-Printer Subscription Object, it 1750 populates this attribute with a value that is the sum of the values 1751 of the Printer's "printer-up-time" attribute and the Subscription 1752 Object's "notify-lease-duration" attribute with the following 1753 exception. If the value of the Subscription Object's "notify-lease- 1754 duration" attribute is 0 (i.e., no expiration time), then the value 1755 of this attribute MUST be set to 0 (i.e., no expiration time). 1757 When the Printer powers up, it MUST populate this attribute in each 1758 persistent Subscription Object with a value using the algorithm in 1759 the previous paragraph. 1761 When the "printer-up-time" equals the value of this attribute, the 1762 Printer MUST delete the Subscription Object. A client can extend a 1763 lease of a Per-Printer Subscription Object with the Renew- 1764 Subscription operation (see section 11.2.6). 1766 Note: In order to compute the number of seconds remaining in a lease 1767 for a Per-Printer Subscription Object, a client can subtract the 1768 Subscription's "notify-printer-up-time" attribute (see section 5.4.4) 1769 from the Subscription's "notify-lease-expiration-time" attribute. 1771 5.4.4 notify-printer-up-time (integer(1:MAX)) 1773 This attribute is an alias for the Printer's "printer-up-time" 1774 attribute " (see [RFC2911] section 4.4.29). In other words, when 1775 this attribute is queried with the Get-Subscriptions or Get- 1776 Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), 1777 the value returned is the current value of the Printer's "printer-up- 1778 time" attribute, rather than the time at which the Subscription 1779 Object was created. 1781 A Printer MUST support this attribute. 1783 When the Printer creates a Per-Job Subscription Object, this 1784 attribute MUST NOT be present. When the Printer creates a Per- 1785 Printer Subscription Object, this attribute MUST be present. 1787 Note: this attribute exists in a Per-Printer Subscription Object so 1788 that a client using the Get-Subscription-Attributes or Get- 1789 Subscription operations can convert the Per-Printer Subscription's 1790 "notify-lease-expiration-time" attribute to wall clock time with one 1791 request. If the value of the "notify-lease-expiration-time" 1792 attribute is not 0 (i.e., no expiration time), then the difference 1793 between the "notify-lease-expiration-time" attribute and the "notify- 1794 printer-up-time" is the remaining number of seconds on the lease from 1795 the current time. 1797 5.4.5 notify-printer-uri (uri) 1799 This attribute identifies the Printer object that created this 1800 Subscription Object. 1802 A Printer MUST support this attribute. 1804 During a Subscription Creation Operation, the Printer MUST populate 1805 this attribute with the value of the "printer-uri" operation 1806 attribute in the request. From the Printer URI, the client can, for 1807 example, determine what security scheme was used. 1809 5.4.6 notify-job-id (integer(1:MAX)) 1811 This attribute specifies whether the containing Subscription Object 1812 is a Per-Job or Per-Printer Subscription Object, and for Per-Job 1813 Subscription Objects, it specifies the associated Job. 1815 A Printer MUST support this attribute. 1817 If this attribute is not present, the Subscription Object MUST be a 1818 Per-Printer Subscription. If this attribute is present, the 1819 Subscription Object MUST be a Per-Job Subscription Object and this 1820 attribute MUST identify the Job with which the Subscription Object is 1821 associated. 1823 Note: This attribute could be useful to a Notification Recipient that 1824 receives an Event Notification generated from a Per-Job Subscription 1825 Object and caused by a Printer Event. The Event Notification gives 1826 access to the Printer and the Subscription Object. The Event 1827 Notification gives access to the associated Job only via this 1828 attribute. See discussion of the 'job-completed' event in section 1829 5.3.3.4.3 about retention of the Job object after completion so that 1830 a Notification Recipient can query the Job object after receiving the 1831 'job-completed' Event Notification. 1833 5.4.7 notify-subscriber-user-name (name(MAX)) 1835 This attribute contains the name of the user who performed the 1836 Subscription Creation Operation. 1838 A Printer MUST support this attribute. 1840 The Printer MUST populates this attribute with the most authenticated 1841 printable name that it can obtain from the authentication service 1842 over which the Subscription Creation Operation was received. The 1843 Printer uses the same mechanism for determining the value of this 1844 attribute as it does for a Job's "job-originating-user-name" (see 1845 [RFC2911] section 4.3.6). 1847 Note: To help with authentication, a Subscription Object may have 1848 additional private attributes about the user, e.g., a credential of a 1849 principal. Such private attributes are implementation-dependent and 1850 not defined in this document. 1852 6 Printer Description Attributes Related to Notification 1854 This section defines the Printer Description attributes that are 1855 related to Notification. Table 3 lists the Printer Description 1856 attributes, indicates the Printer support required for conformance, 1857 and whether or not the attribute is READ-ONLY (see section 3.1): 1859 Table 3 - Printer Description Attributes Associated with Notification 1861 Printer object attributes: REQUIRED READ-ONLY 1863 printer-state-change-time (integer(1:MAX)) No Yes 1865 printer-state-change-date-time (dateTime) No Yes 1867 6.1 printer-state-change-time (integer(1:MAX)) 1869 This OPTIONAL attribute records the most recent time at which the 1870 'printer-state-changed' Printer Event occurred whether or not any 1871 Subscription objects were listening for this event. This attribute 1872 helps a client or operator to determine how long the Printer has been 1873 in its current state. 1875 A Printer MAY support this attribute and if so, the attribute MUST be 1876 READ-ONLY. 1878 On power-up, the Printer MUST populate this attribute with the value 1879 of its "printer-up-time" attribute, so that it always has a value. 1880 Whenever the 'printer-state-changed' Printer Event occurs, the 1881 Printer MUST update this attribute with the value of the Printer's 1882 "printer-up-time" attribute. 1884 6.2 printer-state-change-date-time (dateTime) 1886 This OPTIONAL attribute records the most recent time at which the 1887 'printer-state-changed' Printer Event occurred whether or not there 1888 were any Subscription Objects listening for this event. This 1889 attribute helps a client or operator to determine how long the 1890 Printer has been in its current state. 1892 A Printer MAY support this attribute and if so, the attribute MUST be 1893 READ-ONLY. 1895 On power-up, the Printer MUST populate this attribute with the value 1896 of its "printer-current-time" attribute, so that it always has a 1897 value (see [RFC2911] section 4.4.30 on "printer-current-time"). 1898 Whenever the 'printer-state-changed' Printer Event occurs, the 1899 Printer MUST update this attribute with the value of the Printer's 1900 "printer-current-time" attribute. 1902 7 New Values for Existing Printer Description Attributes 1904 This section contains those attributes for which additional values 1905 are added. 1907 7.1 operations-supported (1setOf type2 enum) 1909 The following "operation-id" values are added in order to support the 1910 new operations defined in this document: 1912 Table 4 - Operation-id assignments 1914 Value Operation Name 1916 0x0016 Create-Printer-Subscriptions 1918 0x0017 Create-Job-Subscriptions 1920 0x0018 Get-Subscription-Attributes 1922 0x0019 Get-Subscriptions 1924 0x001A Renew-Subscription 1926 0x001B Cancel-Subscription 1928 8 Attributes Only in Event Notifications 1930 This section contains those attributes that exist only in Event 1931 Notifications and do not exist in any objects. 1933 8.1 notify-subscribed-event (type2 keyword) 1935 This attribute indicates the Subscribed Event that caused the Printer 1936 to deliver this Event Notification. This attribute exists only in 1937 Event Notifications. 1939 This attribute MUST contain one of the values of the "notify-events" 1940 attribute in the Subscription Object, i.e., one of the Subscribed 1941 Event values. Its value is the Subscribed Event that "matches" the 1942 Event that caused the Printer to deliver this Event Notification. 1943 This Subscribed Event value may be identical to the Event or the 1944 Event may be a sub-value of the Subscribed Event. For example, the 1945 'job-completed' Event (which is a sub-event of the 'job-state- 1946 changed' event) would cause the Printer to deliver an Event 1947 Notification for either the 'job-completed' or 'job-state-changed' 1948 Subscribed Events and to deliver the 'job-completed' or 'job-state- 1949 changed' value for this attribute, respectively. See section 5.3.3.5 1950 for the "matching" rules of Subscribed Events and for additional 1951 examples. 1953 The Delivery Method Document specifies whether the Printer includes 1954 the value of this attribute in an Event Notification. 1956 8.2 notify-text (text(MAX)) 1958 This attribute contains a Human Consumable text message (see section 1959 9.2). This message describes the Event and is encoded as plain text, 1960 i.e., 'text/plain' with the charset specified by Subscription 1961 Object's "notify-charset" attribute. 1963 The Delivery Method Document specifies whether the Printer includes 1964 this attribute in an Event Notification. 1966 9 Event Notification Content 1968 This section defines the Event Notification content that the Printer 1969 delivers when an Event occurs. 1971 When an Event occurs, the Printer MUST find each Subscription object 1972 whose "notify-events" attribute "matches" the Event. See section 1973 5.3.3.5 for details on "matching". For each matched Subscription 1974 Object, the Printer MUST create an Event Notification with the 1975 content and format that the Delivery Method Document specifies. The 1976 content contains the value of attributes specified by the Delivery 1977 Method Document. The Printer obtains the values immediately after 1978 the Event occurs. For example, if the "printer-state" attribute 1979 changes from 'idle' to 'processing', the Event 'printer-state- 1980 changed' occurs and the Printer puts various attributes into the 1981 Event Notification, including "printer-up-time" and "printer-state" 1982 with the values that they have immediately after the Event occurs, 1983 i.e., the value of "printer-state" is 'processing'. 1985 Event Notification Ordering: 1987 When a Printer delivers Event Notifications, the Event Notifications 1988 from any given Subscription Object MUST be in time stamp order, i.e., 1989 in order of increasing "printer-up-time" attribute value in the Event 1990 Notification (see Table 5). These Event Notifications MAY be 1991 interleaved with those from other Subscription Objects, as long as 1992 those others are also in time stamp order. The Printer MUST observe 1993 these ordering requirements whether delivering multiple pending 1994 Events as multiple separate Event Notifications or together in a 1995 single Compound Event Notification. 1997 If a Subscribing Client wants the Printer to deliver certain Event 1998 Notifications in time stamp order, the Subscribing Client uses a 1999 single Subscription Object. Even so, depending on the underlying 2000 transport, the actual order that a Notification Recipient receives 2001 separate Event Notifications may differ from the order sent by the 2002 Printer (e.g., email). 2004 Example: Consider two Per-Printer Subscription Objects: SO1 and SO2. 2005 SO1 requests 'job-state-changed' events and SO2 requests 'printer- 2006 state-changed' events. The number in parens is the time stamp. The 2007 following Event Notification sequences are the only ones that conform 2008 to the ordering requirements for the Printer to deliver the Event 2009 Notifications: 2011 (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 2012 'job-completed' (1009), SO2: 'printer-stopped' (1005) 2014 (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2: 2015 'printer-stopped' (1005), SO1: 'job-completed' (1009) 2017 (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1: 2018 'job-stopped' (1005), SO1: 'job-completed' (1009) 2020 (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1: 2021 'job-stopped' (1005), SO1: 'job-completed' (1009) 2023 Examples (b) and (c) are interleaved; examples (a) and (d) are not 2024 interleaved and are not appropriate for some Delivery Methods. 2026 If two different Events occur simultaneously, or nearly so (e.g., 2027 "printer-up-time" has the same value for both), the Printer MUST 2028 create a separate Event Notification for each Event, even if the 2029 associated Subscription Object is the same for both Events. However, 2030 the Printer MAY combine these distinct Event Notifications into a 2031 single Compound Event Notification if the Delivery Method supports 2032 Compound Event Notifications. For example, suppose that two nearly- 2033 simultaneously Events represent two successive 'printer-state- 2034 changed' Events, one from 'idle' to 'processing' and another from 2035 'processing' to 'stopped'. These two Events have the same name but 2036 are different instances of the Event. Then the Printer MUST create a 2037 separate Event Notification for each Event and SHOULD accurately 2038 report the "printer-state" of the first Event as 'processing' and the 2039 second Event as 'stopped'. 2041 If a Subscription Object contains more than one Subscribed Event, and 2042 several Events occur in quick succession each matching a different 2043 Subscribed Event in the Subscription Object, the Printer MUST NOT 2044 generate a single Event Notification from several of these Events, 2045 but MAY combine distinct Event Notifications into a single Compound 2046 Event Notification if the Delivery Method supports Compound Event 2047 Notifications. 2049 After the Printer has created the Event Notification, the Printer 2050 delivers it via either a: 2052 Push Delivery Method: The Printer delivers the Event 2053 Notification shortly after an Event occurs. For some Push 2054 Delivery Methods, the Notification Recipient MUST deliver a 2055 response; for others it MUST NOT deliver a response. 2057 Pull Delivery Method: The Printer saves Event Notifications for 2058 some Event Life and expects the Notification Recipient to 2059 request Event Notifications. The Printer returns the Event 2060 Notifications in a response to such a request. 2062 If an error that meets the following conditions occurs, the Printer 2063 MUST cancel the Subscription Object. 2065 a)the error occurs during the delivering of an Event Notification 2066 generated from Subscription Object S AND 2068 b)the error would continue to occur every time the Printer delivers 2069 an Event Notification generated from Subscription Object S in the 2070 future. 2072 For example, if the address of the "notify-recipient-uri" of 2073 Subscription Object A references a non-existent target and the 2074 Printer determines this fact, it MUST delete Subscription Object A. 2076 The next two sections describe the values that a Printer delivers in 2077 the content of Machine Consumable and Human Consumable Event 2078 Notifications, respectively. 2080 The tables in the sub-sections of this section contain the following 2081 columns: 2083 a)Source Value: the name of the attribute that supplies the value 2084 for the Event Notification. Asterisks in this field refer to a 2085 note below the table. 2087 b)Delivers: if the Printer supports the value (column 1) on the 2088 Source Object (column 3) the Delivery Method MUST specify: 2090 MUST: that the Printer MUST deliver the value. 2092 SHOULD: either that the Printer MUST deliver the value or that 2093 the value is incompatible with the Delivery Method. 2095 MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, 2096 or NEED NOT deliver the value. The Delivery Method specifies 2097 the level of conformance for the Printer. 2099 c)Source Object: the object from which the source value comes. If 2100 the object is "Event Notification", the Printer fabricates the 2101 value when it delivers the Event Notification. See section 8. 2103 9.1 Content of Machine Consumable Event Notifications 2105 This section defines the attributes that a Delivery Method MUST 2106 mention in a Delivery Method Document when specifying the Machine 2107 Consumable Event Notification's contents. 2109 This document does not define the order of attributes in Event 2110 Notifications. However, Delivery Method Documents MAY define the 2111 order of some or all of the attributes. 2113 A Delivery Method Document MUST specify additional attributes (if 2114 any) that a Printer implementation delivers in a Machine Consumable 2115 Event Notification. 2117 Notification Recipients MUST be able to accept Event Notifications 2118 containing attributes they do not recognize. What a Notification 2119 Recipient does with an unrecognized attribute is implementation- 2120 dependent. Notification Recipients MAY attempt to display 2121 unrecognized attributes anyway or MAY ignore them. 2123 The next three sections define the attributes in Event Notification 2124 Contents that are: 2126 1.for all Events 2128 2.for Job Events only 2130 3.for Printer Events only 2132 9.1.1 Event Notification Content Common to All Events 2134 This section lists the attributes that a Delivery Method Document 2135 MUST specify for all Events. 2137 Table 5 lists potential values in each Event Notification. 2139 Table 5 - Attributes in Event Notification Content 2141 Source Value Delivers Source Object 2143 notify-subscription-id (integer(1:MAX)) MUST Subscription 2145 notify-printer-uri (uri) MUST Subscription 2147 notify-subscribed-event (type2 keyword) MUST Event 2148 Notification 2150 printer-up-time (integer(MIN:MAX)) MUST Printer 2152 printer-current-time (dateTime) * MUST Printer 2154 notify-sequence-number (integer (0:MAX)) SHOULD Subscription 2156 notify-charset (charset) SHOULD Subscription 2158 notify-natural-language (naturalLanguage) SHOULD Subscription 2160 notify-user-data (octetString(63)) ** SHOULD Subscription 2162 notify-text (text) SHOULD Event 2163 Notification 2165 attributes from the "notify-attributes" MAY Printer 2166 attribute *** 2168 attributes from the "notify-attributes" MAY Job 2169 attribute *** 2171 attributes from the "notify-attributes" MAY Subscription 2172 attribute *** 2174 *A Printer MUST deliver this value only if and only if it supports 2175 the Printer's "printer-current-time" attribute. 2177 ** If the Subscription Object does not contain a "notify-user-data" 2178 attribute and the Delivery Method Document REQUIRES the Printer to 2179 deliver the "notify-user-data" source value in the Event 2180 Notification, the Printer MUST deliver an octet-string of length 0. 2182 *** The last three rows represent additional attributes that a client 2183 MAY request via the "notify-attributes" attribute. A Printer MAY 2184 support the "notify-attributes" attribute. The Delivery Method MUST 2185 say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED 2186 NOT support the "notify-attributes" attribute and specific values of 2187 this attribute. The Delivery Method MAY say that support for the 2188 "notify-attributes" is conditioned on support of the attribute by the 2189 Printer or it MAY say that Printer MUST support the "notify- 2190 attributes" attribute if the Printer supports the Delivery Method. 2192 9.1.2 Additional Event Notification Content for Job Events 2194 This section lists the additional attributes that a Delivery Method 2195 Document MUST specify for Job Events. See Table 6. 2197 Table 6 - Additional Event Notification Content for Job Events 2199 Source Value Delive Source Object 2200 rs 2202 job-id (integer(1:MAX)) MUST Job 2204 job-state (type1 enum) MUST Job 2206 job-state-reasons (1setOf type2 keyword) MUST Job 2208 job-impressions-completed (integer(0:MAX)) * MUST Job 2210 * The Printer MUST deliver the "job-impressions-completed" attribute 2211 in an Event Notification only for the combinations of Events and 2212 Subscribed Events shown in Table 7. 2214 Table 7 - Combinations of Events and Subscribed Events for "job- 2215 impressions-completed" 2217 Job Event Subscribed Job Event 2219 'job-progress' 'job-progress' 2221 'job-completed' 'job-completed' 2223 'job-completed' 'job-state-changed' 2225 9.1.3 Additional Event Notification Content for Printer Events 2227 This section lists the additional attributes that a Delivery Method 2228 Document MUST specify for Printer Events. See Table 8. 2230 Table 8 - Additional Event Notification Content for Printer Events 2232 Source Value Delivers Source Object 2234 printer-state (type1 enum) MUST Printer 2236 printer-state-reasons (1setOf type2 MUST Printer 2237 keyword) 2239 printer-is-accepting-jobs (boolean) MUST Printer 2241 9.2 Content of Human Consumable Event Notification 2243 This section defines the information that a Delivery Method MUST 2244 mention in a Delivery Method Document when specifying the Human 2245 Consumable Event Notifications contents or the value of the "notify- 2246 text" attribute. 2248 Such a Delivery Method MUST specify the following information and a 2249 Printer SHOULD deliver it: 2251 a)the Printer name (see Table 9) 2253 b)the time of the Event (see Table 11) 2254 c)for Printer Events only: 2255 i) the Event (see Table 10) and/or Printer state information 2256 (see Table 14) 2257 d)for Job Events only: 2258 i) the job identity (see Table 12) 2259 ii) the Event (see Table 10) and/or Job state information (see 2260 Table 13) 2262 The subsections of this section specify the attributes that a Printer 2263 MUST use to obtain this information. 2265 A Delivery Method Document MUST specify additional information (if 2266 any) that a Printer implementation delivers in a Human Consumable 2267 Event Notification or in the "notify-text" attribute. 2269 A client MUST NOT request additional attributes via the "notify- 2270 attributes" attribute because this attribute works only for Machine 2271 Consumable Event Notifications. 2273 Notification Recipients MUST NOT expect to be able to parse the Human 2274 Consumable Event Notification contents or the value of the "notify- 2275 text" attribute. 2277 The next three sections define the attributes in Event Notification 2278 Contents that are: 2280 a) for all Events 2281 b) for Job Events only 2282 c) for Printer Events only 2284 9.2.1 Event Notification Content Common to All Events 2286 This section lists the source of the information that a Delivery 2287 Method MUST specify for all Events. 2289 There is a separate table for each piece of information. Each row in 2290 the table represents a source value for the information and the 2291 values are listed in order of preference, with the first one being 2292 the preferred one. An implementation SHOULD use the source value 2293 from the earliest row in each table. It MAY use the source value 2294 from another row instead, or it MAY combine the source values from 2295 several rows. An implementation is free to determine the best way to 2296 present this information. 2298 In all tables of this section, all rows contain a "MAY" in order to 2299 state that the Delivery Method specifies the conformance. 2301 Table 9 lists the source of the information for the Printer Name. 2302 The "printer-name" is more user-friendly unless the Notification 2303 Recipient is in a place where the Printer name is not meaningful. 2304 For example, an implementation could have the intelligence to deliver 2305 the value of the "printer-name" attribute to a Notification Recipient 2306 that can access the Printer via value of the "printer-name" attribute 2307 and otherwise deliver the value of the "notify-printer-uri" 2308 attribute. 2310 Table 9 - Printer Name in Event Notification Content 2312 Source Value Delivers Source Object 2314 printer-name (name(127)) MAY Printer 2316 notify-printer-uri (uri) MAY Subscription 2318 Table 10 lists the source of the information for the Event name. A 2319 Printer MAY combine this information with state information described 2320 for Jobs in Table 13 or for Printers in Table 14. 2322 Table 10 - Event Name in Event Notification Content 2324 Source Value Delivers Source Object 2326 notify-subscribed-event (type2 keyword) MAY Subscription 2328 Table 11 lists the source of the information for the time that the 2329 Event occurred. A Printer can deliver this value only if it supports 2330 the Printer's "printer-current-time" attribute. If a Printer does 2331 not support the "printer-current-time" attribute, it MUST NOT deliver 2332 the "printer-up-time" value instead, since it is not an allowed 2333 option for human consumable information. 2335 Table 11 - Event Time in Event Notification Content 2337 Source Value Delivers Source Object 2339 printer-current-time (dateTime) MAY Printer 2341 9.2.2 Additional Event Notification Content for Job Events 2343 This section lists the source of the additional information that a 2344 Delivery Method MUST specify for Job Events. 2346 Table 12 lists the source of the information for the job name. The 2347 "job-name" is likely more meaningful to a user than "job-id". 2349 Table 12 - Job Name in Event Notification Content 2351 Source Value Delivers Source Object 2353 job-name (name(MAX)) MAY Job 2355 job-id (integer(1:MAX)) MAY Job 2357 Table 13 lists the source of the information for the job state. If a 2358 Printer supports the "job-state-message" and "job-detailed-state- 2359 message" attributes, it SHOULD use those attributes for the job state 2360 information, otherwise, it should fabricate such information from the 2361 "job-state" and "job-state-reasons". For some Events, a Printer MAY 2362 combine this information with Event information. 2364 Table 13 - Job State in Event Notification Content 2366 Source Value Delivers Source 2367 Object 2369 job-state-message (text(MAX)) MAY Job 2371 job-detailed-status-messages (1setOf text(MAX)) MAY Job 2373 job-state (type1 enum) MAY Job 2375 job-state-reasons (1setOf type2 keyword) MAY Job 2377 9.2.3 Additional Event Notification Content for Printer Events 2379 This section lists the source of the additional information that a 2380 Delivery Method MUST specify for Printer Events. 2382 Table 14 lists the source of the information for the printer state. 2383 If a Printer supports the "printer-state-message", it SHOULD use that 2384 attribute for the job state information, otherwise it SHOULD 2385 fabricate such information from the "printer-state" and "printer- 2386 state-reasons". For some Events, a Printer MAY combine this 2387 information with Event information. 2389 Table 14 - Printer State in Event Notification Content 2391 Source Value Delivers Source 2392 Object 2394 printer-state-message (text(MAX)) MAY Printer 2396 printer-state (type1 enum) MAY Printer 2398 printer-state-reasons (1setOf type2 keyword) MAY Printer 2400 printer-is-accepting-jobs (boolean) MAY Printer 2402 10 Delivery Methods 2404 A Delivery Method is the mechanism, i.e., protocol, by which the 2405 Printer delivers an Event Notification to a Notification Recipient. 2406 There are several potential Delivery Methods for Event Notifications, 2407 standardized, as well as proprietary. This specification REQUIRES 2408 that the 'ippget' Pull Delivery Method [ipp-get-method] be supported. 2409 Conforming implementations MAY support additional Push or Pull 2410 Delivery Methods as well. This document does not define any of these 2411 delivery mechanisms. Each Delivery Method MUST be defined in a 2412 Delivery Method Document that is separate from this document. New 2413 Delivery Methods will be created as needed using an extension to the 2414 registration procedures defined in [RFC2911]. Such documents are 2415 registered with IANA (see section 24.7.3). 2417 The following sorts of Delivery Methods are possible: 2419 - The Notification Recipient polls for Event Notifications at 2420 intervals directed by the Printer 2421 - The Printer delivers Event Notifications to the Notification 2422 Recipient using http as the transport. 2424 - The Printer delivers an email message. 2426 This section specifies how to define a Delivery Method Document and 2427 what to put in such a document. 2429 A Delivery Method Document MUST contain an exact copy of the 2430 following paragraph, caption and table. In addition, column 2 of the 2431 table in the Delivery Method Document MUST contain answers to 2432 questions in column 1 for the Delivery Method. Also, the Delivery 2433 Method document MUST contain a reference to this document and call 2434 that reference [ipp-ntfy] because the table contains an [ipp-ntfy] 2435 reference. 2437 If a Printer supports this Delivery Method, the following are its 2438 characteristics. 2440 Table 15 - Information about the Delivery Method 2442 Document Method Conformance Requirement Delivery Method 2443 Realization 2445 1.What is the URL scheme name for the Push 2446 Delivery Method or the keyword method 2447 name for the Pull Delivery Method? 2449 2.Is the Delivery Method REQUIRED, 2450 RECOMMENDED, or OPTIONAL for an IPP 2451 Printer to support? 2453 3.What transport and delivery protocols 2454 does the Printer use to deliver the 2455 Event Notification Content, i.e., what 2456 is the entire network stack? 2458 4.Can several Event Notifications be 2459 combined into a Compound Event 2460 Notification? 2462 5.Is the Delivery Method initiated by the 2463 Notification Recipient (pull), or by the 2464 Printer (push)? 2466 Document Method Conformance Requirement Delivery Method 2467 Realization 2469 6.Is the Event Notification content 2470 Machine Consumable or Human Consumable? 2472 7.What section in this document answers 2473 the following question? For a Machine 2474 Consumable Event Notification, what is 2475 the representation and encoding of 2476 values defined in section 9.1 of [ipp- 2477 ntfy] and the conformance requirements 2478 thereof? For a Human Consumable Event 2479 Notification, what is the representation 2480 and encoding of pieces of information 2481 defined in section 9.2 of [ipp-ntfy] and 2482 the conformance requirements thereof? 2484 8.What are the latency and reliability of 2485 the transport and delivery protocol? 2487 9.What are the security aspects of the 2488 transport and delivery protocol, e.g., 2489 how it is handled in firewalls? 2491 10. What are the content length 2492 restrictions? 2494 11. What are the additional values or 2495 pieces of information that a Printer 2496 delivers in an Event Notification 2497 content and the conformance requirements 2498 thereof? 2500 12. What are the additional Subscription 2501 Template and/or Subscription Description 2502 attributes and the conformance 2503 requirements thereof? 2505 13. What are the additional Printer 2506 Description attributes and the 2507 conformance requirements thereof? 2509 11 Operations for Notification 2511 This section defines all of the operations for Notification. Section 2512 7.1 assigns the "operation-id" for each operation. The following two 2513 sub-sections define Subscription Creation Operations, and other 2514 operations. 2516 11.1 Subscription Creation Operations 2518 This section defines the Subscription Creation Operations. The first 2519 section on Create-Job-Subscriptions gives most of the information. 2520 The other Subscription Creation Operations refer to the section on 2521 Create-Job-Subscriptions, even though the Create-Job-Subscriptions 2522 operation is the only OPTIONAL operation in this document (see 2523 section 12). 2525 A Printer MUST support Create-Printer-Subscriptions and the 2526 Subscription Template Attributes Group in Job Creation operations. 2527 It MAY support Create-Job-Subscriptions operations. 2529 11.1.1 Create-Job-Subscriptions Operation 2531 The operation creates one or more Per-Job Subscription Objects. The 2532 client supplies one or more Subscription Template Attributes Groups 2533 each containing one or more of Subscription Template Attributes 2534 (defined in section 5.3). 2536 Except for errors, the Printer MUST create exactly one Per-Job 2537 Subscription Object from each Subscription Template Attributes Group 2538 in the request, even if the newly created Subscription Object would 2539 have identical behavior to some existing Subscription Object. The 2540 Printer MUST associate each newly created Per-Job Subscription Object 2541 with the target Job, which is specified by the "notify-job-id" 2542 operation attribute. 2544 The Printer MUST accept the request in any of the target job's 'not- 2545 completed' states, i.e., 'pending', 'pending-held', 'processing', or 2546 'processing-stopped'. The Printer MUST NOT change the job's "job- 2547 state" attribute because of this operation. If the target job is in 2548 any of the 'completed' states, i.e., 'completed', 'canceled', or 2549 'aborted, then the Printer MUST reject the request and return the 2550 'client-error-not-possible' status code; the response MUST NOT 2551 contain any Subscription Attribute Groups. 2553 Access Rights: To create Per-Job Subscription Objects, the 2554 authenticated user (see [RFC2911] section 8.3) performing this 2555 operation MUST (1) be the job owner, (2) have Operator or 2556 Administrator access rights for this Printer (see [RFC2911] sections 2557 1 and 8.5), or (3) be otherwise authorized by the Printer's 2558 administrator-configured security policy to create Per-Job 2559 Subscription Objects for the target job. Otherwise the Printer MUST 2560 reject the operation and return: the 'client-error-forbidden', 2561 'client-error-not-authenticated', or 'client-error-not-authorized' 2562 status code as appropriate. 2564 11.1.1.1 Create-Job-Subscriptions Request 2566 The following groups of attributes are part of the Create-Job- 2567 Subscriptions Request: 2569 Group 1: Operation Attributes 2571 Natural Language and Character Set: 2572 The "attributes-charset" and "attributes-natural-language" 2573 attributes as described in [RFC2911] section 3.1.4.1. 2575 Target: 2576 The "printer-uri" attribute which defines the target for this 2577 operation as described in [RFC2911] section 3.1.5. 2579 Requesting User Name: 2580 The "requesting-user-name" attribute SHOULD be supplied by the 2581 client as described in [RFC2911] section 8.3. 2583 11.1.1.1.1 notify-job-id (integer(1:MAX)) 2585 The client MUST supply this attribute and it MUST specify the 2586 Job object to associate the Per-Job Subscription with. The 2587 value of "notify-job-id" MUST be the value of the "job-id" of 2588 the associated Job object. If the client does not supply this 2589 attribute, the Printer MUST reject this request with a 'client- 2590 error-bad-request' status code. 2592 Group 2-N: Subscription Template Attributes 2594 For each occurrence of this group: 2596 The client MUST supply one or more Subscription Template 2597 Attributes in any order. See section 5.3 for a description of 2598 each such attribute. See section 5.2 for details on 2599 processing these attributes. 2601 11.1.1.2 Create-Job-Subscriptions Response 2603 The Printer MUST return to the client the following sets of 2604 attributes as part of a Create-Job-Subscriptions response: 2606 Group 1: Operation Attributes 2608 Status Message: 2609 In addition to the REQUIRED status code returned in every 2610 response, the response OPTIONALLY includes a "status-message" 2611 (text(255)) and/or a "detailed-status-message" (text(MAX)) 2612 operation attribute as described in [RFC2911] sections 13 and 2613 3.1.6. 2615 In this group, the Printer can return any status codes defined 2616 in [RFC2911] and section 12. The following is a description of 2617 the important status codes: 2619 successful-ok: the Printer created all Subscription Objects 2620 requested (see [RFC2911]). 2621 successful-ok-ignored-subscriptions: the Printer created 2622 some Subscription Objects requested but some failed. The 2623 Subscription Attributes Groups with a "notify-status- 2624 code" attribute are the ones that failed (see section 2625 12.1). 2626 client-error-ignored-all-subscriptions: the Printer created 2627 no Subscription Objects requested and all failed. The 2628 Subscription Attributes Groups with a "notify-status- 2629 code" attribute are the ones that failed (see section 2630 12.2). 2631 client-error-not-possible: For this operation and other 2632 Per-Job Subscription operations, this error can occur 2633 because the specified Job has already completed (see 2634 [RFC2911], whether or not the Job is retained in the Job 2635 Retention and/or Job History phases (see [RFC2911] 2636 section 4.3.7.1). 2638 Natural Language and Character Set: 2639 The "attributes-charset" and "attributes-natural-language" 2640 attributes as described in [RFC2911] section 3.1.4.2. 2642 Group 2: Unsupported Attributes 2644 See [RFC2911] section 3.1.7 for details on returning 2645 Unsupported Attributes. This group does not contain any 2646 unsupported Subscription Template Attributes; they are returned 2647 in the Subscription Attributes Group (see below). 2649 Group 3-N: Subscription Attributes 2650 These groups MUST be returned unless the Printer is unable to 2651 interpret the entire request, e.g., the "status-code" parameter 2652 returned in Group 1 has the value: 'client-error-bad-request'. 2654 "notify-status-code" (type2 enum): 2655 Indicates the status of this subscription (see section 13 2656 for the status code definitions). Section 5.2 defines when 2657 this attribute MUST be present in this group. 2659 See section 5.2 for details on the contents of each occurrence 2660 of this group. 2662 11.1.2 Create-Printer-Subscriptions operation 2664 The operation is identical to Create-Job-Subscriptions with 2665 exceptions noted in this section. 2667 The operation creates Per-Printer Subscription Objects instead of 2668 Per-Job Subscription Objects, and associates each newly created Per- 2669 Printer Subscription Object with the Printer specified by the 2670 operation target rather than with a specific Job. 2672 The Printer MUST accept the request in any of its states, i.e., 2673 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its 2674 "printer-state" attribute because of this operation. 2676 Access Rights: To create Per-Printer Subscription Objects, the 2677 authenticated user (see [RFC2911] section 8.3) performing this 2678 operation MUST have (1) Operator or Administrator access rights for 2679 this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise 2680 authorized by the Printer's administrator-configured security policy 2681 to create Per-Printer Subscription Objects for this Printer. 2682 Otherwise, the Printer MUST reject the operation and return: the 2683 'client-error-forbidden', 'client-error-not-authenticated', or 2684 'client-error-not-authorized' status code as appropriate. 2686 11.1.2.1 Create-Printer-Subscriptions Request 2688 The groups are identical to the Create-Job-Subscriptions (see section 2689 11.1.1.1) except that the Operation Attributes group MUST NOT contain 2690 the "notify-job-id" attribute. If the client does supply the 2691 "notify-job-id" attribute, then the Printer MUST treat it as any 2692 other unsupported Operation attribute and MUST return it in the 2693 Unsupported Attributes group. 2695 11.1.2.2 Create-Printer-Subscriptions Response 2697 The groups are identical to the Create-Job-Subscriptions (see section 2698 11.1.1.2). 2700 11.1.3 Job Creation Operations - Extensions for Notification 2702 This document extends the Job Creation operations (see section 3.2) 2703 to create Subscription Objects as a part of the operation. 2705 The Job Creation operations are identical to Create-Job-Subscriptions 2706 operation with exceptions noted in this section. 2708 Unlike the Create-Job-Subscriptions operation, a Job Creation 2709 operation associates the newly created Subscription Objects with the 2710 Job object created by this operation. The operation succeeds if and 2711 only if the Job creation succeeds. If the Printer does not create 2712 some or all of the requested Subscription Objects, the Printer MUST 2713 return a 'successful-ok-ignored-subscriptions' status-code instead 2714 of a 'successful-ok' status-code, but the Printer MUST NOT reject the 2715 operation because of a failure to create Subscription Objects. 2717 If the Job Creation operation includes a Job Template group, the 2718 client MUST supply it after the Operation Attributes group and before 2719 the first Subscription Template Attributes Group. 2721 If a Printer does not support this Notification specification, then 2722 it MUST treat the Subscription Attributes Group like an unknown group 2723 and ignore it (see [RFC2911] section 5.2.2). Because the Printer 2724 ignores the Subscription Attributes Group, it doesn't return them in 2725 the response either, thus indicating to the client that the Printer 2726 doesn't support Notification. 2728 After completion of a successful Job Creation operation, the Printer 2729 generates a 'job-created' event (see section 5.3.3.4.3). 2731 Access Rights: To create Per-Job Subscription Objects, the 2732 authenticated user (see [RFC2911] section 8.3) performing this 2733 operation MUST either have permission to create Jobs on the Printer 2734 or have Operator or Administrator access rights for this Printer (see 2735 [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the 2736 operation and return: the 'client-error-forbidden', 'client-error- 2737 not-authenticated', or 'client-error-not-authorized' status code as 2738 appropriate. 2740 11.1.3.1 Job Creation Request 2742 The groups for this operation are sufficiently different from the 2743 Create-Job-Subscriptions operation that they are all presented here. 2744 The following groups of attributes are supplied as part of a Job 2745 Creation Request: 2747 Group 1: Operation Attributes 2749 Same as defined in [RFC2911] for Print-Job, Print-URI, and 2750 Create-Job requests. 2752 Group 2: Job Template Attributes 2754 The client OPTIONALLY supplies a set of Job Template attributes 2755 as defined in [RFC2911] section 4.2. 2757 Group 3 to N: Subscription Template Attributes 2759 The same as Group 2-N in Create-Job-Subscriptions. See section 2760 11.1.1.1. 2761 Group N+1: Document Content (Print-Job only) 2763 The client MUST supply the document data to be processed. 2765 11.1.3.2 Job Creation Response 2767 The Printer MUST return to the client the following sets of 2768 attributes as part of a Print-Job, Print-URI, and Create-Job 2769 Response: 2771 Group 1: Operation Attributes 2773 Status Message: 2775 As defined in [RFC2911] for Print-Job, Print-URI, and Create- 2776 Job requests. 2778 In this group, the Printer can return any status codes defined 2779 in [RFC2911] and section 12. The following is a description of 2780 the important status codes: 2782 successful-ok: the Printer created the Job and all 2783 Subscription Objects requested (see [RFC2911]. 2784 successful-ok-ignored-subscriptions: the Printer created 2785 the Job and not all of the Subscription Objects requested 2786 (see section 12.1). This status-code hides 'successful- 2787 ok-xxx' status-codes that could reveal problems in Job 2788 creation. The Printer MUST NOT return the 'client-error- 2789 ignored-all-subscriptions' status code for Job Creation 2790 operations because the Printer returns an error status- 2791 code only when it fails to create a Job. 2793 Natural Language and Character Set: 2794 The "attributes-charset" and "attributes-natural-language" 2795 attributes as described in [RFC2911] section 3.1.4.2. 2797 Group 2: Unsupported Attributes 2799 See [RFC2911] section 3.1.7 for details on returning 2800 Unsupported Attributes. This group does not contain any 2801 unsupported Subscription Template Attributes; they are returned 2802 in the Subscription Attributes Group (see below). 2804 Group 3: Job Object Attributes 2806 The "job-id" of the Job Object just created, etc., as defined 2807 in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. 2809 Group 4 to N: Subscription Attributes 2811 These groups MUST be returned if and only if the client 2812 supplied Subscription Template Attributes and the operation was 2813 accepted. 2814 See section 5.2 for details on the contents of each occurrence 2815 of this group. 2817 11.2 Other Operations 2819 This section defines other operations on Subscription objects. 2821 11.2.1 Restart-Job Operation - Extensions for Notification 2823 The Restart-Job operation [RFC2911] is neither a Job Creation 2824 operation nor a Subscription Creation operation (see section 3.2). 2825 For the Restart-Job operation, the client MUST NOT supply any Job 2826 Subscription Attributes Groups. The Printer MUST treat any supplied 2827 Job Subscription Attributes as unsupported attributes. 2829 For this operation, the Printer does not return a job-id or any 2830 Subscription Attributes groups because the Printer reuses the 2831 existing Job object with the same job-id and the existing Per-Job 2832 Subscription Objects with the same subscription-ids. However, after 2833 successful completion of this operation, the Printer generates a 2834 'job-created' event (see section 5.3.3.4.3). 2836 11.2.2 Validate-Job Operation - Extensions for Notification 2838 A client can test whether one or more Subscription Objects could be 2839 created using the Validate-Job operation. The client supplies one or 2840 more Subscription Template Attributes Groups (defined in section 2841 5.3), just as in a Job Creation request. 2843 A Printer MUST support this extension to this operation. 2845 The Printer MUST accept requests that are identical to the Job 2846 Creation request defined in section 11.1.3.1, except that the request 2847 MUST NOT contain document data. 2849 The Printer MUST return the same groups and attributes as the Print- 2850 Job operation (section 11.1.3.1) with the following exceptions. The 2851 Printer MUST NOT return a Job Object Attributes Group because no Job 2852 is created. The Printer MUST NOT return the "notify-subscription-id" 2853 attribute in any Subscription Attribute Group because no Subscription 2854 Object is created. 2856 If the Printer would succeed in creating a Subscription Object, the 2857 corresponding Subscription Attributes Group either has no 'status- 2858 code' attribute or a 'status-code' attribute with a value of 2859 'successful-ok-too-many-events' or 'successful-ok-ignored-or- 2860 substituted-attributes' (see sections 5.2 and 13). The status-codes 2861 have the same meaning as in Job Creation except the results state 2862 what "would happen". 2864 The Printer MUST validate Subscription Template Attributes Groups in 2865 the same manner as the Job Creation operations. 2867 11.2.3 Get-Printer-Attributes - Extensions for Notification 2869 This operation is extended so that it returns Printer attributes 2870 defined in this document. 2872 A Printer MUST support this extension to this operation. 2874 In addition to the requirements of [RFC2911] section 3.2.5, a Printer 2875 MUST support the following additional values for the "requested- 2876 attributes" Operation attribute in this operation and return such 2877 attributes in the Printer Object Attributes group of its response. 2879 1.Subscription Template Attributes: Each supported attribute in 2880 column 2 of Table 1. 2882 2.New Printer Description Attributes: Each supported attribute in 2883 section 6. 2885 3.New Group Name: The 'subscription-template' group name, which 2886 names all supported Subscription Template Attribute in column 2 2887 of Table 1. This group name is also used in the Get- 2888 Subscription-Attributes and Get-Subscriptions operation with an 2889 analogous meaning. 2891 4.Extended Group Name: The 'all' group name, which names all 2892 Printer attributes according to [RFC2911] section 3.2.5. In 2893 this extension 'all' names all attributes specified in [RFC2911] 2894 plus those named in items 1 and 2 of this list. 2896 11.2.4 Get-Subscription-Attributes operation 2898 This operation allows a client to request the values of the 2899 attributes of a Subscription Object. 2901 A Printer MUST support this operation. 2903 This operation is almost identical to the Get-Job-Attributes 2904 operation (see [RFC2911] section 3.3.4). The only differences are 2905 that the operation is directed at a Subscription Object rather than a 2906 Job object, and the returned attribute group contains Subscription 2907 Object attributes rather than Job object attributes. 2909 Access Rights: The authenticated user (see [RFC2911] section 8.3) 2910 performing this operation MUST (1) be the Subscription Object owner, 2911 (2) have Operator or Administrator access rights for this Printer 2912 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by 2913 the Printer's administrator-configured security policy to query the 2914 Subscription Object for the target job. Otherwise the Printer MUST 2915 reject the operation and return: the 'client-error-forbidden', 2916 'client-error-not-authenticated', or 'client-error-not-authorized' 2917 status code as appropriate. Furthermore, the Printer's security 2918 policy MAY limit which attributes are returned, in a manner similar 2919 to the Get-Job-Attributes operation (see [RFC2911] end of section 2920 3.3.4.2). 2922 11.2.4.1 Get-Subscription-Attributes Request 2924 The following groups of attributes are part of the Get-Subscription- 2925 Attributes request: 2927 Group 1: Operation Attributes 2929 Natural Language and Character Set: 2930 The "attributes-charset" and "attributes-natural-language" 2931 attributes as described in section [RFC2911] 3.1.4.1. 2933 Target: 2934 The "printer-uri" attribute which defines the target for this 2935 operation as described in [RFC2911] section 3.1.5. 2937 Requesting User Name: 2938 The "requesting-user-name" attribute SHOULD be supplied by the 2939 client as described in [RFC2911] section 8.3. 2941 11.2.4.1.1 "notify-subscription-id" (integer (1:MAX)) 2943 The client MUST supply this attribute. The Printer MUST 2944 support this attribute. This attribute specifies the 2945 Subscription Object from which the client is requesting 2946 attributes. If the client omits this attribute, the Printer 2947 MUST reject this request with the 'client-error-bad-request' 2948 status code. 2950 11.2.4.1.2 "requested-attributes" (1setOf keyword) 2952 The client OPTIONALLY supplies this attribute. The Printer 2953 MUST support this attribute. This attribute specifies the 2954 attributes of the specified Subscription Object that the 2955 Printer MUST return in the response. Each value of this 2956 attribute is either an attribute name (defined in sections 5.3 2957 and 5.4) or an attribute group name. The attribute group names 2958 are: 2960 - 'subscription-template': all attributes that are both 2961 defined in section 5.3 and present on the specified 2962 Subscription Object (column 1 of Table 1). 2963 - 'subscription-description': all attributes that are both 2964 defined in section 5.4 and present on the specified 2965 Subscription Object (Table 2). 2966 - 'all': all attributes that are present on the specified 2967 Subscription Object. 2969 A Printer MUST support all these group names. 2971 If the client omits this attribute, the Printer MUST respond as 2972 if this attribute had been supplied with a value of 'all'. 2974 11.2.4.2 Get-Subscription-Attributes Response 2976 The Printer returns the following sets of attributes as part of the 2977 Get-Subscription-Attributes Response: 2979 Group 1: Operation Attributes 2980 Status Message: 2981 Same as [RFC2911]. 2983 Natural Language and Character Set: 2984 The "attributes-charset" and "attributes-natural-language" 2985 attributes as described in [RFC2911] section 3.1.4.2. The 2986 "attributes-natural-language" MAY be the natural language of 2987 the Subscription Object, rather than the one requested. 2989 Group 2: Unsupported Attributes 2991 See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on 2992 returning Unsupported Attributes. 2994 The response NEED NOT contain the "requested-attributes" 2995 operation attribute with any supplied keyword values that were 2996 requested by the client but are not supported by the IPP 2997 object. If the Printer object does return unsupported 2998 attributes referenced in the "requested-attributes" operation 2999 attribute, the values of the "requested-attributes" attribute 3000 returned MUST include only the unsupported keywords that were 3001 requested by the client. If the client had requested a group 3002 name, such as 'all', the resulting unsupported attributes 3003 returned MUST NOT include attribute keyword names described in 3004 the standard but not supported by the implementation. 3006 Group 3: Subscription Attributes 3008 This group contains a set of attributes with their current 3009 values. Each attribute returned in this group: 3011 a)MUST be specified by the "requested-attributes" attribute 3012 in the request, AND 3014 b)MUST be present on the specified Subscription Object AND 3016 c)MUST NOT be restricted by the security policy in force. 3017 For example, a Printer MAY prohibit a client who is not the 3018 creator of a Subscription Object from seeing some or all of 3019 its attributes. See [RFC2911] end of section 3.3.4.2 and 3020 section 8. 3022 The Printer can return the attributes of the Subscription 3023 Object in any order. The client MUST accept the attributes in 3024 any order. 3026 11.2.5 Get-Subscriptions operation 3028 This operation allows a client to retrieve the values of attributes 3029 of all Subscription Objects belonging to a Job or Printer. 3031 A Printer MUST supported this operation. 3033 This operation is similar to the Get-Subscription-Attributes 3034 operation, except that this Get-Subscriptions operation returns 3035 attributes from possibly more than one object. 3037 This operation is similar to the Get-Jobs operation (see [RFC2911] 3038 section 3.2.6), except that the operation returns Subscription 3039 Objects rather than Job objects. 3041 Access Rights: To query Per-Job Subscription Objects of the 3042 specified job (client supplied the "notify-job-id" operation 3043 attribute - see section 11.2.5.1.1), the authenticated user (see 3044 [RFC2911] section 8.3) performing this operation MUST (1) be the 3045 Subscription Object owner, (2) have Operator or Administrator access 3046 rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3047 otherwise authorized by the Printer's administrator-configured 3048 security policy to query the Subscription Object for the target job. 3049 To query Per-Printer Subscription Objects of the Printer (client 3050 omits the "notify-job-id" operation attribute - see section 3051 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) 3052 performing this operation MUST (1) have Operator or Administrator 3053 access rights for this Printer (see [RFC2911] sections 1 and 8.5), or 3054 (2) be otherwise authorized by the Printer's administrator-configured 3055 security policy to query Per-Printer Subscription Objects for the 3056 target Printer. Otherwise the Printer MUST reject the operation and 3057 return: the 'client-error-forbidden', 'client-error-not- 3058 authenticated', or 'client-error-not-authorized' status code as 3059 appropriate. Furthermore, the Printer's security policy MAY limit 3060 which attributes are returned, in a manner similar to the Get-Jobs 3061 and Get-Printer-Attributes operations (see [RFC2911] end of sections 3062 3.2.6.2 and 3.2.5.2). 3064 11.2.5.1 Get-Subscriptions Request 3066 The following groups of attributes are part of the Get-Subscriptions 3067 request: 3069 Group 1: Operation Attributes 3071 Natural Language and Character Set: 3072 The "attributes-charset" and "attributes-natural-language" 3073 attributes as described in [RFC2911] section 3.1.4.1. 3075 Target: 3076 The "printer-uri" attribute which defines the target for this 3077 operation as described in [RFC2911] section 3.1.5. 3079 Requesting User Name: 3080 The "requesting-user-name" attribute SHOULD be supplied by the 3081 client as described in [RFC2911] section 8.3. 3083 11.2.5.1.1 "notify-job-id" (integer(1:MAX)) 3085 If the client specifies this attribute, the Printer returns the 3086 specified attributes of all Per-Job Subscription Objects 3087 associated with the Job whose "job-id" attribute value equals 3088 the value of this attribute. If the client does not specify 3089 this attribute, the Printer returns the specified attributes of 3090 all Per-Printer Subscription Objects. Note: there is no way to 3091 get all Per-Job Subscriptions known to the Printer in a single 3092 operation. A Get-Jobs operation followed by a Get- 3093 Subscriptions operation for each Job will return all Per-Job 3094 Subscriptions. 3096 11.2.5.1.2 "limit" (integer(1:MAX)) 3098 The client OPTIONALLY supplies this attribute. The Printer 3099 MUST support this attribute. It is an integer value that 3100 determines the maximum number of Subscription Objects that a 3101 client will receive from the Printer even if the "my- 3102 subscriptions" attribute constrains which Subscription Objects 3103 are returned. The limit is a "stateless limit" in that if the 3104 value supplied by the client is 'N', then only the first 'N' 3105 Subscription Objects are returned in the Get-Subscriptions 3106 Response. There is no mechanism to allow for the next 'M' 3107 Subscription Objects after the first 'N' Subscription Objects. 3108 If the client does not supply this attribute, the Printer 3109 responds with all applicable Subscription Objects. 3111 11.2.5.1.3 "requested-attributes" (1setOf type2 keyword) 3113 The client OPTIONALLY supplies this attribute. The Printer 3114 MUST support this attribute. This attribute specifies the 3115 attributes of the specified Subscription Objects that the 3116 Printer MUST return in the response. Each value of this 3117 attribute is either an attribute name (defined in sections 5.3 3118 and 5.4) or an attribute group name (defined in section 3119 11.2.4.1). If the client omits this attribute, the Printer 3120 MUST respond as if the client had supplied this attribute with 3121 the one value: 'notify-subscription-id'. 3123 11.2.5.1.4 "my-subscriptions" (boolean) 3125 The client OPTIONALLY supplies this attribute. The Printer 3126 MUST support this attribute. If the value is 'false', the 3127 Printer MUST consider the Subscription Objects from all users 3128 as candidates. If the value is 'true', the Printer MUST return 3129 the Subscription Objects created by the requesting user of this 3130 request. If the client does not supply this attribute, the 3131 Printer MUST respond as if the client had supplied the 3132 attribute with a value of 'false'. The means for 3133 authenticating the requesting user and matching the 3134 Subscription Objects is similar to that for Jobs which is 3135 described in [RFC2911] section 8. 3137 11.2.5.2 Get-Subscriptions Response 3139 The Printer returns the following sets of attributes as part of the 3140 Get-Subscriptions Response: 3142 Group 1: Operation Attributes 3144 Status Message: 3145 Same as [RFC2911]. 3147 Natural Language and Character Set: 3148 The "attributes-charset" and "attributes-natural-language" 3149 attributes as described in [RFC2911] section 3.1.4.2. 3151 Group 2: Unsupported Attributes 3153 Same as for Get-Subscription-Attributes. 3155 Groups 3 to N: Subscription Attributes 3157 The Printer responds with one Subscription Attributes Group for 3158 each requested Subscription Object (see the "notify-job-id" 3159 attribute in the Operation Attributes Group of this operation). 3161 The Printer returns Subscription Objects in any order. 3163 If the "limit" attribute is present in the Operation Attributes 3164 group of the request, the number of Subscription Attributes 3165 Groups in the response MUST NOT exceed the value of the "limit" 3166 attribute. 3168 It there are no Subscription Objects associated with the 3169 specified Job or Printer, the Printer MUST return zero 3170 Subscription Attributes Groups and it MUST NOT treat this case 3171 as an error, i.e., the status-code MUST be 'successful-ok' 3172 unless something else causes the status code to have some other 3173 value. 3175 See the Group 3 response (Subscription Attributes Group) of the 3176 Get-Subscription-Attributes operation (section 11.2.4.2) for 3177 the attributes that a Printer returns in this group. 3179 11.2.6 Renew-Subscription operation 3181 This operation allows a client to request the Printer to extend the 3182 lease on a Per-Printer Subscription Object. 3184 The Printer MUST support this operation. 3186 The Printer MUST accept this request for a Per-Printer Subscription 3187 Object in any of the target Printer's states, i.e., 'idle', 3188 'processing', or 'stopped', but MUST NOT change the Printer's 3189 "printer-state" attribute. 3191 The Printer MUST reject this request for a Per-Job Subscription 3192 Object because it has no lease (see section 5.4.3). The status code 3193 returned MUST be 'client-error-not-possible'. 3195 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3196 performing this operation MUST (1) be the owner of the Per-Printer 3197 Subscription Object, (2) have Operator or Administrator access rights 3198 for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be 3199 otherwise authorized by the Printer's administrator-configured 3200 security policy to renew Per-Printer Subscription Objects for the 3201 target Printer. Otherwise, the Printer MUST reject the operation and 3202 return: the 'client-error-forbidden', 'client-error-not- 3203 authenticated', or 'client-error-not-authorized' status code as 3204 appropriate. 3206 11.2.6.1 Renew-Subscription Request 3208 The following groups of attributes are part of the Renew-Subscription 3209 Request: 3211 Group 1: Operation Attributes 3213 Natural Language and Character Set: 3214 The "attributes-charset" and "attributes-natural-language" 3215 attributes as described in [RFC2911] section 3.1.4.1. 3217 Target: 3218 The "printer-uri" attribute which defines the target for this 3219 operation as described in [RFC2911] section 3.1.5. 3221 Requesting User Name: 3222 The "requesting-user-name" (name(MAX)) attribute SHOULD be 3223 supplied by the client as described in [RFC2911] section 8.3. 3225 11.2.6.1.1 "notify-subscription-id" (integer (1:MAX)) 3227 The client MUST supply this attribute. The Printer MUST 3228 support this attribute. This attribute specifies the Per- 3229 Printer Subscription Object whose lease the Printer MUST renew. 3230 If the client omits this attribute, the Printer MUST reject 3231 this request with the 'client-error-bad-request' status code. 3233 Group 2: Subscription Template Attributes 3235 11.2.6.1.2 "notify-lease-duration" (integer(0:MAX)) 3237 The client MAY supply this attribute. It indicates the number 3238 of seconds to renew the lease for the specified Subscription 3239 Object. A value of 0 requests an infinite lease (which MAY 3240 require Operator access rights). If the client omits this 3241 attribute, the Printer MUST use the value of the Printer's 3242 "notify-lease-duration-default" attribute. See section 5.3.8 3243 for more details. 3245 11.2.6.2 Renew-Subscription Response 3247 The Printer returns the following sets of attributes as part of the 3248 Renew-Subscription Response: 3250 Group 1: Operation Attributes 3252 Status Message: 3253 Same as [RFC2911]. 3255 The following are some of the status codes returned (see 3256 [RFC2911]: 3258 successful-ok: The operation successfully renewed the lease 3259 on the Subscription Object for the requested duration. 3260 successful-ok-ignored-or-substituted-attributes: The 3261 operation successfully renewed the lease on the 3262 Subscription Object for some duration other than the 3263 amount requested. 3264 client-error-not-possible: The operation failed because the 3265 "notify-subscription-id" Operation attribute identified a 3266 Per-Job Subscription Object. 3267 client-error-not-found: The operation failed because the 3268 "notify-subscription-id" Operation attribute identified a 3269 non-existent Subscription Object. 3271 Natural Language and Character Set: 3272 The "attributes-charset" and "attributes-natural-language" 3273 attributes as described in [RFC2911] section 3.1.4.2. The 3274 "attributes-natural-language" MAY be the natural language of 3275 the Subscription Object, rather than the one requested. 3277 Group 2: Unsupported Attributes 3279 See [RFC2911] section 3.1.7 for details on returning 3280 Unsupported Attributes. 3282 Group 3: Subscription Attributes 3284 The Printer MUST return the following Subscription Attribute: 3286 11.2.6.2.1 "notify-lease-duration" (integer(0:MAX)) 3288 The value of this attribute MUST be the number of seconds that 3289 the Printer has granted for the lease of the Subscription 3290 Object (see section 5.3.8 for details, such as the value of 3291 this attribute when the Printer doesn't support the requested 3292 value). 3294 11.2.7 Cancel-Subscription operation 3296 This operation allows a client to delete a Subscription Object and 3297 stop the Printer from delivering more Event Notifications. Once 3298 performed, there is no way to reference the Subscription Object. 3300 A Printer MUST supported this operation. 3302 The Printer MUST accept this request in any of the target Printer's 3303 states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change 3304 the Printer's "printer-state" attribute. 3306 If the specified Subscription Object is a Per-Job Subscription 3307 Object, the Printer MUST accept this request in any of the target 3308 Job's states, but MUST NOT change the Job's "job-state" attribute or 3309 affect the Job. 3311 Note: There is no way to change any attributes on a Subscription 3312 Object, except the "notify-lease-duration" attribute (using the 3313 Renew-Subscription operation). In order to change other attributes, 3314 a client performs a Subscription Creation Operation and Cancel- 3315 Subscription operation on the old Subscription Object. If the client 3316 wants to avoid missing Event Notifications, it performs the 3317 Subscription Creation Operation first. If this order would create 3318 too many Subscription Objects on the Printer, the client reverses the 3319 order. 3321 Access Rights: The authenticated user (see [RFC2911] section 8.3) 3322 performing this operation MUST (1) be the owner of the Subscription 3323 Object, (2) have Operator or Administrator access rights for the 3324 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 3325 authorized by the Printer's administrator-configured security policy 3326 to cancel the target Subscription Object. Otherwise, the Printer 3327 MUST reject the operation and return: the 'client-error-forbidden', 3328 'client-error-not-authenticated', or 'client-error-not-authorized' 3329 status code as appropriate. 3331 11.2.7.1 Cancel-Subscription Request 3333 The following groups of attributes are part of the Cancel- 3334 Subscription Request: 3336 Group 1: Operation Attributes 3338 Natural Language and Character Set: 3339 The "attributes-charset" and "attributes-natural-language" 3340 attributes as described in [RFC2911] section 3.1.4.1. 3342 Target: 3343 The "printer-uri" attribute which defines the target for this 3344 operation as described in [RFC2911] section 3.1.5. 3346 Requesting User Name: 3347 The "requesting-user-name" attribute SHOULD be supplied by the 3348 client as described in [RFC2911] section 8.3. 3350 11.2.7.1.1 "notify-subscription-id" (integer (1:MAX)) 3352 The client MUST supply this attribute. The Printer MUST 3353 support this attribute. This attribute specifies the 3354 Subscription Object that the Printer MUST cancel. If the 3355 client omits this attribute, the Printer MUST reject this 3356 request with the 'client-error-bad-request' status code. 3358 11.2.7.2 Cancel-Subscription Response 3360 The Printer returns the following sets of attributes as part of the 3361 Cancel-Subscription Response: 3363 Group 1: Operation Attributes 3365 Status Message: 3366 Same as [RFC2911]. 3368 The following are some of the status codes returned (see 3369 [RFC2911]: 3371 successful-ok: The operation successfully canceled 3372 (deleted) the Subscription Object. 3373 client-error-not-found: The operation failed because the 3374 "notify-subscription-id" Operation attribute identified a 3375 non-existent Subscription Object. 3377 Natural Language and Character Set: 3378 The "attributes-charset" and "attributes-natural-language" 3379 attributes as described in [RFC2911] section 3.1.4.2. The 3380 "attributes-natural-language" MAY be the natural language of 3381 the Subscription Object, rather than the one requested. 3383 Group 2: Unsupported Attributes 3385 See [RFC2911] section 3.1.7 for details on returning 3386 Unsupported Attributes. 3388 12 Status Codes 3390 The following status codes are defined as extensions for Notification 3391 and are returned as the value of the "status-code" parameter in the 3392 Operation Attributes Group of a response (see [RFC2911] section 3393 3.1.6.1). Operations in this document can also return the status 3394 codes defined in section 13 of [RFC2911]. The 'successful-ok' status 3395 code is an example of such a status code. 3397 12.1 successful-ok-ignored-subscriptions (0x0003) 3399 The Subscription Creation Operation was unable to create all 3400 requested Subscription Objects. 3402 For a Create-Job-Subscriptions or Create-Printer-Subscriptions 3403 operation, this status code means that the Printer created one or 3404 more Subscription Objects, but not all requested Subscription 3405 Objects. 3407 For a Job Creation operation, this status code means that the Printer 3408 created the Job along with zero or more Subscription Objects. The 3409 Printer returns this status code even if other job attributes are 3410 unsupported or in conflict. That is, if an IPP Printer finds a 3411 warning that would allow it to return 'successful-ok-ignored- 3412 subscriptions' and either 'successful-ok-ignored-or-substituted- 3413 attributes' and/or 'successful-ok-conflicting-attributes', it MUST 3414 return 'successful-ok-ignored-subscriptions'. 3416 12.2 client-error-ignored-all-subscriptions (0x0414) 3418 This status code is the same as 'successful-ok-ignored-subscriptions' 3419 except that only the Create-Job-Subscriptions and Create-Printer- 3420 Subscriptions operation return it. They return this status code only 3421 when the Printer creates zero Subscription Objects. 3423 13 Status Codes in Subscription Attributes Groups 3425 This section contains values of the "notify-status-code" (type2 enum) 3426 attribute that the Printer returns in a Subscription Attributes Group 3427 in a response when the corresponding Subscription Object: 3429 1.is not created or 3431 2.is created and some of the client-supplied attributes are not 3432 supported. 3434 The following sections are ordered in decreasing order of importance 3435 of the status-codes. 3437 13.1 client-error-uri-scheme-not-supported (0x040C) 3439 This status code is defined in [RFC2911]. This document extends its 3440 meaning and allows it to be in a Subscription Attributes Group of a 3441 response. 3443 The scheme of the client-supplied URI in a "notify-recipient-uri" 3444 Subscription Template Attribute in a Subscription Creation Operation 3445 is not supported. See section 5.3.1. 3447 13.2 client-error-attributes-or-values-not-supported (0x040B) 3449 This status code is defined in [RFC2911]. This document extends its 3450 meaning and allows it to be in a Subscription Attributes Group of a 3451 response. 3453 The method of the client-supplied keyword in a "notify-pull-method" 3454 Subscription Template Attribute in a Subscription Creation Operation 3455 is not supported. See section 5.3.2. 3457 13.3 client-error-too-many-subscriptions (0x0415) 3459 The number of Subscription Objects supported by the Printer would be 3460 exceeded if this Subscription Object were created (see section 5.2). 3462 13.4 successful-ok-too-many-events (0x0005) 3464 The client supplied more Events in the "notify-events" operation 3465 attribute of a Subscription Creation Operation than the Printer 3466 supports, as indicated in its "notify-max-events-supported" Printer 3467 attribute (see section 5.3.3). 3469 13.5 successful-ok-ignored-or-substituted-attributes (0x0001) 3471 This status code is defined in [RFC2911]. This document extends its 3472 meaning to include unsupported Subscription Template Attributes and 3473 it can appear in a Subscription Attributes Group. 3475 14 Encodings of Additional Attribute Tags 3477 This section assigns values to two attributes tags as extensions to 3478 the encoding defined in [RFC2910]). 3480 The "subscription-attributes-tag" delimits Subscription Template 3481 Attributes Groups in requests and Subscription Attributes Groups in 3482 responses. 3484 The "event-notification-attributes-tag" delimits Event Notifications 3485 in Delivery Methods that use an IPP-like encoding. 3487 The following table specifies the values for the delimiter tags: 3489 Tag Value (Hex) Meaning 3491 0x06 "subscription-attributes-tag" 3493 0x07 "event-notification-attributes-tag" 3495 15 Conformance Requirements 3497 It is OPTIONAL for IPP clients and Printers to implement this Event 3498 Notification specification. 3500 15.1 Conformance requirements for clients 3502 If this Event Notification specification is implemented by a client, 3503 the client MUST support the 'ippget' Pull Delivery Method and meet 3504 the conformance requirements as defined in [ipp-get-method] for 3505 clients. A client MAY support additional Delivery Methods. 3507 15.2 Conformance requirements for Printers 3509 If this Event Notification specification is implemented by a Printer, 3510 the Printer MUST: 3512 - meet the Conformance Requirements detailed in section 5 of 3513 [RFC2911]. 3515 - support the Subscription Template Attributes Group in requests 3516 and the Subscription Attributes Group in responses. 3518 - support all of the following attributes: 3520 a.REQUIRED Subscription Object attributes in section 5. 3521 b.REQUIRED Printer Description object attributes in section 6. 3522 c.REQUIRED attributes in Event Notification content in section 3523 8. 3525 - support the 'ippget' Pull Delivery Method and meet the 3526 conformance requirements as defined in [ipp-get-method] for 3527 Printers. The Printer MAY support additional Push and Pull 3528 Delivery Methods. 3530 - deliver Event Notifications that conform to the requirements of 3531 section 9 and the requirements of the Delivery Method Document 3532 for each supported Delivery Method (the conformance 3533 requirements for Delivery Method Documents is specified in 3534 section 10). 3536 - for all of the Job Creation Operations that the Printer 3537 supports, MUST support the REQUIRED extensions for notification 3538 defined in section 11.1.3. 3540 - meet the conformance requirements for operations as described 3541 in Table 16 and meet the requirements for Printers as specified 3542 in the indicated sub-sections of section 11: 3544 Table 16 - Printer Conformance Requirements for Operations 3546 Operation Printer 3547 Conformance 3548 Requirements 3550 Create-Printer-Subscriptions (section 11.1.2) REQUIRED 3552 Create-Job-Subscriptions (section 11.1.1) OPTIONAL 3554 Get-Subscription-Attributes (section 11.2.3) REQUIRED 3556 Get-Subscriptions (section 11.2.5) REQUIRED 3558 Renew-Subscription (section 11.2.6) REQUIRED 3560 Cancel-Subscription (section 11.2.7) REQUIRED 3562 16 Appendix A - Model for Notification with Cascading Printers 3563 (Informative) 3565 With this model (see Figure 2 below), there is an intervening Print 3566 server between the human user and the output-device. So the system 3567 effectively has two Printer objects. There are two cases to 3568 consider. 3570 1.When the Printer 1 (in the server) generates Events, the system 3571 behaves like the client and Printer in Figure 1. In this case, 3572 Printer 1 delivers Event Notifications that are shown as Event 3573 Notifications (A) of Figure 2. 3575 2.When the Printer 2 (in the output-device) generates Events, there 3576 are two possible system configurations: 3578 a)Printer 1 forwards the client-supplied Subscription Creation 3579 Operations to the downstream Printer 2 and lets Printer 2 3580 deliver the Event Notifications directly to the Notification 3581 Recipients supplied by the Client (Event Notifications(C) in the 3582 diagram). 3584 b)Printer 1 performs the client-supplied Subscription Creation 3585 Operations and also forwards the Subscription Creation 3586 Operations to Printer 2 with the Notification Recipient changed 3587 to be the Printer 1. When an Event occurs in Printer 2, Printer 3588 2 delivers the Event Notification (B) to Notification Recipient 3589 of Printer 1, which relays the received Event Notification (B) 3590 to the client-supplied Notification Recipient (as Event 3591 Notifications(A) in the diagram). Note, when a client performs 3592 a Subscription Creation Operation, Printer 1 need not forward 3593 the Subscription Creation Operation to Printer 2 if it would 3594 create a duplicate Subscription Object on Printer 2. 3596 Note: when Printer 1 is forwarding Subscription Creation Operations 3597 to Printer 2, it may request Printer 2 to create additional 3598 Subscription Objects (called "piggy-backing"). Piggy-backing is 3599 useful when: 3601 - Device A is configured to accept (IPP or non-IPP) requests from 3602 other servers. 3604 - Server S wants to receive Job Events that the client didn't 3605 request and Server S wants these Events for jobs it submits and 3606 not for other jobs. 3608 server S device A 3609 +------------+ +------------+ 3610 | | | | 3611 +--------+ Subscription | ###########| | ###########| 3612 | client |--Creation ----># Printer #| Subscription | # Printer #| 3613 +--------+ Operation | # Object 1#|---Creation------|># Object 2#| 3614 | ###|#######| Operation | ####|#|####| 3615 +----|---^---+ +-----|-|----+ 3616 +--------+ Event | | | | 3617 |Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ | 3618 |ation Re|<-------------Event Notifications(C)-----------------+ 3619 |cipient | 3620 +--------+ 3622 Figure 2 - Model for Notification with Cascading Printers 3624 17 Appendix B - Distributed Model for Notification (Informative) 3626 A Printer implementation could use some other remote notification 3627 server to provide some or most of the service. For example, the 3628 remote notification server could deliver Event Notifications using 3629 Delivery Methods that are not directly supported by the output device 3630 or Printer object. Or, the remote notification server could store 3631 Subscription Objects (passed to it from the output device in response 3632 to Subscription Creation requests), accept Events, format the Event 3633 Notification in the natural language of the Notification Recipient, 3634 and deliver the Event Notifications to the Notification Recipient(s). 3636 Figure 3 shows this partitioning. The interface between the output 3637 device (or Printer object) and the remote notification server is 3638 outside the scope of this document and is intended to be transparent 3639 to the client and this document. 3641 *********************** 3642 * 3643 * Printer in combination 3644 * with the distributed 3645 * Notification Server) 3646 * 3647 * output device or server 3648 * +---------------+ 3649 PDA, desktop, or server * + ########### + 3650 +--------+ * | # # | 3651 | client |---IPP Subscription--------># Printer # | 3652 +--------+ Creation operation * | # Object # | 3653 * | #####|##### | 3654 * +-------|-------+ 3655 * | Subscriptions 3656 * | OR Event 3657 +------------+ * | Notifications 3658 |Notification| IPP-defined * +------v--------+ 3659 |Recipient |<--Event Notifications---| Notification | 3660 +------------+ * | Server | 3661 * +---------------+ 3662 * 3663 ************************* 3664 *** = Implementation configuration opaque boundary 3666 Figure 3 - Opaque Use of a Notification Server Transparent to the 3667 Client 3669 18 Appendix C - Extended Notification Recipient (Informative) 3671 The model allows for an extended Notification Recipient that is 3672 itself a notification server that forwards each Event Notification to 3673 another recipient (called the Ultimate Notification Recipient in this 3674 section). The Delivery Method to the Ultimate Recipient is probably 3675 different from the Delivery Method used by the Printer to the 3676 extended Notification Recipient. 3678 This extended Notification Recipient is transparent to the Printer 3679 but not to the client. 3681 When a client performs a Subscription Creation Operation, it 3682 specifies the extended Notification Recipient as it would any 3683 Notification Recipient. In addition, the client specifies the 3684 Ultimate Notification Recipient in the Subscription Creation 3685 Operation in a manner specified by the extended Notification 3686 Recipient. Typically, it is either some bytes in the value of 3687 "notify-user-data" or some additional parameter in the value of 3688 "notify-recipient-uri". The client also subscribes directly with the 3689 extended Notification Recipient (by means outside this document), 3690 since it is a notification server in its own right. 3692 The IPP Printer treats the extended Notification Recipient like any 3693 other Notification Recipient and the IPP Printer is not aware of the 3694 forwarding. The Delivery Method that the extended Notification 3695 Recipient uses for delivering the Event Notification to the Ultimate 3696 Notification Recipient is beyond the scope of this document and is 3697 transparent to the IPP Printer. 3699 Examples of this extended Notification Recipient are paging, 3700 immediate messaging services, general notification services, and NOS 3701 vendors' infrastructure. Figure 4 shows this approach. 3703 PDA, desktop, or server server or output device 3704 +---------------+ 3705 +--------+ | ########### | 3706 | client |---Subscription Creation -----------># Printer # | 3707 +--------+ Operation | # Object # | 3708 | #####|##### | 3709 +------------+ +------------+ IPP-defined +-------|-------+ 3710 |Ultimate | any |Notification|<--Event Notifications----+ 3711 |Notification|<----|Recipient | 3712 |Recipient | +------------+ 3713 +------------+ (Notification Server) 3715 Figure 4 - Use of an Extended Notification Recipient transparent to 3716 the Printer 3718 19 Appendix D - Details about Conformance Terminology (Normative) 3720 The following paragraphs provide more details about conformance 3721 terminology. 3723 REQUIRED - an adjective used to indicate that a conforming IPP 3724 Printer implementation MUST support the indicated operation, 3725 object, attribute, attribute value, status code, or out-of-band 3726 value in requests and responses. See [RFC2911] "Appendix A - 3727 Terminology for a definition of "support". Since support of this 3728 entire Notification specification is OPTIONAL for conformance to 3729 IPP/1.1, the use of the term REQUIRED in this document means 3730 "REQUIRED if this OPTIONAL Notification specification is 3731 implemented". 3733 RECOMMENDED - an adjective used to indicate that a conforming IPP 3734 Printer implementation is recommended to support the indicated 3735 operation, object, attribute, attribute value, status code, or 3736 out-of-band value in requests and responses. Since support of 3737 this entire Notification specification is OPTIONAL for conformance 3738 to IPP/1.1, the use of the term RECOMMENDED in this document means 3739 "RECOMMENDED if this OPTIONAL Notification specification is 3740 implemented". 3742 OPTIONAL - an adjective used to indicate that a conforming IPP 3743 Printer implementation MAY, but is NOT REQUIRED to, support the 3744 indicated operation, object, attribute, attribute value, status 3745 code, or out-of-band value in requests and responses. 3747 20 Appendix E - Object Model for Notification (Normative) 3749 This section describes the Notification object model that adds a 3750 Subscription Object which together with the Job and Printer object 3751 provide the complete Notification semantics. 3753 The object relationships can be seen pictorially as: 3755 Subscription Objects (Per-Printer Subscriptions) Printer object 3756 +----+ +------------+ 3757 | s1 |<--------------------------------------------->| | 3758 +----++ | | 3759 | s2 |<-------------------------------------------->| p1 | 3760 +----++ | | 3761 | s3 |<------------------------------------------->| | 3762 +----+ +------------+ 3763 Job objects 3764 +---------+ 3765 | | 3766 +----+ | j1 | 3767 | s4 |<------->| | 3768 +----+ | | 3769 | | s4 is a Per-Job Subscription Object 3770 ++--------++ 3771 | | 3772 +----+ | j2 | 3773 | s5 |<------>| | 3774 +----++ | | 3775 | s6 |<----->| | s5 and s6 are Per-Job Subscription 3776 +----+ ++--------++ Objects 3777 | | 3778 | j3 | 3779 | | 3780 | | <----> indicates association 3781 +---------+ 3783 Figure 5 - Object Model for Notification 3785 s1, s2, and s3 are Per-Printer Subscription Objects and can 3786 identify Printer and/or Job Events. 3787 s4, s5, and s6 are Per-Job Subscription Objects and can identify 3788 Printer and/or Job Events. 3790 20.1 Object relationships 3792 This sub-section defines the object relationships between the 3793 Printer, Job, and Subscription Objects by example. Whether Per- 3794 Printer Subscription Objects are actually contained in a Printer 3795 object or are just bi-directionally associated with them in some way 3796 is IMPLEMENTATION DEPENDENT and is transparent to the client. 3797 Similarly, whether Per-Job Subscription Objects are actually 3798 contained in a Job object or are just bi-directionally associated 3799 with them in some way is IMPLEMENTATION DEPENDENT and is transparent 3800 to the client. The object relationships are defined as follows: 3802 20.2 Printer Object and Per-Printer Subscription Objects 3804 1.The Printer object contains (is associated with) zero or more 3805 Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer 3806 Subscription Objects). 3808 2.Each Per-Printer Subscription Object (s1, s2, and s3) is 3809 contained in (or is associated with) exactly one Printer object 3810 (p1). 3812 20.3 Job Object and Per-Job Subscription Objects 3814 1.A Job object (j1, j2, j3) is associated with zero or more Per- 3815 Job Subscription Objects (s4-s6). Job j1 is associated with 3816 Per-Job Subscription Object s4, Job j2 is associated with Per- 3817 Job Subscription Objects s5 and s6, and Job j3 is not associated 3818 with any Per-Job Subscription Object. 3820 2.Each Per-Job Subscription Object is associated with exactly one 3821 Job object. 3823 21 Appendix F - Per-Job versus Per-Printer Subscription Objects 3824 (Normative) 3826 Per-Job and Per-Printer Subscription Objects are quite similar. 3827 Either type of Subscription Object can subscribe to Job Events, 3828 Printer Events, or both. Both types of Subscription Objects can be 3829 queried using the Get-Subscriptions and Get-Subscription-Attributes 3830 operations and canceled using the Cancel-Subscription operation. 3831 Both types of Subscription Objects create Subscription Objects which 3832 have the same Subscription Object attributes defined. However, there 3833 are some semantic differences between Per-Job Subscription Objects 3834 and Per-Printer Subscription Objects. A Per-Job Subscription Object 3835 is established by the client when submitting a job and after creating 3836 the job using the Create-Job-Subscriptions operation by specifying 3837 the "job-id" of the Job with the "notify-job-id" attribute. A Per- 3838 Printer Subscription Object is established between a client and a 3839 Printer using the Create-Printer-Subscriptions operation. Some 3840 specific differences are: 3842 1.A client usually creates one or more Per-Job Subscription 3843 Objects as part of the Job Creation operations (Create-Job, 3844 Print-Job, and Print-URI), rather than using the OPTIONAL 3845 Create-Job-Subscriptions operation, especially since Printer 3846 implementations NEED NOT support the Create-Job-Subscriptions 3847 operation, since it is OPTIONAL. 3849 2.For Per-Job Subscription Objects, the Subscription Object is 3850 only valid while the job is "not-complete" (see sections 5.4.3) 3851 while for the Per-Printer Subscription Objects, the Subscription 3852 Object is valid until the time (in seconds) that the Printer 3853 returned in the "notify-lease-expiration-time" operation 3854 attribute. 3856 3.Job Events in a Per-Job Subscription Object apply only to "one 3857 job" (the Job created by the Job Creation operation or 3858 references by the Create-Job-Subscriptions operation) while Job 3859 Events in a Per-Printer Subscription Object apply to ALL jobs 3860 contained in the IPP Printer. 3862 22 Normative References 3864 [ipp-get-method] 3865 Herriot, R., and T. Hastings, "Internet Printing Protocol (IPP): 3866 The 'ippget' Delivery Method for Event Notifications", , September 10, 2002. 3869 [RFC2119] 3870 S. Bradner, "Key words for use in RFCs to Indicate Requirement 3871 Levels", RFC 2119 , March 1997 3873 [RFC2396] 3874 Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource 3875 Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 3877 [RFC2717] 3878 R. Petke and I. King, "Registration Procedures for URL Scheme 3879 Names", RFC 2717, November 1999. 3881 [RFC2910] 3882 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3883 Printing Protocol/1.1: Encoding and Transport", RFC 2910, September 3884 2000. 3886 [RFC2911] 3887 deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, 3888 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 3889 September 2000. 3891 [RFC3381] 3892 Hastings, T., Lewis, H., and R. Bergman, "IPP: Job Progress 3893 Attributes", RFC 3381, September 2002. 3895 23 Informative References 3897 [IANA-CON] 3898 Narte, T. and H. Alvestrand, "Guidelines for Writing an IANA 3899 Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 3901 [ipp-not-req] 3902 deBry, R., Lewis, H., and T. Hastings, "Internet Printing 3903 Protocol/1.1: Requirements for IPP Notifications", , work in progress, July 17, 2001. 3906 [RFC2565] 3907 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 3908 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 3909 1999. 3911 [RFC2566] 3912 deBry, R., , Hastings, T., Herriot, R., Isaacson, S., and P. 3913 Powell, "Internet Printing Protocol/1.0: Model and Semantics", RFC 3914 2566, April 1999. 3916 [RFC2567] 3917 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 3918 2567, April 1999. 3920 [RFC2568] 3921 Zilles, S., "Rationale for the Structure and Model and Protocol for 3922 the Internet Printing Protocol", RFC 2568, April 1999. 3924 [RFC2569] 3925 Herriot, R., Hastings, T., Jacobs, N., and J. Martin, "Mapping 3926 between LPD and IPP Protocols", RFC 2569, April 1999. 3928 [RFC2616] 3929 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., 3930 Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol - 3931 HTTP/1.1", RFC 2616, June 1999. 3933 [RFC3196] 3934 Hastings, T., Manros, C., Zehler, P., Kugler, C., and H. Holst, 3935 "Internet Printing Protocol/1.1: Implementer's Guide", RFC3196, 3936 November 2001. 3938 24 IANA Considerations 3940 This section contains the registration information for IANA to add to 3941 the various IPP Registries according to the procedures defined in RFC 3942 2911 [RFC2911] section 6 to cover the definitions in this document. 3944 In addition, this section defines how Events and Delivery Methods 3945 will be registered when they are defined in other documents. The 3946 resulting registrations will be published in the 3947 http://www.iana.org/assignments/ipp-registrations registry. 3949 Note to RFC Editors: Replace RFC NNNN below with the RFC number 3950 for this document, so that it accurately reflects the content of 3951 the information for the IANA Registry. 3953 24.1 Attribute Registrations 3955 The following table lists all the attributes defined in this 3956 document. These are to be registered according to the procedures in 3957 RFC 2911 [RFC2911] section 6.2. 3959 Subscription Template attributes: Ref. Section: 3960 notify-attributes (1setOf type2 keyword) RFC NNNN 5.3.4 3961 notify-attributes-supported (1setOf type2 keyword) 3962 RFC NNNN 5.3.4.1 3963 notify-charset (charset) RFC NNNN 5.3.6 3964 notify-events (1setOf type2 keyword) RFC NNNN 5.3.3 3965 notify-events-default (1setOf type2 keyword) RFC NNNN 5.3.3.1 3966 notify-events-supported (1setOf type2 keyword) RFC NNNN 5.3.3.2 3967 notify-lease-duration (integer(0:67108863)) RFC NNNN 5.3.8 3968 notify-lease-duration-default (integer(0:67108863)) 3969 RFC NNNN 5.3.8.1 3970 notify-lease-duration-supported (1setOf (integer(0: 67108863) | 3971 rangeOfInteger(0:67108863))) RFC NNNN 5.3.8.2 3972 notify-max-events-supported (integer(2:MAX)) RFC NNNN 5.3.3.3 3973 notify-natural-language (naturalLanguage) RFC NNNN 5.3.7 3974 notify-pull-method (type2 keyword) RFC NNNN 5.3.2 3975 notify-pull-method-supported (1setOf type2 keyword) 3976 RFC NNNN 5.3.2.1 3977 notify-recipient-uri (uri) RFC NNNN 5.3.1 3978 notify-schemes-supported (1setOf uriScheme) RFC NNNN 5.3.1.1 3979 notify-time-interval (integer(0:MAX)) RFC NNNN 5.3.9 3980 notify-user-data (octetString(63)) RFC NNNN 5.3.5 3982 Subscription Description Attributes: 3983 notify-job-id (integer(1:MAX))) RFC NNNN 5.4.6 3984 notify-lease-expiration-time (integer(0:MAX))) RFC NNNN 5.4.3 3985 notify-printer-up-time (integer(1:MAX))) RFC NNNN 5.4.4 3986 notify-printer-uri (uri)) RFC NNNN 5.4.5 3987 notify-sequence-number (integer (0:MAX))) RFC NNNN 5.4.2 3988 notify-subscriber-user-name (name(MAX))) RFC NNNN 5.4.7 3989 notify-subscription-id (integer (1:MAX))) RFC NNNN 5.4.1 3991 Printer Description Attributes: 3993 printer-state-change-date-time (dateTime)) RFC NNNN 6.2 3994 printer-state-change-time (integer(1:MAX))) RFC NNNN 6.1 3996 Attributes Only in Event Notifications 3997 notify-subscribed-event (type2 keyword) RFC NNNN 8.1 3998 notify-text (text(MAX)) RFC NNNN 8.2 4000 24.2 Additional Enum Attribute Value Registrations 4002 The following table lists all the new enum attribute values defined 4003 in this document. These are to be registered according to the 4004 procedures in RFC 2911 [RFC2911] section 6.1. 4006 Attribute 4007 Value Name Reference Section 4008 ------ ----------------------------- --------- ------- 4009 operations-supported (type2 enum) RFC2911 4.4.15 4010 0x0016 Create-Printer-Subscriptions RFC NNNN 7.1 4011 0x0017 Create-Job-Subscriptions RFC NNNN 7.1 4012 0x0018 Get-Subscription-Attributes RFC NNNN 7.1 4013 0x0019 Get-Subscriptions RFC NNNN 7.1 4014 0x001A Renew-Subscription RFC NNNN 7.1 4015 0x001B Cancel-Subscription RFC NNNN 7.1 4017 24.3 Operation Registrations 4019 The following table lists all of the operations defined in this 4020 document. These are to be registered according to the procedures in 4021 RFC 2911 [RFC2911] section 6.4. 4023 Operations: Ref. Section: 4024 Cancel-Subscription Operation RFC NNNN 11.2.7 4025 Create-Job-Subscriptions Operation RFC NNNN 11.1.1 4026 Create-Printer-Subscriptions Operation RFC NNNN 11.1.2 4027 Get-Printer-Attributes - Extensions RFC NNNN 11.2.3 4028 Get-Subscription-Attributes Operation RFC NNNN 11.2.4 4029 Get-Subscriptions Operation RFC NNNN 11.2.5 4030 Job Creation Operations - Extensions RFC NNNN 11.1.3 4031 Renew-Subscription Operation RFC NNNN 11.2.6 4032 Validate-Job Operation - Extensions RFC NNNN 11.2.2 4034 24.4 Status code Registrations 4036 The following table lists all the status codes defined in this 4037 document. These are to be registered according to the procedures in 4038 RFC 2911 [RFC2911] section 6.6. 4040 Value Name Ref. Section: 4041 ----- ------------------------------------ -------- ------- 4042 0x0000:0x00FF - "successful" 4043 0x0003 successful-ok-ignored-subscriptions RFC NNNN 12.1 4045 0x0400:0x04FF - "client-error" 4046 0x0414 client-error-ignored-all-subscriptions RFC NNNN 12.2 4048 24.5 Attribute Group tag Registrations 4050 The following table lists all the attribute group tags defined in 4051 this document. These are to be registered according to the 4052 procedures in RFC 2911 [RFC2911] section 6.5. 4054 Value Name Ref. Section 4055 ----- ------------------------------------ -------- ------- 4056 0x06 subscription-attributes-tag RFC NNNN 14 4057 0x07 event-notification-attributes-tag RFC NNNN 14 4059 24.6 Registration of Events 4061 When other document define additional type2 keywords to be used with 4062 the "notify-events" Subscription Template attribute (see section 4063 5.3.3)), these event keywords will be registered according to the 4064 procedures of [RFC2911] section 7.1 as additional attribute values 4065 for use with the "notify-events" Subscription Template attribute, 4066 i.e., the "notify-events", "notify-events-default", and "notify- 4067 events-supported" attributes. 4069 Therefore, the IPP Registry entry for an Event will be of the form: 4071 Attribute 4072 Value Ref. Section 4073 --------------------- -------- ------- 4074 notify-events (1setOf type2 keyword) 4075 notify-events-default (1setOf type2 keyword) 4076 notify-events-supported (1setOf type2 keyword) 4077 RFC xxxx m.n 4079 24.7 Registration of Event Notification Delivery Methods 4081 This section describes the requirements and procedures for 4082 registration and publication of Event Notification Delivery Methods 4083 and for the submission of such proposals. 4085 24.7.1 Requirements for Registration of Event Notification Delivery 4086 Methods 4088 Registered IPP Event Notification Delivery Methods are expected to 4089 follow a number of requirements described below. 4091 24.7.1.1 Required Characteristics 4093 A Delivery Method Document MUST either (1) contain all of the 4094 semantics of the Delivery Method or (2) contain the IPP Delivery 4095 Method registration requirements and a profile of some other protocol 4096 that in combination is the Delivery Method (e.g., mailto). The 4097 Delivery Method Document (and any documents it requires) MUST define 4098 either (1) a URL for a Push Delivery Method that the meets the 4099 requirements of [RFC2717]. or (2) a keyword for a Pull Delivery 4100 method. 4102 IPP Event Notification Delivery Method Documents MUST meet the 4103 requirements of this document (see sections 9 and 10). 4105 In addition, a Delivery Method Document MUST contain the following 4106 information: 4108 Type of registration: IPP Event Notification Delivery Method 4109 Name of this delivery method: 4110 Proposed URL scheme name of this Push Delivery Method or the 4111 keyword name of this Pull Delivery Method: 4112 Name of proposer: 4113 Address of proposer: 4114 Email address of proposer: 4115 Is this delivery method REQUIRED or OPTIONAL for conformance to the 4116 IPP Event Notification and Subscriptions document: 4117 Is this delivery method defining Machine Consumable and/or Human 4118 Consumable content: 4120 24.7.1.2 Naming Requirements 4122 Exactly one (URL scheme or keyword) name MUST be assigned to each 4123 Delivery Method. 4125 Each assigned name MUST uniquely identify a single Delivery Method. 4126 All Push Delivery Method names MUST conform to the rules for URL 4127 scheme names, according to [RFC2396] and [RFC2717] for schemes in the 4128 IETF tree. All Pull Delivery Method names MUST conform to the rules 4129 for keywords according to [RFC2911]. 4131 24.7.1.3 Functionality Requirements 4133 Delivery Methods MUST function as a protocol that is capable of 4134 delivering (push or pull) IPP Event Notifications to Notification 4135 Recipients. 4137 24.7.1.4 Usage and Implementation Requirements 4139 Use of a large number of Delivery Methods may hamper 4140 interoperability. However, the use of a large number of undocumented 4141 and/or unlabelled Delivery Methods hampers interoperability even 4142 more. 4144 A Delivery Method should therefore be registered ONLY if it adds 4145 significant functionality that is valuable to a large community, OR 4146 if it documents existing practice in a large community. Note that 4147 Delivery Methods registered for the second reason should be 4148 explicitly marked as being of limited or specialized use and should 4149 only be used with prior bilateral agreement. 4151 24.7.1.5 Publication Requirements 4153 Delivery Method Documents MUST be published in a standards track, 4154 informational, or experimental RFCs. 4156 24.7.2 Registration Procedure 4158 The IPP WG is developing a small number of Delivery Methods which are 4159 intended to be published as standards track RFCs. However, some 4160 parties may wish to register additional Delivery Methods in the 4161 future. This section describes the procedures for these additional 4162 Delivery Methods. 4164 24.7.2.1 Present the proposal to the Community 4166 First the Delivery Method Document MUST be an Internet-Draft with a 4167 target category of standards track, informational, or experimental. 4168 The same MUST be true for any documents that it references. 4170 Deliver the proposed Delivery Method Document proposal to the 4171 "ipp@pwg.org" mailing list. This mailing list has been established 4172 by [RFC2911] for reviewing proposed registrations and discussing 4173 other IPP matters. Proposed Delivery Method Documents are not 4174 formally registered and MUST NOT be used until approved. 4176 The intent of the public posting is to solicit comments and feedback 4177 on the definition and suitability of the Delivery Method and the name 4178 chosen for it over a four week period. 4180 24.7.2.2 Delivery Method Reviewer 4182 The Delivery Method Reviewer is the same person who has been 4183 appointed by the IETF Application Area Director(s) as the IPP 4184 Designated Expert according to [RFC2911] and [IANA-CON]. When the 4185 four week period is over and the IPP Designated Expert is convinced 4186 that consensus has been achieved, the IPP Designated Expert either 4187 approves the request for registration or rejects it. Rejection may 4188 occur because of significant objections raised on the list or 4189 objections raised externally. 4191 Decisions made by the Reviewer must be posted to the ipp@pwg.org 4192 mailing list within 14 days. Decisions made by the Reviewer may be 4193 appealed to the IESG. 4195 24.7.2.3 IANA Registration 4197 Provided that the Delivery Method registration proposal has either 4198 passed review or has been successfully appealed to the IESG, the IANA 4199 will register the Delivery Method and make it available to the 4200 community. 4202 24.7.3 Delivery Method Document Registrations 4204 Each Push Delivery Method Document defines a URI scheme which is 4205 registered as an additional value of the "notify-schemes-supported" 4206 Printer attribute. These uriScheme values will be registered 4207 according to the procedures of [RFC2911] section 7.1 for additional 4208 attribute values. Therefore, the IPP Registry entry for a Push 4209 Delivery Method will be of the form: 4211 Attribute 4212 Value Ref. Section 4213 --------------------- -------- ------- 4214 notify-schemes-supported (type2 keyword) RFC xxxx 5.3.1.1 4215 RFC xxxx m.n 4217 Each Pull Delivery Method Document defines a keyword method which is 4218 registered as an additional value of the "notify-pull-method" and 4219 "notify-pull-method-supported" Printer attributes. These keyword 4220 values will be registered according to the procedures of [RFC2911] 4221 section 7.1 for additional attribute values. Therefore, the IPP 4222 Registry entry for a Pull Delivery Method will be of the form: 4224 Attribute 4225 Value Ref. Section 4226 --------------------- -------- ------- 4227 notify-pull-method (type2 keyword) [ipp-ntfy] 5.3.2 4228 notify-pull-method-supported (1setOf type2 keyword) 4229 [ipp-ntfy] 5.3.2.1 4230 RFC xxxx m.n 4232 24.7.4 Registration Template 4234 To: ipp@pwg.org 4235 Subject: Registration of a new Delivery Method 4237 Delivery Method name: 4239 (All Push Delivery Method names must be suitable for use as the value 4240 of a URL scheme in the IETF tree and all Pull Delivery Method names 4241 must be suitable IPP keywords according to [RFC2911]) 4243 Published specification(s): 4245 (A specification for the Delivery Method must be openly available 4246 that accurately describes what is being registered.) 4248 Person & email address to contact for further information: 4250 25 Internationalization Considerations 4252 This IPP Notification specification continues support for the 4253 internationalization of [RFC2911] of attributes containing text 4254 strings and names. Allowing a Subscribing Client to specify a 4255 different natural language and charset for each Subscription Object 4256 increases the internationalization support. 4258 The Printer MUST be able to localize the content of Human Consumable 4259 Event Notifications and to localize the value of "notify-text" 4260 attribute in Machine Consumable Event Notifications that it delivers 4261 to Notification Recipients. For localization, the Printer MUST use 4262 the value of the "notify-charset" attribute and the "notify-natural- 4263 language" attribute in the Subscription Object supplied by the 4264 Subscribing Client. 4266 26 Security Considerations 4268 Clients submitting Notification requests to the IPP Printer have the 4269 same security issues as submitting an IPP/1.1 print job request (see 4270 [RFC2911] section 3.2.1 and section 8). The same mechanisms used by 4271 IPP/1.1 can therefore be used by the client Notification submission. 4272 Operations that require authentication can use the HTTP 4273 authentication. Operations that require privacy can use the HTTP/TLS 4274 privacy. As with IPP/1.1 Print Job Objects, if there is no security 4275 on Subscription Objects, sequential assignment of subscription-ids 4276 exposes the system to a passive traffic monitoring threat. 4278 26.1 Client access rights 4280 The Subscription Object access control model is the same as the 4281 access control model for Job objects. The client MUST have the 4282 following access rights for the indicated Subscription operations: 4284 1. Create-Job-Subscriptions (see section 11.1.1): A Per-Job 4285 Subscription object is associated with a Job. To create Per-Job 4286 Subscription Objects, the authenticated user (see [RFC2911] 4287 section 8.3) performing this operation MUST (1) be the job 4288 owner, (2) have Operator or Administrator access rights for this 4289 Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 4290 authorized by the Printer's administrator-configured security 4291 policy to create Per-Job Subscription Objects for the target 4292 job. 4294 2. Create-Printer-Subscriptions (see section 11.1.2): A Per- 4295 Printer Subscription object is associated with the Printer. To 4296 create Per-Printer Subscription Objects, the authenticated user 4297 (see [RFC2911] section 8.3) performing this operation MUST (1) 4298 have Operator or Administrator access rights for this Printer 4299 (see [RFC2911] sections 1 and 8.5) or (2) be otherwise 4300 authorized by the Printer's administrator-configured security 4301 policy to create Per-Printer Subscription Objects for this 4302 Printer. 4304 3. Get-Subscription-Attributes (see section 11.2.4): The access 4305 control model for this operation is the same as that of the Get- 4306 Job-Attributes operation (see [RFC2911] section 3.3.4). The 4307 primary difference is that a Get-Subscription-Attributes 4308 operation is directed at a Subscription Object rather than at a 4309 Job object, and a returned attribute group contains Subscription 4310 Object attributes rather than Job object attributes. To query 4311 the specified Subscription Object, the authenticated user (see 4312 [RFC2911] section 8.3) performing this operation MUST (1) be the 4313 Subscription Object owner, (2) have Operator or Administrator 4314 access rights for this Printer (see [RFC2911] sections 1 and 4315 8.5), or (3) be otherwise authorized by the Printer's 4316 administrator-configured security policy to query the 4317 Subscription Object for the target job. Furthermore, the 4318 Printer's security policy MAY limit which attributes are 4319 returned, in a manner similar to the Get-Job-Attributes 4320 operation (see [RFC2911] end of section 3.3.4.2). 4322 4. Get-Subscriptions (see section 11.2.5): The access control 4323 model for this operation is the same as that of the Get-Jobs 4324 operation (see [RFC2911] section 3.2.6). The primary difference 4325 is that the operation is directed at Subscription Objects rather 4326 than at Job objects, and the returned attribute groups contain 4327 Subscription Object attributes rather than Job object 4328 attributes. To query Per-Job Subscription Objects of the 4329 specified job (client supplied the "notify-job-id" operation 4330 attribute - see section 11.2.5.1.1), the authenticated user (see 4331 [RFC2911] section 8.3) performing this operation MUST (1) be the 4332 Subscription Object owner, (2) have Operator or Administrator 4333 access rights for this Printer (see [RFC2911] sections 1 and 4334 8.5), or (3) be otherwise authorized by the Printer's 4335 administrator-configured security policy to query the 4336 Subscription Object for the target job. To query Per-Printer 4337 Subscription Objects of the Printer (client omits the "notify- 4338 job-id" operation attribute - see section 11.2.5.1.1), the 4339 authenticated user (see [RFC2911] section 8.3) performing this 4340 operation MUST (1) have Operator or Administrator access rights 4341 for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be 4342 otherwise authorized by the Printer's administrator-configured 4343 security policy to query Per-Printer Subscription Objects for 4344 the target Printer. Furthermore, the Printer's security policy 4345 MAY limit which attributes are returned, in a manner similar to 4346 the Get-Job-Attributes operation (see [RFC2911] end of section 4347 3.2.6.2). 4349 5. Renew-Subscriptions (see section 11.2.6): The authenticated 4350 user (see [RFC2911] section 8.3) performing this operation MUST 4351 (1) be the owner of the Per-Printer Subscription Object, (2) 4352 have Operator or Administrator access rights for the Printer 4353 (see [RFC2911] sections 1 and 8.5), or (3) be otherwise 4354 authorized by the Printer's administrator-configured security 4355 policy to renew Per-Printer Subscription Objects for the target 4356 Printer 4358 6. Cancel-Subscription (see section 11.2.7): The authenticated 4359 user (see [RFC2911] section 8.3) performing this operation MUST 4360 (1) be the owner of the Subscription Object, (2) have Operator 4361 or Administrator access rights for the Printer (see [RFC2911] 4362 sections 1 and 8.5), or (3) be otherwise authorized by the 4363 Printer's administrator-configured security policy to cancel the 4364 target Subscription Object. 4366 The standard security concerns (delivery to the right user, privacy 4367 of content, tamper proof content) apply to each Delivery Method. 4368 Some Delivery Methods are more secure than others. Each Delivery 4369 Method Document MUST discuss its Security Considerations. 4371 26.2 Printer security threats 4373 Notification trap door: If a Printer supports the OPTIONAL "notify- 4374 attributes" Subscription Template attribute (see section 5.3.4) where 4375 the client can request that the Printer return any specified Job, 4376 Printer, and Subscription object attributes, the Printer MUST apply 4377 the same security policy to these requested attributes in the Get- 4378 Notifications request as it does for the Get-Jobs, Get-Job- 4379 Attributes, Get-Printer-Attributes, and Get-Subscription-Attributes 4380 requests. 4382 26.3 Notification Recipient security threats 4384 Unwanted Events Notifications (spam): For any Push Delivery Method, 4385 by far the biggest security concern is the abuse of notification: 4386 delivering unwanted Event Notifications to third parties (i.e., 4387 spam). The problem is made worse by notification addresses that may 4388 be redistributed to multiple parties. There exist scenarios where 4389 third party notification is used (see Scenario #2 and #3 in [ipp-not- 4390 req]). Any fully secure solution would require active agreement of 4391 all recipients before delivering anything. 4393 27 Contributors 4395 The following people made significant contributions to the design and 4396 review of this specification: 4398 Scott A. Isaacson 4399 Novell, Inc. 4400 122 E 1700 S 4401 Provo, UT 84606 4403 Phone: 801-861-7366 4404 Fax: 801-861-2517 4405 e-mail: sisaacson@novell.com 4407 Roger deBry 4408 Utah Valley State College 4409 Orem, UT 84058 4411 Phone: (801) 222-8000 4412 EMail: debryro@uvsc.edu 4414 Jay Martin 4415 Underscore Inc. 4416 9 Jacqueline St. 4417 Hudson, NH 03051-5308 4418 603-889-7000 4419 fax: 775-414-0245 4420 e-mail: jkm@underscore.com 4422 Michael Shepherd 4423 Xerox Corporation 4424 800 Phillips Road MS 128-51E 4425 Webster, NY 14450 4427 Phone: 716-422-2338 4428 Fax: 716-265-8871 4429 e-mail: mshepherd@usa.xerox.com 4431 Ron Bergman 4432 Hitachi Koki Imaging Solutions 4433 1757 Tapo Canyon Road 4434 Simi Valley, CA 93063-3394 4436 Phone: 805-578-4421 4437 Fax: 805-578-4001 4438 Email: rbergma@hitachi-hkis.com 4440 28 Author's Addresses 4442 Robert Herriot 4443 706 Colorado Ave. 4444 Palo Alto, CA 94303 4446 Phone: 650-327-4466 4447 Fax: 650-327-4466 4448 Email: bob@herriot.com 4449 Tom Hastings 4450 Xerox Corporation 4451 737 Hawaii St. ESAE 231 4452 El Segundo, CA 90245 4454 Phone: 310-333-6413 4455 Fax: 310-333-5514 4456 e-mail: hastings@cp10.es.xerox.com 4458 IPP Web Page: http://www.pwg.org/ipp/ 4459 IPP Mailing List: ipp@pwg.org 4461 To subscribe to the ipp mailing list, send the following email: 4462 1) send it to majordomo@pwg.org 4463 2) leave the subject line blank 4464 3) put the following two lines in the message body: 4465 subscribe ipp 4466 end 4468 Implementers of this specification document are encouraged to join 4469 the IPP Mailing List in order to participate in any discussions of 4470 clarification issues and review of registration proposals for 4471 additional attributes and values. In order to reduce spam the 4472 mailing list rejects mail from non-subscribers, so you must subscribe 4473 to the mailing list in order to send a question or comment to the 4474 mailing list. 4476 29 Appendix G - Description of the base IPP documents (Informative) 4478 The base set of IPP documents includes: 4480 Design Goals for an Internet Printing Protocol [RFC2567] 4481 Rationale for the Structure and Model and Protocol for the Internet 4482 Printing Protocol [RFC2568] 4483 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 4484 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 4485 Internet Printing Protocol/1.1: Implementer's Guide [RFC3196] 4486 Mapping between LPD and IPP Protocols [RFC2569] 4488 The "Design Goals for an Internet Printing Protocol" document takes a 4489 broad look at distributed printing functionality, and it enumerates 4490 real-life scenarios that help to clarify the features that need to be 4491 included in a printing protocol for the Internet. It identifies 4492 requirements for three types of users: end users, operators, and 4493 administrators. It calls out a subset of end user requirements that 4494 are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator 4495 operations have been added to IPP/1.1 [RFC2911, RFC2910]. 4497 The "Rationale for the Structure and Model and Protocol for the 4498 Internet Printing Protocol" document describes IPP from a high level 4499 view, defines a roadmap for the various documents that form the suite 4500 of IPP specification documents, and gives background and rationale 4501 for the IETF IPP working group's major decisions. 4503 The "Internet Printing Protocol/1.1: Model and Semantics" document 4504 describes a simplified model with abstract objects, their attributes, 4505 and their operations. The model introduces a Printer and a Job. The 4506 Job supports multiple documents per Job. The model document also 4507 addresses how security, internationalization, and directory issues 4508 are addressed. 4510 The "Internet Printing Protocol/1.1: Encoding and Transport" document 4511 is a formal mapping of the abstract operations and attributes defined 4512 in the model document onto HTTP/1.1 [RFC2616]. It also defines the 4513 encoding rules for a new Internet MIME media type called 4514 "application/ipp". This document also defines the rules for 4515 transporting over HTTP a message body whose Content-Type is 4516 "application/ipp". This document defines the 'ipp' scheme for 4517 identifying IPP printers and jobs. 4519 The "Internet Printing Protocol/1.1: Implementer's Guide" document 4520 gives insight and advice to implementers of IPP clients and IPP 4521 objects. It is intended to help them understand IPP/1.1 and some of 4522 the considerations that may assist them in the design of their client 4523 and/or IPP object implementations. For example, a typical order of 4524 processing requests is given, including error checking. Motivation 4525 for some of the specification decisions is also included. 4527 The "Mapping between LPD and IPP Protocols" document gives some 4528 advice to implementers of gateways between IPP and LPD (Line Printer 4529 Daemon) implementations. 4531 30 Appendix H - Full Copyright Statement (Informative) 4533 Copyright (C) The Internet Society (1998,1999,2000,2001,2002). All 4534 Rights Reserved 4536 This document and translations of it may be copied and furnished to 4537 others, and derivative works that comment on or otherwise explain it 4538 or assist in its implementation may be prepared, copied, published 4539 and distributed, in whole or in part, without restriction of any 4540 kind, provided that the above copyright notice and this paragraph are 4541 included on all such copies and derivative works. However, this 4542 document itself may not be modified in any way, such as by removing 4543 the copyright notice or references to the Internet Society or other 4544 Internet organizations, except as needed for the purpose of 4545 developing Internet standards in which case the procedures for 4546 copyrights defined in the Internet Standards process must be 4547 followed, or as required to translate it into languages other than 4548 English. 4550 The limited permissions granted above are perpetual and will not be 4551 revoked by the Internet Society or its successors or assigns. 4553 This document and the information contained herein is provided on an 4554 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4555 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4556 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4557 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4558 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4560 Acknowledgement 4562 Funding for the RFC Editor function is currently provided by the 4563 Internet Society.