idnits 2.17.1 draft-ietf-ipp-notify-get-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories -- however, there's a paragraph with a matching beginning. Boilerplate error? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == The 'Updates: ' line in the draft header should list only the _numbers_ of the RFCs which will be updated by this document (if approved); it should not include the word 'RFC' in the list. -- The draft header indicates that this document updates RFC2911, but the abstract doesn't seem to directly say this. It does mention RFC2911 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 313 has weird spacing: '...ll), or a p...' == Line 1585 has weird spacing: '...for the purpo...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Unrecognized Status in '[Target category: standards track]', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) (Using the creation date from RFC2911, updated by this document, for RFC5378 checks: 1999-02-22) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 27, 2002) is 7971 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) == Unused Reference: 'RFC2565' is defined on line 1224, but no explicit reference was found in the text == Unused Reference: 'RFC2566' is defined on line 1229, but no explicit reference was found in the text == Unused Reference: 'RFC3196' is defined on line 1255, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2910 (Obsoleted by RFC 8010) ** Obsolete normative reference: RFC 2911 (Obsoleted by RFC 8011) -- 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: 5 errors (**), 0 flaws (~~), 10 warnings (==), 6 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 2911 Xerox Corp. 6 [Target category: standards track] June 27, 2002 7 Expires: December 27, 2002 9 Internet Printing Protocol (IPP): 10 The 'ippget' Delivery Method for Event Notifications 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 30 The list of Internet-Draft Shadow Directories can be accessed as 31 http://www.ietf.org/shadow.html. 33 Abstract 35 This document describes an extension to the Internet Printing 36 Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). This 37 document specifies the 'ippget' Delivery Method for use with the 38 "Internet Printing Protocol (IPP): Event Notifications and 39 Subscriptions" specification. When IPP Notification [ipp-ntfy] is 40 supported, the Delivery Method defined in this document is the 41 REQUIRED Delivery Method for clients and Printers to support. They 42 MAY support additional Delivery Methods. 44 The 'ippget' Delivery Method is a Pull Delivery Method. When an 45 Event occurs, the Printer saves the Event Notification for a period 46 of time called the Event Life. The Notification Recipient fetches 47 (pulls) Event Notifications using the Get-Notifications operation. 48 If the Notification Recipient has selected the Event Wait Mode option 49 to wait for additional Event Notifications, the Printer continues to 50 return Event Notifications to the Notification Recipient as Get- 51 Notification responses as Events occur using the connection 52 originated by the Notification Recipient. 54 Either the Notification Recipient or the Printer can terminate Event 55 Wait Mode without closing the connection. 57 Table of Contents 59 1 Introduction.....................................................5 61 2 Terminology......................................................6 63 3 Model and Operation..............................................7 65 4 General Information..............................................8 67 5 Get-Notifications operation......................................9 68 5.1 Get-Notifications Request.....................................11 69 5.1.1 notify-subscription-ids (1setOf integer(1:MAX)).............11 70 5.1.2 notify-sequence-numbers (1setOf integer(1:MAX)).............11 71 5.1.3 notify-wait (boolean).......................................12 72 5.2 Get-Notifications Response....................................13 73 5.2.1 notify-get-interval (integer(0:MAX))........................16 74 5.2.2 printer-up-time (integer(1:MAX))............................18 75 5.2.3 redirect-uri (uri)..........................................18 77 6 Additional Information about Subscription Template Attributes...22 78 6.1 notify-pull-method (type2 keyword)............................22 80 7 Subscription Description Attributes.............................22 82 8 Additional Printer Description Attributes.......................23 83 8.1 ippget-event-life (integer(15:MAX))...........................23 85 9 New Values for Existing Printer Description Attributes..........24 86 9.1 notify-pull-method-supported (1setOf type2 keyword)...........24 87 9.2 operations-supported (1setOf type2 enum)......................24 89 10 New Status Codes...............................................24 90 10.1 successful-ok-events-complete (0x0007).......................25 91 10.2 redirection-other-site (0x0300)..............................25 93 11 Encoding and Transport.........................................25 95 12 Conformance Requirements.......................................27 96 12.1 Conformance for IPP Printers.................................27 97 12.2 Conformance for IPP Clients..................................28 99 13 Normative References...........................................28 101 14 Informative References.........................................29 103 15 Security Considerations........................................30 104 15.1 Notification Recipient client access rights..................30 105 15.2 Printer security threats.....................................31 106 15.3 Notification Recipient security threats......................31 107 15.4 Security requirements for Printers...........................31 108 15.5 Security requirements for clients............................32 110 16 Internationalization Considerations............................32 112 17 IANA Considerations............................................32 113 17.1 Additional attribute value registrations for existing attributes 114 32 115 17.1.1 Additional values for the "notify-pull-method-supported" 116 Printer attribute......................................32 117 17.1.2 Additional values for the "operations-supported" Printer 118 attribute..............................................33 119 17.2 Operation Registrations......................................33 120 17.3 Attribute Registrations......................................33 121 17.4 Status code Registrations....................................34 123 18 Contributors...................................................34 125 19 Authors' Addresses.............................................35 127 20 Description of Base IPP documents..............................35 129 21 Full Copyright Statement.......................................37 131 Table of Tables 133 Table 1 - Information about the Delivery Method....................8 134 Table 2 - Combinations of "notify-wait", "status-code", and "notify- 135 get-interval" .................................................17 136 Table 3 - Attributes in Event Notification Content................20 137 Table 4 - Additional Attributes in Event Notification Content for Job 138 Events ........................................................21 139 Table 5 - Combinations of Events and Subscribed Events for "job- 140 impressions-completed" ........................................21 141 Table 6 - Additional Attributes in Event Notification Content for 142 Printer Events ................................................22 143 Table 7 - Operation-id assignments................................24 144 Table 8 - The "event-notification-attributes-tag" value...........27 146 1 Introduction 148 The "IPP Event Notifications and Subscriptions" document [ipp-ntfy] 149 defines an OPTIONAL extension to Internet Printing Protocol/1.1: 150 Model and Semantics [RFC2911, RFC2910]. For a description of the 151 base IPP documents, see section 20. The [ipp-ntfy] extension defines 152 operations that a client can perform in order to create Subscription 153 Objects in a Printer and carry out other operations on them. A 154 Subscription Object represents a Subscription abstraction. A client 155 associates Subscription Objects with a particular Job by performing 156 the Create-Job-Subscriptions operation or by submitting a Job with 157 subscription information. A client associates Subscription Objects 158 with the Printer by performing a Create-Printer-Subscriptions 159 operation. Four other operations are defined for Subscription 160 Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- 161 Subscription, and Cancel-Subscription. The Subscription Object 162 specifies that when one of the specified Events occurs, the Printer 163 sends an asynchronous Event Notification to the specified 164 Notification Recipient via the specified Delivery Method (i.e., 165 protocol). 167 The "IPP Event Notifications and Subscriptions" document [ipp-ntfy] 168 specifies that each Delivery Method is defined in another document. 169 This document is one such document, and it specifies the 'ippget' 170 delivery method. If a client or Printer supports IPP Notification 171 [ipp-ntfy], the client or Printer MUST support the 'ippget' Delivery 172 Method defined in this document. Such a client or Printer MAY 173 support additional Delivery Methods. 175 The 'ippget' Delivery Method is a Pull Delivery Method. When an 176 Event occurs, the Printer saves the Event Notification for a period 177 of time called the Event Life. The Notification Recipient fetches 178 (pulls) the Event Notifications using the Get-Notifications 179 operation. This operation causes the Printer to return all Event 180 Notifications held for the specified Subscription object(s). If the 181 Notification Recipient has selected the Event Wait Mode option to 182 wait for additional Event Notifications, the Printer continues to 183 return Event Notifications to the Notification Recipient as Get- 184 Notification responses as Events occur using the transaction 185 originated by the Notification Recipient. 187 The Notification Recipient can terminate Event Wait Mode (without 188 closing the connection) by supplying the "notify-wait" (boolean) 189 attribute with a 'false' value in a subsequent Get-Notifications 190 request. Similarly, the Printer can terminate Event Wait Mode 191 (without closing the connection) by returning the "notify-get- 192 interval" (integer) operation attribute in a Get-Notifications 193 response which tells the Notification Recipient how long to wait 194 before trying again. 196 2 Terminology 198 This section defines the following terms that are used throughout 199 this document: 201 This document uses the same terminology as [RFC2911], such as 202 "client", "Printer", "Job", "attribute", "attribute value", 203 "keyword", "operation", "request", "response", and "support". 205 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 206 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 207 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 208 12.1. If an implementation supports the extension defined in this 209 document, then these terms apply; otherwise, they do not. These 210 terms define conformance to this document only; they do not affect 211 conformance to other documents, unless explicitly stated otherwise. 213 Event Life: The length of time in seconds after an Event occurs 214 during which the Printer will return that Event in a Event 215 Notification in a Get-Notifications response. After the Event 216 Life expires, the Printer will no longer return an Event 217 Notification for that Event in a Get-Notifications response. 219 Event Notification Attributes Group: The attributes group in a 220 response that contains attributes that are part of an Event 221 Notification. 223 Event Wait Mode: The mode requested by a Notification Recipient 224 client in its Get-Notifications Request and granted by a Printer 225 to keep the connection open where the Printer sends subsequent 226 Event Notifications to the Notification Recipient as they occur 227 as additional Get-Notification Responses. 229 Other capitalized terms, such as Notification Recipient, Event, Event 230 Notification, Compound Event Notification, Printer, etc., are 231 defined in [ipp-ntfy], have the same meanings, and are not 232 reproduced here. However, for convenience the following key 233 terms are reproduced here: 235 Event - some occurrence (either expected or unexpected) within the 236 printing system of a change of state, condition, or 237 configuration of a Job or Printer object. An Event occurs only 238 at one instant in time and does not span the time the physical 239 Event takes place. For example, jam-occurred and jam-cleared 240 are two distinct, instantaneous Events, even though the jam may 241 last for a while. 243 Event Notification - the information about an Event that the Printer 244 sends when an Event occurs. 246 3 Model and Operation 248 In a Subscription Creation Operation, when the "notify-pull-method" 249 attribute is present and has the 'ippget' keyword value, the client 250 is requesting that the Printer use the 'ippget' Pull Delivery Method 251 for the Event Notifications associated with the new Subscription 252 Object. 254 When an Event occurs, the Printer MUST generate an Event Notification 255 and MUST assign it the Event Life. The Printer MUST hold an Event 256 Notification for its assigned Event Life. 258 When a Notification Recipient wants to receive Event Notifications 259 for a Subscription object, it performs the Get-Notifications 260 operation supplying the Subscription object's subscription-id, which 261 causes the Printer to return all un-expired Event Notifications held 262 for that Subscription object. If the Notification Recipient has 263 selected the Event Wait Mode option to wait for additional Event 264 Notifications, the response to the Get-Notifications request 265 continues indefinitely as the Printer continues to send Event 266 Notifications in the response as Events occur for that Subscription 267 object. 269 When the Notification Recipient requests Event Notifications for per- 270 Job Subscription Objects, the Notification Recipient typically 271 performs the Get-Notifications operation within a second of 272 performing the Subscription Creation operation. Because the Printer 273 MUST save Event Notifications for at least 15 seconds (see section 274 8.1), the Notification Recipient is unlikely to miss any Event 275 Notifications that occur between the Subscription Creation and the 276 Get-Notifications operation. 278 The 'ippget' Delivery Method is designed primarily for (1) a client 279 that wants to get Events (from the job's per-Job Subscription object) 280 for a job that it has submitted and (2) for a privileged client that 281 wants to get all job or printer Events from a per-Printer 282 Subscription object. 284 4 General Information 286 If a Printer supports this Delivery Method, the following are its 287 characteristics. 289 Table 1 - Information about the Delivery Method 291 Document Method Conformance Requirement Delivery Method 292 Realization 294 1. What is the URL scheme name for the 295 Push Delivery Method or the keyword name 296 method name for the Pull Delivery 297 Method? 'ippget' keyword method 299 2. Is the Delivery Method REQUIRED, REQUIRED 300 RECOMMENDED or OPTIONAL for an IPP 301 Printer to support? 303 3. What transport and delivery protocols IPP with one new 304 does the Printer use to deliver the operation. 305 Event Notification Content, i.e., what 306 is the entire network stack? 308 4. Can several Event Notifications be 309 combined into a Compound Event 310 Notification? Yes. 312 5. Is the Delivery Method initiated by This Delivery Method is 313 the Notification Recipient (pull), or a pull method with 314 by the Printer (push)? aspects of a push 315 method, though the 316 Printer does not 317 initiate the connection. 319 6. Is the Event Notification content Machine Consumable 320 Machine Consumable or Human 321 Consumable? 323 7. What section in this document answers Section 5 324 the following question? For a Machine 325 Consumable Event Notification, what is 326 the representation and encoding of 327 values defined in section 9.1 of [ipp- 328 ntfy] and the conformance requirements 329 thereof? For a Human Consumable Event 330 thereof? For a Human Consumable Event 331 Notification, what is the 332 representation and encoding of pieces 333 of information defined in section 9.2 334 of [ipp-ntfy] and the conformance 335 requirements thereof? 337 8. What are the latency and reliability Same as IPP and the 338 of the transport and delivery underlying HTTP 339 protocol? transport 341 9. What are the security aspects of the 342 transport and delivery protocol, e.g., underlying HTTP 343 how it is handled in firewalls? transportPandnintthe 344 same direction, so no 345 new firewall 346 considerations. 348 10.What are the content length None 349 restrictions? 351 11.What are the additional values or 352 pieces of information that a Printer 353 sends in an Event Notification content 354 and the conformance requirements 355 thereof? None 357 12.What are the additional Subscription None 358 Template and/or Subscription 359 Description attributes and the 360 conformance requirements thereof? 362 13.What are the additional Printer "ipp-event-life" 363 Description attributes and the (integer (15: MAX)) 364 conformance requirements thereof? 366 5 Get-Notifications operation 368 This operation is issued by a client acting in the role of a 369 Notification Recipient requesting the Printer to return all Event 370 Notifications held for the identified Subscription object(s). 372 A Printer MUST support this operation. 374 When a Printer performs this operation, it MUST return all and only 375 those Event Notifications: 377 1. Whose associated Subscription Object's "notify-subscription-id" 378 Subscription Description attribute equals one of the values of 379 the "notify-subscription-ids" (1setOf integer(1:MAX)) operation 380 attribute AND 382 2. Whose associated Subscription Object's contains the "notify- 383 pull-method" attribute and it has the 'ippget' keyword value AND 385 3. Whose "notify-sequence-number" is equal to or greater than the 386 corresponding value of the "notify-sequence-numbers (1setOf 387 integer(1:MAX)) operation attribute, if supplied AND 389 4. Whose Event Life has not yet expired AND 391 5. Where the Notification Recipient client has read-access rights 392 to the identified Subscription Object (see Access Rights 393 paragraph below). 395 The Notification Recipient client can request Event Wait Mode by 396 supplying the "notify-wait" operation attribute with a 'true' value. 398 The Notification Recipient client can terminate Event Wait Mode 399 (without closing the connection) by supplying the "notify-wait" 400 attribute with a 'false' value in a subsequent Get-Notifications 401 request. Similarly, the Printer can terminate Event Wait Mode 402 (without closing the connection) by returning the "notify-get- 403 interval" operation attribute in a Get-Notifications response which 404 tells the Notification Recipient how long to wait before trying 405 again. 407 The Printer MUST accept the request in any state (see [RFC2911] 408 "printer-state" and "printer-state-reasons" attributes) and MUST 409 remain in the same state with the same "printer-state-reasons" 410 values. 412 Access Rights: The authenticated user (see [RFC2911] section 8.3) 413 performing this operation MUST be (1) the owner of each Subscription 414 Object identified by the "notify-subscription-ids" operation 415 attribute (see section 5.1.1), (2) an operator or administrator of 416 the Printer (see [RFC2911] Sections 1 and 8.5), or (3) be otherwise 417 authorized by the Printer's administrator-configured security policy 418 to request Event Notifications from the target Subscription 419 Object(s). Otherwise, the IPP Printer MUST reject the operation and 420 return: 'client-error-forbidden', 'client-error-not-authenticated', 421 or 'client-error-not-authorized' status code as appropriate. 422 Furthermore, the Printer's security policy MAY limit the attributes 423 returned by the Get-Notifications operation, in a manner similar to 424 the Get-Job-Attributes operation (see [RFC2911] end of section 425 3.3.4.2). 427 5.1 Get-Notifications Request 429 The following groups of attributes are part of the Get-Notifications 430 Request: 432 Group 1: Operation Attributes 434 Natural Language and Character Set: 435 The "attributes-charset" and "attributes-natural-language" 436 attributes as described in [RFC2911] section 3.1.4.1. 438 Target: 439 The "printer-uri" (uri) operation attribute which is the target 440 for this operation as described in [RFC2911] section 3.1.5. 442 Requesting User Name: 443 The "requesting-user-name" (name(MAX)) attribute SHOULD be 444 supplied by the client as described in [RFC2911] section 8.3. 446 5.1.1 notify-subscription-ids (1setOf integer(1:MAX)) 448 This attribute identifies one or more Subscription objects for 449 which Events are requested. The client MUST supply this 450 attribute with at least one value. The Printer object MUST 451 support this attribute with multiple values. 453 If no Subscription Object exists with the supplied identifier 454 or the identified Subscription Object does not contain the 455 "notify-pull-method" attribute with the 'ippget' keyword value, 456 the Printer MUST return the 'client-error-not-found' status 457 code. 459 Note: The name of both the "notify-subscription-ids" and 460 "notify-sequence-numbers" end in 's', since they are 461 multi-valued. However, there are other occurrences of 462 these attribute names without the 's' that are single 463 valued. 465 5.1.2 notify-sequence-numbers (1setOf integer(1:MAX)) 467 This attribute specifies one or more lowest Event Notification 468 sequence number values for the Subscription objects identified 469 by the corresponding values of the "notify-subscription-ids" 470 operation attribute. The Notification Recipient SHOULD supply 471 this attribute and the number of values SHOULD be the same as 472 the number of values of the "notify-subscriptions-ids" 473 attribute. The Printer MUST support this attribute with 474 multiple values. 476 The Printer MUST NOT return Notification Events with lower 477 sequence numbers for the corresponding Subscription object. 478 Therefore, by supplying the proper values for this attribute 479 the Notification Recipient can prevent getting the same Event 480 Notifications from a Subscription object that were returned on 481 a previous Get-Notifications request. The Notification 482 Recipient SHOULD remember the highest "notify-sequence-number" 483 value returned for each Subscription object requested and 484 SHOULD pass that value for each requested Subscription object 485 on the next Get-Notifications request. 487 If the Notification Recipient supplies fewer values for this 488 attribute (including omitting this attribute) than for the 489 "notify-subscription-ids" operation attribute, the Printer 490 assumes a '1' value for each missing value. A value of '1' 491 causes the Printer to return any un-expired Event Notification 492 for that Subscription object, since '1' is the lowest possible 493 sequence number. If the Notification Recipient supplies more 494 values for this attribute than the number of values for the 495 "notify-subscription-ids" operation attribute, the Printer 496 ignores the extra values. 498 Note: If a Notification Recipient performs two consecutive Get- 499 Notifications operations with the same value for "notify- 500 sequence-number" (or omits the attribute), the time stamp of 501 the first Event Notification in the second Get-Notifications 502 Response may be less than the time stamp of the last Event 503 Notification in the first Get-Notification Response. This 504 happens because the Printer sends all unexpired Event 505 Notification with a sequence number equal or higher according 506 to the ordering specified in [ipp-ntfy] and some Event 507 Notifications from the first Get-Notifications operation may 508 not have expired by the time the second Get-Notifications 509 operation occurs. 511 5.1.3 notify-wait (boolean) 513 This value indicates whether or not the Notification Recipient 514 wants Event Wait Mode. The client MAY supply this attribute. 515 The Printer object MUST support both values of this attribute. 517 If the client supplies the 'false' value or omits this 518 attribute, the client is not requesting Event Wait Mode. If 519 the value is 'true', the client is requesting Event Wait Mode. 520 See the beginning of section 5.2 for the rules for Event Wait 521 Mode. 523 5.2 Get-Notifications Response 525 The Printer has the following options for responding to a Get- 526 Notifications Request: 528 1. The Printer can reject the request and return the 'server-error- 529 busy' status code, if the Printer is too busy to accept this 530 operation at this time. In this case, the Printer MUST return 531 the "get-notify-interval" operation attribute to indicate when 532 the client SHOULD try again. 534 2. If the Notification Recipient did not request Event Wait Mode 535 ("notify-wait-mode" = 'false' or omitted), the Printer MUST 536 return immediately whatever Event Notifications it currently 537 holds in the requested Subscription object(s) and MUST return 538 the "notify-get-interval" operation attribute with number of 539 seconds from now at which the Notification Recipient SHOULD 540 repeat the Get-Notifications Request to get future Event 541 Notifications. 543 3. If the Notification Recipient requested Event Wait Mode 544 ("notify-wait-mode" = 'true'), the Printer MUST return 545 immediately whatever Event Notifications it currently holds in 546 the requested Subscription object(s) and MUST continue to return 547 Event Notifications as they occur until all of the requested 548 Subscription Objects are canceled. A Subscription Object is 549 canceled either via the Cancel-Subscription operation or by the 550 Printer (e.g., the Subscription Object is canceled when the 551 associated Job completes and is no longer in the Job Retention 552 or Job History phase - see the "ippget-event-life 553 (integer(15:MAX))" attribute discussion in section 8.1). 555 However, the Printer MAY decide to terminate Event Wait Mode at 556 any time, including in the first response. In this case the 557 Printer MUST return the "notify-get-interval" operation 558 attribute. This attribute indicates that the Printer wishes to 559 leave Event Wait Mode and the number of seconds in the future 560 that the Notification Recipient SHOULD try the Get-Notifications 561 operation again. The Notification Recipient MUST accept this 562 response and MUST disconnect. If the Notification Recipient 563 does not disconnect, the Printer SHOULD do so. 565 From the Notification Recipient's view, the response appears as an 566 initial burst of data, which includes the Operation Attributes Group 567 and one Event Notification Attributes Group per Event Notification 568 that the Printer is holding. After the initial burst of data, if the 569 Notification Recipient has selected the Event Wait Mode option to 570 wait for additional Event Notifications, the Notification Recipient 571 receives occasional Event Notification Attribute Groups. Proxy 572 servers may delay some Event Notifications or cause time-outs to 573 occur. The client MUST be prepared to perform the Get-Notifications 574 operation again when time-outs occur. 576 Each attribute is encoded using the IPP rules for encoding attributes 577 [RFC2910] and MAY be encoded in any order. Note: the Get-Jobs 578 response in [RFC2911] acts as a model for encoding multiple groups of 579 attributes. See section 11 for the encoding and transport rules. 581 The following groups of attributes are part of the Get-Notifications 582 Response: 584 Group 1: Operation Attributes 586 Status Message: 587 In addition to the REQUIRED status code returned in every 588 response, the response OPTIONALLY includes a "status-message" 589 (text(255)) and/or a "detailed-status-message" (text(MAX)) 590 operation attribute as described in [RFC2911] sections 13 and 591 3.1.6. 593 The Printer can return any status codes defined in [RFC2911]. 594 If the status code is not 'successful-xxx', the Printer MUST 595 NOT return any Event Notification Attribute groups. The 596 following is a description of the important status codes: 598 successful-ok: the response contains all Event Notification 599 associated with the specified subscription-ids that had 600 been supplied in the "notify-subscription-ids" operation 601 attribute in the request. If the requested Subscription 602 Objects have no associated Event Notification, the 603 response MUST contain zero Event Notifications. 604 successful-ok-events-complete: indicate when this return 605 is the last return for all Subscription objects that 606 match the request, whether or not there are Event 607 Notifications being returned. This condition occurs for 608 Event Wait Mode with Notification Recipients waiting for 609 responses when the Subscription Object is: (1) canceled 610 with a Cancel-Subscription operation, (2) deleted when 611 the Per-Printer Subscription lease time expires, or (3) 612 when the 'job-completed' event occurs for a Per-Job 613 Subscription. This condition also occurs for a Get- 614 Notifications request that a Notification Recipient makes 615 after the job completes, but before the Event Life 616 expires. See section 10.1. 617 client-error-not-found: The Printer has no Subscription 618 Object's whose "notify-subscription-id" attribute equals 619 any of the values of the "notify-subscription-ids" 620 operation attribute supplied or the identified 621 Subscription Object does not contain the "notify-pull- 622 method" attribute with the 'ippget' keyword value. 623 server-error-busy: The Printer is too busy to accept this 624 operation. The Printer SHOULD return the "notify-get- 625 interval" operation attribute in the Operation Attributes 626 of the response, then the Notification Recipient SHOULD 627 wait for the number of seconds specified by the "notify- 628 get-interval" operation attribute before performing this 629 operation again. If the "notify-get-interval" Operation 630 Attribute is not present, the Notification Recipient 631 SHOULD use the normal network back-off algorithms for 632 determining when to perform this operation again. 633 redirection-other-site: The Printer does not handle this 634 operation and requests the Notification Recipient to 635 perform the operation again with the uri specified by the 636 "redirect-uri" Operation Attribute in the response. See 637 section 10.2. 639 Natural Language and Character Set: 640 The "attributes-charset" and "attributes-natural-language" 641 attributes as described in [RFC2911] section 3.1.4.2. 643 The Printer MUST use the values of "notify-charset" and 644 "notify-natural-language", respectively, from one Subscription 645 Object associated with the Event Notifications in this 646 response. 648 Normally, there is only one matched Subscription Object, or the 649 value of the "notify-charset" and "notify-natural-language" 650 attributes is the same in all Subscription Objects. If not, 651 the Printer MUST pick one Subscription Object from which to 652 obtain the value of these attributes. The algorithm for 653 picking the Subscription Object is implementation dependent. 654 The choice of natural language is not critical because 'text' 655 and 'name' values can override the "attributes-natural- 656 language" operation attribute. The Printer's choice of charset 657 is critical because a bad choice may leave it unable to send 658 some 'text' and 'name' values accurately. 660 5.2.1 notify-get-interval (integer(0:MAX)) 662 The value of this operation attribute is the number of seconds 663 that the Notification Recipient SHOULD wait before trying the 664 Get-Notifications operation again. The Printer MUST return 665 this operation attribute if: (1) it is too busy to return 666 events, (2) the Notification Recipient client did not request 667 Event Wait Mode, or (3) the Printer is terminating Event Wait 668 Mode. The client MUST accept this attribute and SHOULD re- 669 issue the Get-Notifications operation (with or without "notify- 670 wait" = 'true') the indicated number of seconds in the future 671 in order to get more Event Notifications This value is 672 intended to help the client be a good network citizen. 674 The value of this attribute MUST be at least as large as the 675 value of the Printer's "ippget-event-life" Printer Description 676 attribute (see section 8.1). The Printer MAY return a value 677 that is larger than the value of the "ippget-event-life" 678 Printer Description attribute provided that the Printer 679 increases the Event Life for this Subscription object, so that 680 Notification Recipients taking account of the larger value and 681 polling with a longer interval will not miss events. Note; 682 implementing such an algorithm requires some hidden attributes 683 in the Subscription object that are IMPLEMENTATION DEPENDENT. 685 If the Printer wants to remain in Event Wait Mode, then the 686 Printer MUST NOT return this attribute in the response. 688 Here is a complete table of combinations of "notify-wait", 689 "status-code", "notify-get-interval", and Event Notification 690 Attributes Groups for Get-Notification initial (Wait and No 691 Wait) Responses and subsequent Event Wait Mode Responses (which 692 may be staying in Event Wait Mode or may be requesting the 693 Notification Recipient to leave Event Wait Mode): 695 Table 2 - Combinations of "notify-wait", "status-code", and "notify- 696 get-interval" 698 client sends: Printer returns: Printer Event 699 returns: Notification 700 "notify-wait" "status-code" "notify-get- Attribute 701 interval" Groups 703 1. 'false'* 'successful-ok' MUST return N maybe 705 2. 'false'* 'not-found' MUST NOT MUST NOT 707 3. 'false'* 'busy' MUST return N MUST NOT 709 4. 'false'* 'events- MUST NOT 'job- 710 complete' completed' 712 5. 'true' 'successful-ok' MUST NOT MUST 714 6. 'true' 'successful-ok' MUST return N maybe 716 7. 'true' 'not-found' MUST NOT MUST NOT 718 8. 'true' 'busy' MUST return N MUST NOT 720 9. 'true' 'events- MUST NOT 'job- 721 complete' completed' or 722 maybe other 724 * 'false' or client omits the "notify-wait" attribute. 726 Explanation: 728 1-4: client does not request Event Wait Mode 729 5-9: client requests Event Wait Mode 730 2,7: Subscription object not found, or was canceled earlier; 731 client should NOT try again. 732 3,8: server busy, tells client to try later; client should try 733 again in N seconds. 734 4: client polled after job completed, but before Event Life 735 expired, and got the 'job-completed' event, so the client 736 shouldn't bother trying again; client should NOT try again 737 later. 738 5: Printer returns one or more Event Notifications and is OK 739 to stay in Event Wait Mode; the client waits for more Event 740 Notifications to be returned. 742 6: Printer wants to leave Event Wait mode. Can happen on the 743 first response (with or without Event Notifications) or happen 744 on a subsequent response with or without Event Notifications; 745 the client SHOULD try again in N seconds. 746 9: Printer either (1) returns 'job-completed' event or (2) the 747 Subscription Object was canceled by either a Cancel-Job or a 748 Per-Printer Subscription expired without being renewed. For 749 case (1), at least one Event Notification MUST be returned, 750 while for case (2), it is unlikely that any Event Notifications 751 are returned; the client should NOT try again. 753 5.2.2 printer-up-time (integer(1:MAX)) 755 The value of this attribute is the Printer's "printer-up-time" 756 attribute at the time the Printer sends this response. The 757 Printer MUST return this attribute. Because each Event 758 Notification also contains the value of this attribute when the 759 event occurred, the value of this attribute lets a Notification 760 Recipient know when each Event Notification occurred relative 761 to the time of this response. 763 5.2.3 redirect-uri (uri) 765 The value of this attribute is the uri that the Notification 766 Recipient MUST use for a subsequent Get-Notifications 767 operation. The Printer MAY support this attribute. This 768 attribute MUST be returned in the Operation Attributes Group if 769 and only if the Printer returns the 'redirection-other-site' 770 status code (see section 10.2). 772 Group 2: Unsupported Attributes 774 See [RFC2911] section 3.1.7 for details on returning 775 Unsupported Attributes. 777 Group 3 through N: Event Notification Attributes 779 The Printer responds with one Event Notification Attributes 780 Group per matched Event Notification. The entire response is 781 considered a single Compound Event Notification (see [ipp- 782 ntfy]). The matched Event Notifications are all un-expired 783 Event Notification associated with the matched Subscription 784 Objects and MUST follow the "Event Notification Ordering" 785 requirements for Event Notifications within a Compound Event 786 Notification specified in [ipp-ntfy] section 9. In other 787 words, the Printer MUST order these Event Notification groups 788 in ascending time stamp (and sequence number) order for a 789 Subscription object. If Event Notifications for multiple 790 Subscription objects are being returned, the Notification 791 Events for the next Subscription object follow in ascending 792 time stamp order, etc. 794 Each Event Notification Group MUST contain all of attributes 795 specified in section 9.1 ("Content of Machine Consumable Event 796 Notifications") of [ipp-ntfy] with exceptions denoted by 797 asterisks in the tables below. 799 The tables below are copies of the tables in section 9.1 800 ("Content of Machine Consumable Event Notifications") of [ipp- 801 ntfy] except that each cell in the "Sends" column is a "MUST". 803 If more than one Event Notification is being returned and the 804 status of each is not the same, then the Printer MUST return a 805 "notify-status-code" attribute in each Event Notification 806 Attributes group to indicate the differing status values. 808 For an Event Notification for all Events, the Printer includes 809 the attributes shown in Table 3. 811 Table 3 - Attributes in Event Notification Content 813 Source Value Sends Source 814 Object 816 notify-subscription-id (integer(1:MAX)) MUST Subscription 818 notify-printer-uri (uri) MUST Subscription 820 notify-subscribed-event (type2 keyword) MUST Event 821 Notification 823 printer-up-time (integer(1:MAX)) * MUST Printer 825 printer-current-time (dateTime) MUST ** Printer 827 notify-sequence-number (integer (0:MAX)) MUST Subscription 829 notify-charset (charset) MUST Subscription 831 notify-natural-language (naturalLanguage) MUST Subscription 833 notify-user-data (octetString(63)) MUST *** Subscription 835 notify-text (text) MUST Event 836 Notification 838 attributes from the "notify-attributes" MUST **** Printer 839 attribute 841 attributes from the "notify-attributes" MUST **** Job 842 attribute 844 attributes from the "notify-attributes" MUST **** Subscription 845 attribute 847 * As specified in [ipp-ntfy] section 9, the value of the 848 "printer-up-time" attribute sent in each Event Notification 849 MUST be the time at which the Event occurred, not the time at 850 which the Event Notification was sent. 852 ** The Printer MUST send the "printer-current-time" attribute 853 if and only if it supports the "printer-current-time" attribute 854 on the Printer object. 856 *** If the associated Subscription Object does not contain a 857 "notify-user-data" attribute, the Printer MUST send an octet- 858 string of length 0. 860 **** If the "notify-attributes" attribute is present on the 861 Subscription Object, the Printer MUST send all attributes 862 specified by the "notify-attributes" attribute. Note: if the 863 Printer doesn't support the "notify-attributes" attribute, it 864 is not present on the associated Subscription Object. 866 For Event Notifications for Job Events, the Printer includes 867 the additional attributes shown in Table 4. 869 Table 4 - Additional Attributes in Event Notification Content for 870 Job Events 872 Source Value Sends Source 873 Object 875 job-id (integer(1:MAX)) MUST Job 877 job-state (type1 enum) MUST Job 879 job-state-reasons (1setOf type2 keyword) MUST Job 881 job-impressions-completed (integer(0:MAX)) MUST * Job 883 * The Printer MUST send the "job-impressions-completed" 884 attribute in an Event Notification only for the combinations of 885 Events and Subscribed Events shown in Table 5. 887 Table 5 - Combinations of Events and Subscribed Events for "job- 888 impressions-completed" 890 Job Event Subscribed Job Event 892 'job-progress' 'job-progress' 894 'job-completed' 'job-completed' 896 'job-completed' 'job-state-changed' 897 For Event Notification for Printer Events, the Printer includes 898 the additional attributes shown in Table 6. 900 Table 6 - Additional Attributes in Event Notification Content for 901 Printer Events 903 Source Value Sends Source 904 Object 906 printer-state (type1 enum) MUST Printer 908 printer-state-reasons (1setOf type2 keyword) MUST Printer 910 printer-is-accepting-jobs (boolean) MUST Printer 912 6 Additional Information about Subscription Template Attributes 914 The 'ippget' Delivery Method does not define any addition 915 Subscription Template attributes. The 'ippget' Delivery Method has 916 the same conformance requirements for Subscription Template 917 attributes as defined in [ipp-ntfy]. This section defines additional 918 information about Subscription Template attributes defined in [ipp- 919 ntfy]. 921 6.1 notify-pull-method (type2 keyword) 923 This Subscription Template attribute identifies the Pull Delivery 924 Method to be used for the Subscription Object (see [ipp-ntfy]). In 925 order to support the 'ippget' Pull Delivery Method defined in this 926 document, the Printer MUST support this attribute with the following 927 keyword value: 929 'ippget': indicates that the IPPGET Pull Delivery Method is to be 930 used for this Subscription Object. 932 7 Subscription Description Attributes 934 The 'ippget' Delivery Method has the same conformance requirements 935 for Subscription Description attributes as defined in [ipp-ntfy]. 936 The 'ippget' Delivery Method does not define any addition 937 Subscription Description attributes. 939 8 Additional Printer Description Attributes 941 This section defines additional Printer Description attributes for 942 use with the 'ippget' Delivery Method. 944 8.1 ippget-event-life (integer(15:MAX)) 946 This Printer Description attribute specifies the Event Life value 947 that the Printer assigns to each Event, i.e., the number of seconds 948 after an Event occurs during which a Printer will return that Event 949 in an Event Notification in a Get-Notifications response. After the 950 Event Life expires for the Event, the Printer MAY no longer return an 951 Event Notification for that Event in a Get-Notifications response. 953 The Printer MUST support this attribute if it supports the 'ippget' 954 Delivery Method. The value MUST be 15 or more (at least 15 seconds) 955 and 60 (seconds) is the RECOMMENDED value to align with the PWG Job 956 Monitoring MIB [RFC2707] jmGeneralJobPersistence and 957 jmGeneralAttributePersistence objects. 959 For example, assume the following: 961 1.a client performs a Job Creation operation that creates a 962 Subscription Object associated with the 'ippget' Delivery 963 Method, AND 965 2.an Event associated with the new Job occurs immediately after 966 the Subscription Object is created, AND 968 3.the same client or some other client performs a Get- 969 Notifications operation such that the client is connected N 970 seconds after the Job Creation operation. 972 Then, if N is less than the value of this attribute, the client(s) 973 performing the Get-Notifications operations can expect not to miss 974 any Event-Notifications, barring some unforeseen lack of memory space 975 in the Printer. Note: The client MUST initiate the Get- 976 Notifications a time that is sufficiently less that N seconds to 977 account for network latency so that it is connected to the Printer 978 before N seconds elapses. 980 If a Printer supports the 'ippget' Delivery Method, it MUST keep 981 'completed', 'canceled', or 'aborted' Job objects in the Job 982 Retention and/or Job History phases for at least as long as this 983 attribute's value. The Printer MAY retain jobs longer that this 984 value. See [RFC2911] section 4.3.7.1 and the discussion in [ipp- 985 ntfy] 'job-completed' event) that explains that a Notification 986 Recipients can query the Job after receiving a 'job-completed' Event 987 Notification in order to find out other information about the job 988 that is 'completed', 'aborted', or 'canceled'. However, this 989 attribute has no effect on the Cancel-Subscription operation which 990 deletes the Subscription object immediately, whether or not it 991 contain the "notify-pull-method" attribute with the 'ippget' keyword 992 value. Immediately thereafter, subsequent Get-Notifications 993 Responses MUST NOT contain Event Notifications associated with the 994 canceled Subscription object. 996 9 New Values for Existing Printer Description Attributes 998 This section defines additional values for existing Printer 999 Description attributes defined in [ipp-ntfy]. 1001 9.1 notify-pull-method-supported (1setOf type2 keyword) 1003 The following keyword value for the "notify-pull-method-supported" 1004 attribute is added in order to support the new Delivery Method 1005 defined in this document: 1007 'ippget' - The IPP Notification Pull Delivery Method defined in 1008 this document. 1010 9.2 operations-supported (1setOf type2 enum) 1012 Table 7 lists the "operation-id" value defined in order to support 1013 the new Get-Notifications operation defined in this document. 1015 Table 7 - Operation-id assignments 1017 Value Operation Name 1019 0x001C Get-Notifications 1021 10 New Status Codes 1023 The following status codes are defined as extensions for this 1024 Delivery Method and are returned as the status code of the Get- 1025 Notifications operation in Group 1 or Group 3 to N. 1027 10.1 successful-ok-events-complete (0x0007) 1029 The Printer MUST return the 'successful-ok-events-complete' status 1030 code to indicate when this Get-Notifications response is the last 1031 response for a Subscription object, whether or not there are Event 1032 Notifications being returned. This condition occurs for Event Wait 1033 Mode with Notification Recipients waiting for responses when the 1034 Subscription Object is: (1) canceled with a Cancel-Subscription 1035 operation, (2) deleted when the Per-Printer Subscription lease time 1036 expires, or (3) when the 'job-completed' event occurs for a Per-Job 1037 Subscription. This condition also occurs for a Get-Notifications 1038 request that a Notification Recipient makes after the job completes, 1039 but before the Event Life expires. 1041 10.2 redirection-other-site (0x0300) 1043 This status code means that the Printer doesn't perform that Get- 1044 Notifications operation and that the "redirect-uri" operation 1045 attribute (see section 5.2.3) in the response contains the uri that 1046 the Notification Recipient MUST use for performing the Get- 1047 Notifications operation. If the client issues subsequent Get- 1048 Notifications operations, it MUST use the value of the "redirect-uri" 1049 operation attribute returned by the Printer as the target of the 1050 operation. 1052 11 Encoding and Transport 1054 This section defines the encoding and transport considerations for 1055 this Delivery Method based on [RFC2910]. 1057 The encoding of a Get-Notifications Response is modeled the Get-Jobs 1058 Response (see [RFC2911]). In a Get-Notifications Response, each 1059 Event Notification Attributes Group MUST start with an 'event- 1060 notification-attributes-tag' (see the section "Encodings of 1061 Additional Attribute Tags" in [ipp-ntfy]), and end with an 'end-of- 1062 attributes-tag'. In addition, for Event Wait Mode the multi- 1063 part/related is used to separate each multiple response (in time) to 1064 a single Get-Notifications Request. 1066 The Printer returns Get-Notification Response as follows: 1068 1. If the Notification Recipient client did not request Event Wait 1069 Mode ("notify-wait" = 'false' or omitted), the Printer ends the 1070 response with an 'end-of-attributes-tag' (see [RFC2911] Get-Jobs 1071 encoding) as with any operation response. 1073 2. If the Notification Recipient client requests Event Wait Mode 1074 ("notify-wait" = 'true') and the Printer wishes to honor the 1075 request, the Printer MUST return the response as an 1076 application/ipp part inside a multi-part/related MIME media 1077 type. When one or more additional Events occur, the Printer 1078 returns each as an additional Event Notification Group using a 1079 separate application/ipp part under the multi-part/related type. 1081 3. If the client requested Event Wait Mode ("notify-wait" = 1082 'true'), but the Printer does not wish to honor the request in 1083 the initial response but wants the client explicitly poll for 1084 Event Notifications, the Printer MUST return the "notify-get- 1085 interval" operation attribute (see section 5.2.1). The Printer 1086 returns the response as an application/ipp part which MAY be 1087 inside an multi-part/related type. The client MUST accept this 1088 response and re-issue the Get-Notifications request in the 1089 future indicated by the value of the "notify-get-interval" 1090 attribute value.. 1092 4. If the client requested Event Wait Mode ("notify-wait" = 1093 'true'), and the Printer initially honored the request, but 1094 later wishes to leave Event Wait Mode, the Printer MUST return 1095 the "notify-get-interval" operation attribute (see section 1096 5.2.1). The Printer returns the response as an application/ipp 1097 part which MUST be inside an multi-part/related type. 1099 Note: All of the above is without either the Printer or the 1100 Notification Recipient closing the connection. In fact, the 1101 connection SHOULD remain open for any subsequent IPP operations. 1102 However, either the Notification Recipient or the Printer can 1103 abnormally terminate by closing the connection. But, if the Printer 1104 closes the connection too soon after returning the response, the 1105 client may not receive the response. 1107 The Printer MAY chunk the responses, but this has no significance to 1108 the IPP semantics. 1110 Note: While HTTP/1.1 allows a proxy to collect chunked responses 1111 over a period of time and return them back as a single un-chunked 1112 response (with a Content Length instead). However, in practice no 1113 proxy wants to have an infinite buffer. Also no proxy want to hold 1114 up responses, since user would be furious. 1116 This notification delivery method uses the IPP transport and encoding 1117 [RFC2910] for the Get-Notifications operation with the following 1118 extension allocated in [ipp-ntfy]: 1120 Table 8 - The "event-notification-attributes-tag" value 1122 Tag Value (Hex) Meaning 1124 0x07 "event-notification-attributes-tag" 1126 12 Conformance Requirements 1128 This section lists the conformance requirements for clients and 1129 Printers. 1131 12.1 Conformance for IPP Printers 1133 It is OPTIONAL for a Printer to support IPP Notifications as defined 1134 in [ipp-ntfy]. However, if a Printer supports IPP Notifications, the 1135 Printer MUST support the 'ippget' Delivery Method as defined in this 1136 document as one of its Delivery Methods. IPP Printers that conform 1137 to this specification: 1139 1. MUST meet the conformance requirements defined in [ipp-ntfy] for 1140 a Pull Delivery Method; 1142 2. MUST support the Get-Notifications operation defined in section 1143 5, including Event Wait Mode; 1145 3. MUST support the Subscription Template object attributes as 1146 defined in section 6; 1148 4. MUST support the Subscription Description object attributes as 1149 defined in section 7; 1151 5. MUST support the "ippget-event-life" Printer Description 1152 attribute defined in section 8.1, including retaining jobs in 1153 the Job Retention and/or Job History phases for at least as long 1154 as the value specified by the Printer's "ippget-event-life"; 1156 6. MUST support the additional values for IPP/1.1 Printer 1157 Description attributes defined in section 9; 1159 7. MUST support the 'successful-ok-events-complete' status code as 1160 described in section 10.1; 1162 8. MUST support the "redirection-other-site" status code defined 1163 10.2, if it redirects Get-Notifications operations; 1165 9. MUST listen for the IPP Get-Notifications operation requests on 1166 IANA-assigned well-known port 631, unless explicitly configured 1167 by system administrators or site policies; 1169 10. SHOULD NOT listen for IPP Get-Notifications operation requests 1170 on any other port, unless explicitly configured by system 1171 administrators or site policies. 1173 11. MUST meet the conformance requirements as stated in section 1174 15.4. 1176 12.2 Conformance for IPP Clients 1178 It is OPTIONAL for an IPP Client to support IPP Notifications as 1179 defined in [ipp-ntfy]. However, if a client supports IPP 1180 Notifications, the client MUST support the 'ippget' Delivery Method 1181 as defined in this document as one of its Delivery Methods. IPP 1182 Clients that conform to this specification: 1184 1.MUST create Subscription Objects containing the "notify-pull- 1185 method" attribute (as opposed to the "notify-recipient-uri" 1186 attribute) using the 'ippget' keyword value (see section 1187 17.1.1); 1189 2.MUST send IPP Get-Notifications operation requests (see section 1190 5.1) via the port specified in the associated 'ipp' URL (if 1191 present) or otherwise via IANA assigned well-known port 631; 1193 3.MUST convert the associated 'ipp' URLs for use in IPP Get- 1194 Notifications operation to their corresponding 'http' URL forms 1195 for use in the HTTP layer according to the rules in section 5 1196 "IPP URL Scheme" in [RFC2910]. 1198 4.MUST meet the conformance requirements as stated in section 1199 15.5. 1201 13 Normative References 1203 [ipp-ntfy] 1204 Herriot, R., and T. Hastings, "Internet Printing Protocol/1.1: IPP 1205 Event Notifications and Subscriptions", , June 27, 2002. 1208 [RFC2119] 1209 S. Bradner, "Key words for use in RFCs to Indicate Requirement 1210 Levels", RFC 2119 , March 1997 1212 [RFC2910] 1213 Herriot, R., Butler, S., Moore, P., and R. Tuner, "Internet 1214 Printing Protocol/1.1: Encoding and Transport", RFC 2910, September 1215 2000. 1217 [RFC2911] 1218 deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, 1219 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 1220 September 2000. 1222 14 Informative References 1224 [RFC2565] 1225 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 1226 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 1227 1999. 1229 [RFC2566] 1230 R. deBry, T. Hastings, R. Herriot, S. Isaacson, and P. Powell, 1231 "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, 1232 April 1999. 1234 [RFC2567] 1235 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 1236 2567, April 1999. 1238 [RFC2568] 1239 Zilles, S., "Rationale for the Structure and Model and Protocol for 1240 the Internet Printing Protocol", RFC 2568, April 1999. 1242 [RFC2569] 1243 Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between 1244 LPD and IPP Protocols", RFC 2569, April 1999. 1246 [RFC2616] 1247 R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. 1248 Leach, T. Berners-Lee, "Hypertext Transfer Protocol - HTTP/1.1", 1249 RFC 2616, June 1999. 1251 [RFC2707] 1252 Bergman, R., Hastings, T., Isaacson, S., and H. Lewis, "Job 1253 Monitoring MIB - V1.0", November 1999. 1255 [RFC3196] 1256 Hastings, T., Manros, C., Zehler, P., Kugler, C., and H. Holst, 1257 "Internet Printing Protocol/1.1: Implementer's Guide", RFC3196, 1258 November 2001. 1260 15 Security Considerations 1262 The IPP Model and Semantics document [RFC2911 section 8] discusses 1263 high-level security requirements (Client Authentication, Server 1264 Authentication and Operation Privacy). The IPP Transport and 1265 Encoding document [RFC2910 section 8] discusses the security 1266 requirements for the IPP protocol. Client Authentication is the 1267 mechanism by which the client proves its identity to the server in a 1268 secure manner. Server Authentication is the mechanism by which the 1269 server proves its identity to the client in a secure manner. 1270 Operation Privacy is defined as a mechanism for protecting operations 1271 from eavesdropping. 1273 The 'ippget' Delivery Method with its Get-Notifications operations 1274 leverages the security mechanism that are used in IPP/1.1 [RFC2910 1275 and RFC2911] without adding any additional security mechanisms in 1276 order to maintain the same security support as IPP/1.1. 1278 The access control model for the Get-Notifications operation defined 1279 in this document is the same as the access control model for the Get- 1280 Job-Attributes operation (see [RFC2911] section 3.2.6). The primary 1281 difference is that a Get-Notifications operation is directed at 1282 Subscription Objects rather than at Job objects, and a returned 1283 attribute group contains Event Notification attributes rather than 1284 Job object attributes. 1286 15.1 Notification Recipient client access rights 1288 The Notification Recipient client MUST have the following access 1289 rights to the Subscription object(s) targeted by the Get- 1290 Notifications operation request: 1292 The authenticated user (see [RFC2911] section 8.3) performing this 1293 operation MUST be (1) the owner of each Subscription Object 1294 identified by the "notify-subscription-ids" operation attribute 1295 (see section 5.1.1), (2) an operator or administrator of the 1296 Printer (see [RFC2911] Sections 1 and 8.5), or (3) be otherwise 1297 authorized by the Printer's administrator-configured security 1298 policy to request Event Notifications from the target Subscription 1299 Object(s). Furthermore, the Printer's security policy MAY limit 1300 the attributes returned by the Get-Notifications operation, in a 1301 manner similar to the Get-Job-Attributes operation (see [RFC2911] 1302 end of section 3.3.4.2). 1304 15.2 Printer security threats 1306 Because the Get-Notifications operation is sent in the same direction 1307 as Job Creation operations, usually by the same client, this Event 1308 Notification Delivery Method poses no additional authentication, 1309 authorization, privacy, firewall, or port assignment issues above 1310 those for the IPP Get-Job-Attributes and Get-Printer-Attributes 1311 operations (see [RFC2911] sections 3.2.6 and 3.2.5). 1313 15.3 Notification Recipient security threats 1315 Unwanted Events Notifications (spam): Unlike Push Event Notification 1316 Delivery Methods in which the IPP Printer initiates the Event 1317 Notification, with the Pull Delivery Method defined in this document, 1318 the Notification Recipient is the client who initiates the Get- 1319 Notifications operation (see section 5). Therefore, there is no 1320 chance of "spam" notifications with this method. 1322 Note: when a client stays connected to a Printer using the Event 1323 Wait Mode (see section 5.1.3) in order to receive Event Notifications 1324 as they occur, such a client can close down the IPP connection at any 1325 time, and so can avoid future unwanted Event Notifications at any 1326 time. 1328 It is true that client has control about whether to ask for Event 1329 Notifications. However, if the client subscribes to an event, and 1330 does a Get-Notifications request, the client gets all events for the 1331 Subscription Object in the sequence number range (see section 5.1.2), 1332 not just the ones the client wants. If a client subscribes to a Per- 1333 Printer Subscription job event, such as 'job-completed', and someone 1334 then starts and cancels thousands of jobs, the client would have to 1335 receive these events in addition to the ones the client is interested 1336 in. A client can protect itself better by subscribing to his own 1337 jobs using a Per-Job Subscription, rather than creating a Per-Printer 1338 subscription whose Job events apply to all jobs. 1340 15.4 Security requirements for Printers 1342 For the Get-Notifications operation defined in this document, the 1343 same Printer conformance requirements apply for supporting and using 1344 Client Authentication, Server Authentication and Operation Privacy as 1345 stated in [RFC2910] section 8 for all IPP operations. 1347 15.5 Security requirements for clients 1349 For the Get-Notifications operation defined in this document, the 1350 same client conformance requirements apply for supporting and using 1351 Client Authentication, Server Authentication and Operation Privacy as 1352 stated in [RFC2910] section 8 for all IPP operations. 1354 16 Internationalization Considerations 1356 The IPP Printer MUST localize the "notify-text" attribute as 1357 specified in section 14 of [ipp-ntfy]. 1359 In addition, when the client receives the Get-Notifications response, 1360 it is expected to localize the attributes that have the 'keyword' 1361 attribute syntax according to the charset and natural language 1362 requested in the Get-Notifications request. 1364 17 IANA Considerations 1366 This section contains the exact information for IANA to add to the 1367 IPP Registries according to the procedures defined in RFC 2911 1368 [RFC2911] section 6. 1370 Note to RFC Editors: Replace RFC NNNN below with the RFC number 1371 for this document, so that it accurately reflects the content of 1372 the information for the IANA Registry. 1374 17.1 Additional attribute value registrations for existing attributes 1376 This section lists additional attribute value registrations for use 1377 with existing attributes defined in other documents. 1379 17.1.1 Additional values for the "notify-pull-method-supported" Printer 1380 attribute 1382 The following table lists the keyword value defined in this document 1383 as an additional keyword value for use with the "notify-pull-method- 1384 supported" Printer attribute defined in [ipp-ntfy]. This is to be 1385 registered according to the procedures in RFC 2911 [RFC2911] section 1386 6.1. 1388 keyword Attribute Values: Ref. Section: 1389 ippget RFC NNNN 9.1 1390 The resulting keyword method attribute value registrations will be 1391 published in the 1392 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 1393 values/notify-pull-method-supported/ 1394 area. 1396 17.1.2 Additional values for the "operations-supported" Printer 1397 attribute 1399 The following table lists the enum attribute value defined in this 1400 document as an additional type2 enum value for use with the 1401 "operations-supported" Printer attribute defined in [RFC2911]. This 1402 is to be registered according to the procedures in RFC 2911 [RFC2911] 1403 section 6.1. 1405 type2 enum Attribute Values: Value Ref. Section: 1406 Get-Notifications 0x001C RFC NNNN 9.2 1408 The resulting enum attribute value registration will be published in 1409 the 1410 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 1411 values/operations-supported/ 1412 area. 1414 17.2 Operation Registrations 1416 The following table lists the operation defined in this document. 1417 This is to be registered according to the procedures in RFC 2911 1418 [RFC2911] section 6.4. 1420 Operations: Ref. Section: 1421 Get-Notifications operation RFC NNNN 5 1423 The resulting operation registration will be published in the 1424 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/operations/ 1425 area. 1427 17.3 Attribute Registrations 1429 The following table lists the attribute defined in this document. 1430 This is to be registered according to the procedures in RFC 2911 1431 [RFC2911] section 6.2. 1433 Printer Description attributes: Ref. Section: 1434 ippget-event-life (integer(15:MAX)) RFC NNNN 8.1 1436 The resulting attribute registration will be published in the 1437 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attributes/ 1438 area. 1440 17.4 Status code Registrations 1442 The following table lists the status code defined in this document. 1443 This is to be registered according to the procedures in RFC 2911 1444 [RFC2911] section 6.6. 1446 Status codes: Ref. Section: 1447 successful-ok-events-complete (0x0007) RFC NNNN 10.1 1448 redirection-other-site (0x0300) RFC NNNN 10.2 1450 The resulting status code registration will be published in the 1451 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/status-codes/ 1452 area. 1454 18 Contributors 1456 Carl Kugler and Harry Lewis contributed the basic idea of in-band 1457 "smart polling" coupled with multiple responses for a single 1458 operation on the same connection, one response for each event as it 1459 occurs. Without their continual persuasion, we would not have 1460 arrived at this Delivery Method specification and would not have been 1461 able to agree on a single REQUIRED Delivery Method for IPP. 1463 Carl Kugler 1464 IBM 1465 P.O. Box 1900 1466 Boulder, CO 80301-9191 1468 Phone: 1469 Fax: 1470 e-mail: kugler@us.ibm.com 1472 Harry Lewis 1473 IBM 1474 P.O. Box 1900 1475 Boulder, CO 80301-9191 1477 Phone: 303-924-5337 1478 FAX: 1479 e-mail: harryl@us.ibm.com 1481 19 Authors' Addresses 1483 Robert Herriot 1484 706 Colorado Ave. 1485 Palo Alto, CA 94303 1487 Phone: 650-327-4466 1488 Fax: 650-327-4466 1489 email: bob@herriot.com 1491 Thomas N. Hastings 1492 Xerox Corporation 1493 737 Hawaii St. ESAE 231 1494 El Segundo CA 90245 1496 Phone: 310-333-6413 1497 Fax: 310-333-5514 1498 email: hastings@cp10.es.xerox.com 1500 IPP Web Page: http://www.pwg.org/ipp/ 1501 IPP Mailing List: ipp@pwg.org 1503 To subscribe to the ipp mailing list, send the following email: 1504 1) send it to majordomo@pwg.org 1505 2) leave the subject line blank 1506 3) put the following two lines in the message body: 1507 subscribe ipp 1508 end 1510 Implementers of this specification document are encouraged to join 1511 the IPP Mailing List in order to participate in any discussions of 1512 clarification issues and review of registration proposals for 1513 additional attributes and values. In order to reduce spam the 1514 mailing list rejects mail from non-subscribers, so you must subscribe 1515 to the mailing list in order to send a question or comment to the 1516 mailing list. 1518 20 Description of Base IPP documents 1520 The base set of IPP documents includes: 1522 Design Goals for an Internet Printing Protocol [RFC2567] 1523 Rationale for the Structure and Model and Protocol for the Internet 1524 Printing Protocol [RFC2568] 1525 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 1526 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 1527 Internet Printing Protocol/1.1: Implementer's Guide [[RFC3196]] 1528 Mapping between LPD and IPP Protocols [RFC2569] 1530 The "Design Goals for an Internet Printing Protocol" document takes a 1531 broad look at distributed printing functionality, and it enumerates 1532 real-life scenarios that help to clarify the features that need to be 1533 included in a printing protocol for the Internet. It identifies 1534 requirements for three types of users: end users, operators, and 1535 administrators. It calls out a subset of end user requirements that 1536 are satisfied in IPP/1.0. A few OPTIONAL operator operations have 1537 been added to IPP/1.1. 1539 The "Rationale for the Structure and Model and Protocol for the 1540 Internet Printing Protocol" document describes IPP from a high level 1541 view, defines a roadmap for the various documents that form the suite 1542 of IPP specification documents, and gives background and rationale 1543 for the IETF working group's major decisions. 1545 The "Internet Printing Protocol/1.1: Model and Semantics" document 1546 describes a simplified model with abstract objects, their attributes, 1547 and their operations that are independent of encoding and transport. 1548 It introduces a Printer and a Job object. The Job object optionally 1549 supports multiple documents per Job. It also addresses security, 1550 internationalization, and directory issues. 1552 The "Internet Printing Protocol/1.1: Encoding and Transport" document 1553 is a formal mapping of the abstract operations and attributes defined 1554 in the model document onto HTTP/1.1 [RFC2616]. It defines the 1555 encoding rules for a new Internet MIME media type called 1556 "application/ipp". This document also defines the rules for 1557 transporting over HTTP a message body whose Content-Type is 1558 "application/ipp". This document defines the 'ipp' scheme for 1559 identifying IPP printers and jobs. 1561 The "Internet Printing Protocol/1.1: Implementer's Guide" document 1562 gives insight and advice to implementers of IPP clients and IPP 1563 objects. It is intended to help them understand IPP/1.1 and some of 1564 the considerations that may assist them in the design of their client 1565 and/or IPP object implementations. For example, a typical order of 1566 processing requests is given, including error checking. Motivation 1567 for some of the specification decisions is also included. 1569 The "Mapping between LPD and IPP Protocols" document gives some 1570 advice to implementers of gateways between IPP and LPD (Line Printer 1571 Daemon) implementations. 1573 21 Full Copyright Statement 1575 Copyright (C) The Internet Society (2001). All Rights Reserved. 1577 This document and translations of it may be copied and furnished to 1578 others, and derivative works that comment on or otherwise explain it 1579 or assist in its implementation may be prepared, copied, published 1580 and distributed, in whole or in part, without restriction of any 1581 kind, provided that the above copyright notice and this paragraph are 1582 included on all such copies and derivative works. However, this 1583 document itself may not be modified in any way, such as by removing 1584 the copyright notice or references to the Internet Society or other 1585 Internet organizations, except as needed for the purpose of 1586 developing Internet standards in which case the procedures for 1587 copyrights defined in the Internet Standards process must be 1588 followed, or as required to translate it into languages other than 1589 English. 1591 The limited permissions granted above are perpetual and will not be 1592 revoked by the Internet Society or its successors or assigns. 1594 This document and the information contained herein is provided on an 1595 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1596 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1597 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1598 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1599 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1601 Acknowledgement 1603 Funding for the RFC Editor function is currently provided by the 1604 Internet Society.