idnits 2.17.1 draft-ietf-ipp-notify-get-05.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 : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC2911,RFC2910], [RFC2566,RFC2565]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 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 329 has weird spacing: '...ll), or a p...' == Line 1688 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 (October 17, 2001) is 8199 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'US-ASCII' is mentioned on line 1123, but not defined == Unused Reference: 'RFC2026' is defined on line 1497, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'IANA-MT' -- Possible downref: Non-RFC (?) normative reference: ref. 'IANA-PORTREG' ** Downref: Normative reference to an Informational RFC: RFC 1900 ** Obsolete normative reference: RFC 2368 (Obsoleted by RFC 6068) ** Obsolete normative reference: RFC 2373 (Obsoleted by RFC 3513) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2565 (Obsoleted by RFC 2910) ** Obsolete normative reference: RFC 2566 (Obsoleted by RFC 2911) ** Downref: Normative reference to an Experimental RFC: RFC 2567 ** Downref: Normative reference to an Experimental RFC: RFC 2568 ** Downref: Normative reference to an Experimental RFC: RFC 2569 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Downref: Normative reference to an Informational RFC: RFC 2707 ** Obsolete normative reference: RFC 2717 (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2732 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2910 (Obsoleted by RFC 8010) ** Obsolete normative reference: RFC 2911 (Obsoleted by RFC 8011) Summary: 20 errors (**), 0 flaws (~~), 9 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Printing Protocol WG Robert Herriot (editor) 3 INTERNET-DRAFT Xerox Corp. 4 Carl Kugler 5 Updates: RFC 2911 Harry Lewis 6 [Target category: standards track] IBM, Corp. 7 Expires: April 17, 2002 October 17, 2001 9 Internet Printing Protocol (IPP): 10 The 'ippget' Delivery Method for Event Notifications 12 Copyright (C) The Internet Society (2001). 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 [rfc2026]. 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.txt 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.0 (IPP) [RFC2566, RFC2565] and IPP/1.1 [RFC2911, RFC2910]. 37 This document specifies the 'ippget' Delivery Method for use with the 38 "IPP Event Notifications and Subscriptions" specification [ipp-ntfy]. 39 When IPP Notification [ipp-ntfy] is supported, the Delivery Method 40 defined in this document is one of the RECOMMENDED Delivery Methods 41 for Printers to support. 43 The 'ippget' Delivery Method is a 'pull' Delivery Method with aspects 44 of a 'push' method as well. That is, when an Event occurs, the 45 Printer saves the Event Notification for a period of time called the 46 Event Life. The Notification Recipient fetches (pulls) Event 47 Notifications using the Get-Notifications operation. If the 48 Notification Recipient has selected the Event Wait Mode option to 49 wait for additional Event Notifications, the Printer continues to 50 return (similar to push) Event Notifications to the Notification 51 Recipient as Get-Notification responses as Events occur. This push 52 aspect is not a true 'push', since the Printer does not open the 53 connect, but rather continues to return responses as Events occur 54 using the connection originated by the Notification Recipient. 56 Either the Notification Recipient or the Printer can terminate Event 57 Wait Mode without closing the connection. 59 Table of Contents 61 1 Introduction.....................................................5 63 2 Terminology......................................................6 65 3 Model and Operation..............................................7 67 4 General Information..............................................9 69 5 Get-Notifications operation.....................................10 70 5.1 Get-Notifications Request.....................................12 71 5.1.1 "notify-subscription-ids" (1setOf integer(1:MAX)):..........12 72 5.1.2 notify-sequence-numbers (1setOf integer(1:MAX)).............13 73 5.1.3 "notify-wait" (boolean):....................................14 74 5.2 Get-Notifications Response....................................14 75 5.2.1 "notify-get-interval" (integer(0:MAX))......................17 76 5.2.2 "printer-up-time" (integer(1:MAX)):.........................19 77 5.2.3 "redirect-uri" (uri):.......................................19 79 6 Additional Information about Subscription Template Attributes...23 80 6.1 notify-recipient-uri (uri)....................................23 82 7 Subscription Description Attributes.............................24 84 8 Additional Printer Description Attributes.......................24 85 8.1 ippget-event-life (integer(15:MAX))...........................24 87 9 New Values for Existing Printer Description Attributes..........25 88 9.1 notify-schemes-supported (1setOf uriScheme)...................25 89 9.2 operations-supported (1setOf type2 enum)......................26 91 10 New Status Codes...............................................26 92 10.1 successful-ok-events-complete (0x0007).......................26 93 10.2 redirection-other-site (0x0300)..............................26 95 11 The IPPGET URL Scheme..........................................27 96 11.1 The IPPGET URL Scheme Applicability and Intended Usage.......27 97 11.2 The IPPGET URL Scheme Associated Port........................27 98 11.3 The IPPGET URL Scheme Associated MIME Type...................27 99 11.4 The IPPGET URL Scheme Character Encoding.....................28 100 11.5 The IPPGET URL Scheme Syntax in ABNF.........................28 101 11.5.1 IPPGET URL Examples........................................29 102 11.5.2 IPPGET URL Comparisons.....................................30 104 12 Encoding and Transport.........................................30 105 13 Conformance Requirements.......................................31 106 13.1 Conformance for IPP Printers.................................31 107 13.2 Conformance for IPP Clients..................................32 109 14 IANA Considerations............................................33 110 14.1 Additional attribute value registrations for existing attributes 111 33 112 14.1.1 Additional values for the "notify-schemes-supported" Printer 113 attribute..............................................33 114 14.1.2 Additional values for the "operations-supported" Printer 115 attribute..............................................34 116 14.2 Operation Registrations......................................34 117 14.3 Attribute Registrations......................................35 118 14.4 Status code Registrations....................................35 120 15 Internationalization Considerations............................35 122 16 Security Considerations........................................35 124 17 References.....................................................36 126 18 Authors' Addresses.............................................38 128 19 Description of Base IPP documents..............................39 130 20 Full Copyright Statement.......................................40 132 Table of Tables 134 Table 1 - Information about the Delivery Method....................9 135 Table 2 - Combinations of "notify-wait", "status-code", and "notify- 136 get-interval" .................................................18 137 Table 3 - Attributes in Event Notification Content................21 138 Table 4 - Additional Attributes in Event Notification Content for Job 139 Events ........................................................22 140 Table 5 - Combinations of Events and Subscribed Events for "job- 141 impressions-completed" ........................................23 142 Table 6 - Additional Attributes in Event Notification Content for 143 Printer Events ................................................23 144 Table 7 - Operation-id assignments................................26 145 Table 8 - The "event-notification-attributes-tag" value...........31 147 1 Introduction 149 The "IPP Event Notifications and Subscriptions" document [ipp-ntfy] 150 defines an OPTIONAL extension to Internet Printing Protocol/1.0 (IPP) 151 [RFC2566, RFC2565] and IPP/1.1 [RFC2911, RFC2910]. For a description 152 of the base IPP documents, see section 19. The [ipp-ntfy] extension 153 defines operations that a client can perform in order to create 154 Subscription Objects in a Printer and carry out other operations on 155 them. A Subscription Object represents a Subscription abstraction. 156 A client associates Subscription Objects with a particular Job by 157 performing the Create-Job-Subscriptions operation or by submitting a 158 Job with subscription information. A client associates Subscription 159 Objects with the Printer by performing a Create-Printer-Subscriptions 160 operation. Four other operations are defined for Subscription 161 Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- 162 Subscription, and Cancel-Subscription. The Subscription Object 163 specifies that when one of the specified Events occurs, the Printer 164 sends an asynchronous Event Notification to the specified 165 Notification Recipient via the specified Delivery Method (i.e., 166 protocol). 168 The "IPP Event Notifications and Subscriptions" document [ipp-ntfy] 169 specifies that each Delivery Method is defined in another document. 170 This document is one such document, and it specifies the 'ippget' 171 delivery method. When IPP Notification [ipp-ntfy] is supported, the 172 Delivery Method defined in this document is one of the RECOMMENDED 173 Delivery Methods for Printers to support. 175 The 'ippget' Delivery Method is a 'pull' Delivery Method with aspects 176 of a 'push' method as well. That is, when an Event occurs, the 177 Printer saves the Event Notification for a period of time called the 178 Event Life. The Notification Recipient fetches (pulls) the Event 179 Notifications using the Get-Notifications operation. This operation 180 causes the Printer to return all Event Notifications held for the 181 specified Subscription object(s). If the Notification Recipient has 182 selected the Event Wait Mode option to wait for additional Event 183 Notifications, the Printer continues to return (similar to push) 184 Event Notifications to the Notification Recipient as Get-Notification 185 responses as Events occur. This push aspect is not a true 'push', 186 since the Printer does not open the transaction, but rather continues 187 to return responses as Events occur using the transaction originated 188 by the Notification Recipient. 190 The Notification Recipient can terminate Event Wait Mode (without 191 closing the connection) by supplying the "notify-wait" attribute with 192 a 'false' value in a subsequent Get-Notifications request. 193 Similarly, the Printer can terminate Event Wait Mode (without closing 194 the connection) by returning the "notify-get-interval" operation 195 attribute in a Get-Notifications response which tells the 196 Notification Recipient how long to wait before trying again. 198 2 Terminology 200 This section defines the following terms that are used throughout 201 this document: 203 This document uses the same terminology as [RFC2911], such as 204 "client", "Printer", "Job", "attribute", "attribute value", 205 "keyword", "operation", "request", "response", and "support". 207 Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD 208 NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to 209 conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 210 12.1. If an implementation supports the extension defined in this 211 document, then these terms apply; otherwise, they do not. These 212 terms define conformance to this document only; they do not affect 213 conformance to other documents, unless explicitly stated otherwise. 215 Event Life: The length of time in seconds after an Event occurs 216 during which the Printer will return that Event in a Event 217 Notification in a Get-Notifications response. After the Event 218 Life expires, the Printer will no longer return an Event 219 Notification for that Even in a Get-Notifications response. 221 Event Notification Attributes Group: The attributes group in a 222 response that contains attributes that are part of an Event 223 Notification. 225 Event Wait Mode: The mode requested by a Notification Recipient 226 client in its Get-Notifications Request and granted by a Printer 227 to keep the connection open where the Printer sends subsequent 228 Event Notifications to the Notification Recipient as they occur 229 as additional Get-Notification Responses. 231 Other capitalized terms, such as Notification Recipient, Event, Event 232 Notification, Compound Event Notification, Printer, etc., are 233 defined in [ipp-ntfy], have the same meanings, and are not 234 reproduced here. However, for convenience the following key 235 terms are reproduced here: 237 Event - some occurrence (either expected or unexpected) within the 238 printing system of a change of state, condition, or 239 configuration of a Job or Printer object. An Event occurs only 240 at one instant in time and does not span the time the physical 241 Event takes place. For example, jam-occurred and jam-cleared 242 are two distinct, instantaneous Events, even though the jam may 243 last for a while. 245 Event Notification - the information about an Event that the Printer 246 sends when an Event occurs. 248 3 Model and Operation 250 In a Subscription Creation Operation, when the value of the "notify- 251 recipient-uri" attribute has the scheme 'ippget', the client is 252 requesting that the Printer use the 'ippget' Delivery Method for the 253 Event Notifications associated with the new Subscription Object. The 254 client SHOULD choose a value for the address part of the "notify- 255 recipient-uri" attribute that uniquely identifies the Notification 256 Recipient. 258 When an Event occurs, the Printer MUST generate an Event Notification 259 and MUST assign it the Event Life. The Printer MUST hold an Event 260 Notification for its assigned Event Life. 262 When a Notification Recipient wants to receive Event Notifications 263 for a Subscription object, it performs the Get-Notifications 264 operation supplying the Subscription object's subscription-id, which 265 causes the Printer to return all un-expired Event Notifications held 266 for that Subscription object. If the Notification Recipient has 267 selected the Event Wait Mode option to wait for additional Event 268 Notifications, the response to the Get-Notifications request 269 continues indefinitely as the Printer continues to send Event 270 Notifications in the response as Events occur for that Subscription 271 object. 273 When the Notification Recipient requests Event Notifications for per- 274 Job Subscription Objects, the Notification Recipient typically 275 performs the Get-Notifications operation within a second of 276 performing the Subscription Creation operation. Because the Printer 277 MUST save Event Notifications for at least 15 seconds (see section 278 8.1), the Notification Recipient is unlikely to miss any Event 279 Notifications that occur between the Subscription Creation and the 280 Get-Notifications operation. 282 ISSUE 01: Although we agreed to extend Job Creation operations to 283 support Event Wait Mode, it seems to be an unnecessary complication, 284 since the Printer MUST keep events for at least 15 seconds. So OK 285 NOT to add the "notify-wait" (boolean) operation attribute to Job 286 Creation operations and NOT have to have Job Creation responses 287 return Event Notification Groups (in addition to returning 288 Subscription Attribute Groups). 290 The 'ippget' Delivery Method is designed primarily for (1) a client 291 that wants to get Events (from the job's per-Job Subscription object) 292 for a job that it has submitted and (2) for a privileged client that 293 wants to get all job or printer Events from a per-Printer 294 Subscription object. If several groups of users expect to receive 295 jobs from other users (FAX paradigm) and each group has a different 296 designated person, say, a secretary, to receive job completion 297 Events, the Printer should be configured to support multiple URLs, 298 one for each group. Then the designated person can run an 299 application that gets the events for jobs submitted to that URL from 300 the per-Printer Subscription object that the application creates. 302 4 General Information 304 If a Printer supports this Delivery Method, the following are its 305 characteristics. 307 Table 1 - Information about the Delivery Method 309 Document Method Conformance Requirement Delivery Method 310 Realization 312 1. What is the URL scheme name for the ippget 313 Delivery Method? 315 2. Is the Delivery Method REQUIRED, RECOMMENDED 316 RECOMMENDED or OPTIONAL for an IPP 317 Printer to support? 319 3. What transport and delivery protocols IPP with one new 320 does the Printer use to deliver the operation. 321 Event Notification Content, i.e., what 322 is the entire network stack? 324 4. Can several Event Notifications be Yes. 325 combined into a Compound Event 326 Notification? 328 5. Is the Delivery Method initiated by This Delivery Method is 329 the Notification Recipient (pull), or a pull method with 330 by the Printer (push)? aspects of a push 331 method, though the 332 Printer does not 333 initiate the connection. 335 6. Is the Event Notification content Machine Consumable 336 Machine Consumable or Human 337 Consumable? 339 7. What section in this document answers Section 5 340 the following question? For a Machine 341 Consumable Event Notification, what is 342 the representation and encoding of 343 values defined in section 9.1 of [ipp- 344 ntfy] and the conformance requirements 345 thereof? For a Human Consumable Event 346 Notification, what is the 347 Notification, what is the 348 representation and encoding of pieces 349 of information defined in section 9.2 350 of [ipp-ntfy] and the conformance 351 requirements thereof? 353 8. What are the latency and reliability Same as IPP and the 354 of the transport and delivery underlying HTTP 355 protocol? transport 357 9. What are the security aspects of the Same as IPP and the 358 transport and delivery protocol, e.g., underlying HTTP 359 how it is handled in firewalls? transport and in the 360 same direction, so no 361 new firewall 362 considerations. 364 10.What are the content length None 365 restrictions? 367 11.What are the additional values or 368 pieces of information that a Printer 369 sends in an Event Notification content 370 and the conformance requirements 371 thereof? None 373 12.What are the additional Subscription None 374 Template and/or Subscription 375 Description attributes and the 376 conformance requirements thereof? 378 13.What are the additional Printer "ipp-event-life" 379 Description attributes and the (integer (15: MAX)) 380 conformance requirements thereof? 382 5 Get-Notifications operation 384 This operation is issued by a client acting in the role of a 385 Notification Recipient requesting the Printer to return all Event 386 Notifications held for the identified Subscription object(s). 388 A Printer MUST support this operation. 390 When a Printer performs this operation, it MUST return all and only 391 those Event Notifications: 393 1. Whose associated Subscription Object's "notify-subscription-id" 394 Subscription Description attribute equals one of the values of 395 the "notify-subscription-ids" (1setOf integer(1:MAX)) operation 396 attribute AND 398 2. Whose associated Subscription Object's "notify-recipient-uri" 399 attribute matches the scheme value of 'ippget' using the (case- 400 insensitive) matching rules in section 11.5.2 AND 402 3. Whose "notify-sequence-number" is equal to or greater than the 403 corresponding value of the "notify-sequence-numbers (1setOf 404 integer(1:MAX)) operation attribute, if supplied AND 406 4. Whose Event Life has not yet expired AND 408 5. Where the Notification Recipient is the owner of or has read- 409 access rights to the identified Subscription Object. 411 The Notification Recipient client can request Event Wait Mode by 412 supplying the "notify-wait" operation attribute with a 'true' value. 414 The Notification Recipient client can terminate Event Wait Mode 415 (without closing the connection) by supplying the "notify-wait" 416 attribute with a 'false' value in a subsequent Get-Notifications 417 request. Similarly, the Printer can terminate Event Wait Mode 418 (without closing the connection) by returning the "notify-get- 419 interval" operation attribute in a Get-Notifications response which 420 tells the Notification Recipient how long to wait before trying 421 again. 423 The Printer MUST accept the request in any state (see [RFC2911] 424 "printer-state" and "printer-state-reasons" attributes) and MUST 425 remain in the same state with the same "printer-state-reasons" 426 values. 428 Access Rights: If the policy of the Printer is to allow all users to 429 access all Event Notifications, then the Printer MUST accept this 430 operation from any user. Otherwise, the authenticated user (see 431 [RFC2911] section 8.3) performing this operation MUST be the owner of 432 each Subscription Object identified by the "notify-subscription-ids" 433 operation attribute (as returned during a Subscription Creation 434 Operation) or an operator or administrator of the Printer (see 435 [RFC2911] Sections 1 and 8.5). Otherwise, the IPP object MUST reject 436 the operation and return: 'client-error-forbidden', 'client-error- 437 not-authenticated', or 'client-error-not-authorized' status code as 438 appropriate. 440 5.1 Get-Notifications Request 442 The following groups of attributes are part of the Get-Notifications 443 Request: 445 Group 1: Operation Attributes 447 Natural Language and Character Set: 448 The "attributes-charset" and "attributes-natural-language" 449 attributes as described in [RFC2911] section 3.1.4.1. 451 Target: 452 The "printer-uri" (uri) operation attribute which is the target 453 for this operation as described in [RFC2911] section 3.1.5. 455 Requesting User Name: 456 The "requesting-user-name" (name(MAX)) attribute SHOULD be 457 supplied by the client as described in [RFC2911] section 8.3. 459 5.1.1 "notify-subscription-ids" (1setOf integer(1:MAX)): 461 This attribute identifies one or more Subscription objects for 462 which Events are requested. The client MUST supply this 463 attribute with at least one value. The Printer object MUST 464 support this attribute with multiple values. 466 If no Subscription Object exists with the supplied identifier, 467 the Printer MUST return the 'client-error-not-found' status 468 code. 470 If an identified Subscription Object does not have a "notify- 471 recipients-uri" Subscription attribute with 'ippget' scheme 472 (case insensitive-match - see section 11.5.2), the Printer MUST 473 reject the request and return the 'client-error-uri-scheme-not- 474 supported' status code. 476 Note: The name of both the "notify-subscription-ids" and 477 "notify-sequence-numbers" end in 's', since they are 478 multi-valued. However, there are other occurrences of 479 these attribute names without the 's' that are single 480 valued. 482 5.1.2 notify-sequence-numbers (1setOf integer(1:MAX)) 484 This attribute specifies one or more lowest Event Notification 485 sequence number values for the Subscription objects identified 486 by the corresponding values of the "notify-subscription-ids" 487 operation attribute. The Notification Recipient SHOULD supply 488 this attribute and the number of values SHOULD be the same as 489 the number of values of the "notify-subscriptions-ids" 490 attribute. The Printer MUST support this attribute with 491 multiple values. 493 The Printer MUST NOT return Notification Events with lower 494 sequence numbers for the corresponding Subscription object. 495 Therefore, by supplying the proper values for this attribute 496 the Notification Recipient can prevent getting the same Event 497 Notifications from a Subscription object that were returned on 498 a previous Get-Notifications request. The Notification 499 Recipient SHOULD remember the highest "notify-sequence-number" 500 value returned for each Subscription object requested and 501 SHOULD pass that value for each requested Subscription object 502 on the next Get-Notifications request. 504 If the Notification Recipient supplies fewer values for this 505 attribute (including omitting this attribute) than for the 506 "notify-subscription-ids" operation attribute, the Printer 507 assumes a '1' value for each missing value. A value of '1' 508 causes the Printer to return any un-expired Event Notification 509 for that Subscription object, since '1' is the lowest possible 510 sequence number. If the Notification Recipient supplies more 511 values for this attribute than the number of values for the 512 "notify-subscription-ids" operation attribute, the Printer 513 ignores the extra values. 515 Note: If a Notification Recipient performs two consecutive Get- 516 Notifications operations with the same value for "notify- 517 sequence-number" (or omits the attribute), the time stamp of 518 the first Event Notification in the second Get-Notifications 519 Response may be less than the time stamp of the last Event 520 Notification in the first Get-Notification Response. This 521 happens because the Printer sends all unexpired Event 522 Notification with a sequence number equal or higher according 523 to the ordering specified in [ipp-ntfy] and some Event 524 Notifications from the first Get-Notifications operation may 525 not have expired by the time the second Get-Notifications 526 operation occurs. 528 5.1.3 "notify-wait" (boolean): 530 This value indicates whether or not the Notification Recipient 531 wants Event Wait Mode. The client MAY supply this attribute. 532 The Printer object MUST support both values of this attribute. 534 If the client supplies the 'false' value or omits this 535 attribute, the client is not requesting Event Wait Mode. If 536 the value is 'true', the client is requesting Event Wait Mode. 537 See the beginning of section 5.2 for the rules for Event Wait 538 Mode. 540 5.2 Get-Notifications Response 542 The Printer has the following options for responding to a Get- 543 Notifications Request: 545 1. The Printer can reject the request and return the 'server-error- 546 busy' status code, if the Printer is too busy to accept this 547 operation at this time. In this case, the Printer MUST return 548 the "get-notify-interval" operation attribute to indicate when 549 the client SHOULD try again. 551 2. If the Notification Recipient did not request Event Wait Mode 552 ("notify-wait-mode" = 'false' or omitted), the Printer MUST 553 return immediately whatever Event Notifications it currently 554 holds in the requested Subscription object(s) and MUST return 555 the "notify-get-interval" operation attribute with number of 556 seconds from now at which the Notification Recipient SHOULD 557 repeat the Get-Notifications Request to get future Event 558 Notifications. 560 3. If the Notification Recipient requested Event Wait Mode 561 ("notify-wait-mode" = 'true'), the Printer MUST return 562 immediately whatever Event Notifications it currently holds in 563 the requested Subscription object(s) and MUST continue to return 564 Event Notifications as they occur until all of the requested 565 Subscription Objects are canceled. A Subscription Object is 566 canceled either via the Cancel-Subscription operation or by the 567 Printer (e.g., the Subscription Object is canceled when the 568 associated Job completes and is no longer in the Job Retention 569 or Job History phase - see the "ippget-event-life 570 (integer(15:MAX))" attribute discussion in section 8.1). 572 However, the Printer MAY decide to terminate Event Wait Mode at 573 any time, including in the first response. In this case the 574 Printer MUST return the "notify-get-interval" operation 575 attribute. This attribute indicates that the Printer wishes to 576 leave Event Wait Mode and the number of seconds in the future 577 that the Notification Recipient SHOULD try the Get-Notifications 578 operation again. The Notification Recipient MUST accept this 579 response and MUST disconnect. If the Notification Recipient 580 does not disconnect, the Printer SHOULD do so. 582 From the Notification Recipient's view, the response appears as an 583 initial burst of data, which includes the Operation Attributes Group 584 and one Event Notification Attributes Group per Event Notification 585 that the Printer is holding. After the initial burst of data, if the 586 Notification Recipient has selected the Event Wait Mode option to 587 wait for additional Event Notifications, the Notification Recipient 588 receives occasional Event Notification Attribute Groups. Proxy 589 servers may delay some Event Notifications or cause time-outs to 590 occur. The client MUST be prepared to perform the Get-Notifications 591 operation again when time-outs occur. 593 Each attribute is encoded using the IPP rules for encoding attributes 594 [RFC2910] and MAY be encoded in any order. Note: the Get-Jobs 595 response in [RFC2911] acts as a model for encoding multiple groups of 596 attributes. See section 12 for the encoding and transport rules. 598 The following groups of attributes are part of the Get-Notifications 599 Response: 601 Group 1: Operation Attributes 603 Status Message: 604 In addition to the REQUIRED status code returned in every 605 response, the response OPTIONALLY includes a "status-message" 606 (text(255)) and/or a "detailed-status-message" (text(MAX)) 607 operation attribute as described in [RFC2911] sections 13 and 608 3.1.6. 610 The Printer can return any status codes defined in [RFC2911]. 611 If the status code is not 'successful-xxx', the Printer MUST 612 NOT return any Event Notification Attribute groups. The 613 following is a description of the important status codes: 615 successful-ok: the response contains all Event Notification 616 associated with the specified subscription-ids that had 617 been supplied in the "notify-subscription-ids" operation 618 attribute in the request. If the requested Subscription 619 Objects have no associated Event Notification, the 620 response MUST contain zero Event Notifications. 621 successful-ok-events-complete: indicate when this return 622 is the last return for all Subscription objects that 623 match the request, whether or not there are Event 624 Notifications being returned. This condition occurs for 625 Event Wait Mode with Notification Recipients waiting for 626 responses when the Subscription Object is: (1) canceled 627 with a Cancel-Subscription operation, (2) deleted when 628 the Per-Printer Subscription lease time expires, or (3) 629 when the 'job-completed' event occurs for a Per-Job 630 Subscription. This condition also occurs for a Get- 631 Notifications request that a Notification Recipient makes 632 after the job completes, but before the Event Life 633 expires. See section 10.1. 634 client-error-not-found: The Printer has no Subscription 635 Object's whose "notify-subscription-id" attribute equals 636 any of the values of the "notify-subscription-ids" 637 operation attribute supplied. 638 server-error-busy: The Printer is too busy to accept this 639 operation. The Printer SHOULD return the "notify-get- 640 interval" operation attribute in the Operation Attributes 641 of the response, then the Notification Recipient SHOULD 642 wait for the number of seconds specified by the "notify- 643 get-interval" operation attribute before performing this 644 operation again. If the "notify-get-interval" Operation 645 Attribute is not present, the Notification Recipient 646 SHOULD use the normal network back-off algorithms for 647 determining when to perform this operation again. 648 redirection-other-site: The Printer does not handle this 649 operation and requests the Notification Recipient to 650 perform the operation again with the uri specified by the 651 "redirect-uri" Operation Attribute in the response. See 652 section 10.2. 654 Natural Language and Character Set: 655 The "attributes-charset" and "attributes-natural-language" 656 attributes as described in [RFC2911] section 3.1.4.2. 658 The Printer MUST use the values of "notify-charset" and 659 "notify-natural-language", respectively, from one Subscription 660 Object associated with the Event Notifications in this 661 response. 663 Normally, there is only one matched Subscription Object, or the 664 value of the "notify-charset" and "notify-natural-language" 665 attributes is the same in all Subscription Objects. If not, the 666 Printer MUST pick one Subscription Object from which to obtain 667 the value of these attributes. The algorithm for picking the 668 Subscription Object is implementation dependent. The choice of 669 natural language is not critical because 'text' and 'name' 670 values can override the "attributes-natural-language" operation 671 attribute. The Printer's choice of charset is critical because 672 a bad choice may leave it unable to send some 'text' and 'name' 673 values accurately. 675 5.2.1 "notify-get-interval" (integer(0:MAX)) 677 The value of this operation attribute is the number of seconds 678 that the Notification Recipient SHOULD wait before trying the 679 Get-Notifications operation again. The Printer MUST return 680 this operation attribute if: (1) it is too busy to return 681 events, (2) the Notification Recipient client did not request 682 Event Wait Mode, or (3) the Printer is terminating Event Wait 683 Mode. The client MUST accept this attribute and SHOULD re- 684 issue the Get-Notifications operation (with or without "notify- 685 wait" = 'true') the indicated number of seconds in the future 686 in order to get more Event Notifications This value is 687 intended to help the client be a good network citizen. 689 The value of this attribute MUST be at least as large as the 690 value of the Printer's "ippget-event-life" Printer Description 691 attribute (see section 8.1). The Printer MAY return a value 692 that is larger than the value of the "ippget-event-life" 693 Printer Description attribute provided that the Printer 694 increases the Event Life for this Subscription object, so that 695 Notification Recipients taking account of the larger value and 696 polling with a longer interval will not miss events. Note; 697 implementing such an algorithm requires some hidden attributes 698 in the Subscription object that are IMPLEMENTATION DEPENDENT. 700 If the Printer wants to remain in Event Wait Mode, then the 701 Printer MUST NOT return this attribute in the response. 703 Here is a complete table of combinations of "notify-wait", 704 "status-code", "notify-get-interval", and Event Notification 705 Attributes Groups for Get-Notification initial (Wait and No 706 Wait) Responses and subsequent Event Wait Mode Responses (which 707 may be staying in Event Wait Mode or may be requesting the 708 Notification Recipient to leave Event Wait Mode): 710 Table 2 - Combinations of "notify-wait", "status-code", and "notify- 711 get-interval" 713 client sends: Printer Event 714 returns: returns: Notification 715 "notify-wait" "status-code" "notify-get- Attribute 716 interval" Groups 718 1. 'successful- MUST return N maybe 719 'false'/omitte ok' 720 d 722 2. 'not-found' MUST NOT MUST NOT 723 'false'/omitte 724 d 726 3. 'busy' MUST return N MUST NOT 727 'false'/omitte 728 d 730 4. 'events- MUST NOT 'job- 731 'false'/omitte complete' completed' 732 d 734 5. 'true' 'successful- MUST NOT MUST 735 ok' 737 6. 'true' 'successful- MUST return N maybe 738 ok' 740 7. 'true' 'not-found' MUST NOT MUST NOT 742 8. 'true' 'busy' MUST return N MUST NOT 744 9. 'true' 'events- MUST NOT 'job- 745 complete' completed' or 746 maybe other 748 Explanation: 750 1-4: client does not request Event Wait Mode 751 5-9: client requests Event Wait Mode 752 2,7: Subscription object not found, or was canceled earlier; 753 client should NOT try again. 754 3,8: server busy, tells client to try later; client should try 755 again in N seconds. 756 4: client polled after job completed, but before Event Life 757 expired, and got the 'job-completed' event, so the client 758 shouldn't bother trying again; client should NOT try again 759 later. 760 5: Printer returns one or more Event Notifications and is OK 761 to stay in Event Wait Mode; the client waits for more Event 762 Notifications to be returned. 763 6: Printer wants to leave Event Wait mode. Can happen on the 764 first response (with or without Event Notifications) or happen 765 on a subsequent response with or without Event Notifications; 766 the client SHOULD try again in N seconds. 767 9: Printer either (1) returns 'job-completed' event or (2) the 768 Subscription Object was canceled by either a Cancel-Job or a 769 Per-Printer Subscription expired without being renewed. For 770 case (1), at least one Event Notification MUST be returned, 771 while for case (2), it is unlikely that any Event Notifications 772 are returned; the client should NOT try again. 774 5.2.2 "printer-up-time" (integer(1:MAX)): 776 The value of this attribute is the Printer's "printer-up-time" 777 attribute at the time the Printer sends this response. The 778 Printer MUST return this attribute. Because each Event 779 Notification also contains the value of this attribute when the 780 event occurred, the value of this attribute lets a Notification 781 Recipient know when each Event Notification occurred relative 782 to the time of this response. 784 5.2.3 "redirect-uri" (uri): 786 The value of this attribute is the uri that the Notification 787 Recipient MUST use for a subsequent Get-Notifications 788 operation. The Printer MAY support this attribute. This 789 attribute MUST be returned in the Operation Attributes Group if 790 and only if the Printer returns the 'redirection-other-site' 791 status code (see section 10.2). 793 Group 2: Unsupported Attributes 794 See [RFC2911] section 3.1.7 for details on returning 795 Unsupported Attributes. 797 Group 3 through N: Event Notification Attributes 799 The Printer responds with one Event Notification Attributes 800 Group per matched Event Notification. The entire response is 801 considered a single Compound Event Notification (see [ipp- 802 ntfy]). The matched Event Notifications are all un-expired 803 Event Notification associated with the matched Subscription 804 Objects and MUST follow the "Event Notification Ordering" 805 requirements for Event Notifications within a Compound Event 806 Notification specified in [ipp-ntfy] section 9. In other 807 words, the Printer MUST order these Event Notification groups 808 in ascending time stamp (and sequence number) order for a 809 Subscription object. If Event Notifications for multiple 810 Subscription objects are being returned, the Notification 811 Events for the next Subscription object follow in ascending 812 time stamp order, etc. 814 Each Event Notification Group MUST contain all of attributes 815 specified in section 9.1 ("Content of Machine Consumable Event 816 Notifications") of [ipp-ntfy] with exceptions denoted by 817 asterisks in the tables below. 819 The tables below are copies of the tables in section 9.1 820 ("Content of Machine Consumable Event Notifications") of [ipp- 821 ntfy] except that each cell in the "Sends" column is a "MUST". 823 If more than one Event Notification is being returned and the 824 status of each is not the same, then the Printer MUST return a 825 "notify-status-code" attribute in each Event Notification 826 Attributes group to indicate the differing status values. 828 For an Event Notification for all Events, the Printer includes 829 the attributes shown in Table 3. 831 Table 3 - Attributes in Event Notification Content 833 Source Value Sends Source 834 Object 836 notify-subscription-id (integer(1:MAX)) MUST Subscription 838 notify-printer-uri (uri) MUST Subscription 840 notify-subscribed-event (type2 keyword) MUST Event 841 Notification 843 printer-up-time (integer(1:MAX)) * MUST Printer 845 printer-current-time (dateTime) MUST ** Printer 847 notify-sequence-number (integer (0:MAX)) MUST Subscription 849 notify-charset (charset) MUST Subscription 851 notify-natural-language (naturalLanguage) MUST Subscription 853 notify-user-data (octetString(63)) MUST *** Subscription 855 notify-text (text) MUST Event 856 Notification 858 attributes from the "notify-attributes" MUST **** Printer 859 attribute 861 attributes from the "notify-attributes" MUST **** Job 862 attribute 864 attributes from the "notify-attributes" MUST **** Subscription 865 attribute 867 * As specified in [ipp-ntfy] section 9, the value of the 868 "printer-up-time" attribute sent in each Event Notification 869 MUST be the time at which the Event occurred, not the time at 870 which the Event Notification was sent. 872 ** The Printer MUST send the "printer-current-time" attribute 873 if and only if it supports the "printer-current-time" attribute 874 on the Printer object. 876 *** If the associated Subscription Object does not contain a 877 "notify-user-data" attribute, the Printer MUST send an octet- 878 string of length 0. 880 **** If the "notify-attributes" attribute is present on the 881 Subscription Object, the Printer MUST send all attributes 882 specified by the "notify-attributes" attribute. Note: if the 883 Printer doesn't support the "notify-attributes" attribute, it 884 is not present on the associated Subscription Object. 886 For Event Notifications for Job Events, the Printer includes 887 the additional attributes shown in Table 4. 889 Table 4 - Additional Attributes in Event Notification Content for 890 Job Events 892 Source Value Sends Source 893 Object 895 job-id (integer(1:MAX)) MUST Job 897 job-state (type1 enum) MUST Job 899 job-state-reasons (1setOf type2 keyword) MUST Job 901 job-impressions-completed (integer(0:MAX)) MUST * Job 903 * The Printer MUST send the "job-impressions-completed" 904 attribute in an Event Notification only for the combinations of 905 Events and Subscribed Events shown in Table 5. 907 Table 5 - Combinations of Events and Subscribed Events for "job- 908 impressions-completed" 910 Job Event Subscribed Job Event 912 'job-progress' 'job-progress' 914 'job-completed' 'job-completed' 916 'job-completed' 'job-state-changed' 918 For Event Notification for Printer Events, the Printer includes 919 the additional attributes shown in Table 6. 921 Table 6 - Additional Attributes in Event Notification Content for 922 Printer Events 924 Source Value Sends Source 925 Object 927 printer-state (type1 enum) MUST Printer 929 printer-state-reasons (1setOf type2 keyword) MUST Printer 931 printer-is-accepting-jobs (boolean) MUST Printer 933 6 Additional Information about Subscription Template Attributes 935 The 'ippget' Delivery Method does not define any addition 936 Subscription Template attributes. The 'ippget' Delivery Method has 937 the same conformance requirements for Subscription Template 938 attributes as defined in [ipp-ntfy]. This section defines additional 939 information about Subscription Template attributes defined in [ipp- 940 ntfy]. 942 6.1 notify-recipient-uri (uri) 944 This section describes the syntax of the value of this attribute for 945 the 'ippget' Delivery Method. The syntax for values of this 946 attribute for other Delivery Method is defined in other Delivery 947 Method Documents. 949 In order to support the 'ippget' Delivery Method and Protocol, the 950 Printer MUST support the following syntax: 952 The 'ippget://' URI scheme. The remainder of the URI indicates 953 something unique about the Notification Recipient, such as its host 954 name or host address (and optional path). However, the remainder 955 of the URI is not used by the Printer in any way. Its value MAY be 956 useful to Notification Recipients who are not the Subscription 957 Creation clients. See section 11 for a complete definition of the 958 syntax of the IPPGET URL. 960 7 Subscription Description Attributes 962 The 'ippget' Delivery Method has the same conformance requirements 963 for Subscription Description attributes as defined in [ipp-ntfy]. 964 The 'ippget' Delivery Method does not define any addition 965 Subscription Description attributes. 967 8 Additional Printer Description Attributes 969 This section defines additional Printer Description attributes for 970 use with the 'ippget' Delivery Method. 972 8.1 ippget-event-life (integer(15:MAX)) 974 This Printer Description attribute specifies the Event Life value 975 that the Printer assigns to each Event, i.e., the number of seconds 976 after an Event occurs during which a Printer will return that Event 977 in an Event Notification in a Get-Notifications response. After the 978 Event Life expires for the Event, the Printer MAY no longer return an 979 Event Notification for that Event in a Get-Notifications response. 981 The Printer MUST support this attribute if it supports the 'ippget' 982 Delivery Method. The value MUST be 15 or more (at least 15 seconds) 983 and 60 (seconds) is the RECOMMENDED value to align with the PWG Job 984 Monitoring MIB [RFC2707] jmGeneralJobPersistence and 985 jmGeneralAttributePersistence objects. 987 For example, assume the following: 989 1.a client performs a Job Creation operation that creates a 990 Subscription Object associated with the 'ippget' Delivery 991 Method, AND 993 2.an Event associated with the new Job occurs immediately after 994 the Subscription Object is created, AND 996 3.the same client or some other client performs a Get- 997 Notifications operation such that the client is connected N 998 seconds after the Job Creation operation. 1000 Then, if N is less than the value of this attribute, the client(s) 1001 performing the Get-Notifications operations can expect not to miss 1002 any Event-Notifications, barring some unforeseen lack of memory space 1003 in the Printer. Note: The client MUST initiate the Get- 1004 Notifications a time that is sufficiently less that N seconds to 1005 account for network latency so that it is connected to the Printer 1006 before N seconds elapses. 1008 If a Printer supports the 'ippget' Delivery Method, it MUST keep 1009 'completed', 'canceled', or 'aborted' Job objects in the Job 1010 Retention and/or Job History phases for at least as long as this 1011 attribute's value. The Printer MAY retain jobs longer that this 1012 value. See [RFC2911] section 4.3.7.1 and the discussion in [ipp- 1013 ntfy] 'job-completed' event) that explains that a Notification 1014 Recipients can query the Job after receiving a 'job-completed' Event 1015 Notification in order to find out other information about the job 1016 that is 'completed', 'aborted', or 'canceled'. However, this 1017 attribute has no effect on the Cancel-Subscription operation which 1018 deletes the Subscription object immediately, whether or not it 1019 contain the 'ippget' scheme. Immediately thereafter, subsequent Get- 1020 Notifications Responses MUST NOT contain Event Notifications 1021 associated with the canceled Subscription object. 1023 9 New Values for Existing Printer Description Attributes 1025 This section defines additional values for existing Printer 1026 Description attributes defined in [ipp-ntfy]. 1028 9.1 notify-schemes-supported (1setOf uriScheme) 1030 The following value for the "notify-schemes-supported" attribute is 1031 added in order to support the new Delivery Method defined in this 1032 document: 1034 'ippget' - The IPP Notification Delivery Method defined in this 1035 document. 1037 9.2 operations-supported (1setOf type2 enum) 1039 Table 7 lists the "operation-id" value defined in order to support 1040 the new Get-Notifications operation defined in this document. 1042 Table 7 - Operation-id assignments 1044 Value Operation Name 1046 0x001C Get-Notifications 1048 10 New Status Codes 1050 The following status codes are defined as extensions for this 1051 Delivery Method and are returned as the status code of the Get- 1052 Notifications operation. 1054 10.1 successful-ok-events-complete (0x0007) 1056 The Printer MUST return the 'successful-ok-events-complete' status 1057 code to indicate when this Get-Notifications response is the last 1058 response for a Subscription object, whether or not there are Event 1059 Notifications being returned. This condition occurs for Event Wait 1060 Mode with Notification Recipients waiting for responses when the 1061 Subscription Object is: (1) canceled with a Cancel-Subscription 1062 operation, (2) deleted when the Per-Printer Subscription lease time 1063 expires, or (3) when the 'job-completed' event occurs for a Per-Job 1064 Subscription. This condition also occurs for a Get-Notifications 1065 request that a Notification Recipient makes after the job completes, 1066 but before the Event Life expires. 1068 10.2 redirection-other-site (0x0300) 1070 This status code means that the Printer doesn't perform that Get- 1071 Notifications operation and that the "redirect-uri" operation 1072 attribute in the response contains the uri that the Notification 1073 Recipient MUST use for performing the Get-Notifications operation. 1075 If the client issues subsequent Get-Notifications operations, it MUST 1076 use the value of the "redirect-uri" operation attribute returned by 1077 the Printer as the target of the operation. 1079 11 The IPPGET URL Scheme 1081 This section defines the 'ippget' URL and the conformance 1082 requirements for using it. 1084 11.1 The IPPGET URL Scheme Applicability and Intended Usage 1086 This section is intended for use in registering the 'ippget' URL 1087 scheme with IANA and fully conforms to the requirements in [RFC2717]. 1088 This document defines the 'ippget'" URL (Uniform Resource Locator) 1089 scheme for specifying a unique identifier for an IPP Client which 1090 implements the IPP Get-Notifications operation specified in this 1091 document (see section 5). 1093 ISSUE 02: How unique do we need now that the Printer doesn't use 1094 anything but the scheme? 1096 The intended usage of the 'ippget' URL scheme is COMMON. 1098 11.2 The IPPGET URL Scheme Associated Port 1100 None. 1102 An 'ippget' URL behaves as a unique identifier for IPP Clients and is 1103 NOT used to initiate any over-the-wire protocol associations. 1105 See: IANA Port Numbers Registry [IANA-PORTREG]. 1107 11.3 The IPPGET URL Scheme Associated MIME Type 1109 All IPP Get-Notifications operations (requests and responses) MUST be 1110 conveyed in an 'application/ipp' MIME media type as registered in 1111 [IANA-MT]. An 'ippget' URL MUST uniquely identify an IPP Client that 1112 support this 'application/ipp' MIME media type. 1114 See: IANA MIME Media Types Registry [IANA-MT]. 1116 11.4 The IPPGET URL Scheme Character Encoding 1118 The 'ippget' URL scheme defined in this document is based on the ABNF 1119 for the URI Generic Syntax [RFC2396] and further updated by [RFC2732] 1120 and [RFC2373] (for IPv6 addresses in URLs). The 'ippget' URL scheme 1121 is case-insensitive in the scheme and 'authority' part as in 1122 [RFC2396]; however, the 'abs_path' part is case-sensitive, as in 1123 [RFC2396]. Code points outside [US-ASCII] MUST be hex escaped by the 1124 mechanism specified in [RFC2396]. 1126 11.5 The IPPGET URL Scheme Syntax in ABNF 1128 This document is intended for use in registering the 'ippget' URL 1129 scheme with IANA and fully conforms to the requirements in [RFC2717]. 1130 This document defines the 'ippget' URL (Uniform Resource Locator) 1131 scheme for specifying a unique identifier for an IPP Client which 1132 implements IPP 'Get-Notifications' operation specified in this 1133 document. 1135 The intended usage of the 'ippget' URL scheme is COMMON. 1137 The value of an 'ippget' URI MUST NOT exceed 255 octets (see section 1138 8.1), since the URI is for identification rather than for identifying 1139 the location of a network resource. An IPP Printer MUST return the 1140 'client-error-request-value-too-long' status code (see section 1141 13.1.4.10 in [RFC2911]) when a URI received in a request is too long. 1143 An 'ippget' URL MUST be represented in absolute form. Absolute URLs 1144 always begin with a scheme name followed by a colon. For definitive 1145 information on URL syntax and semantics, see "Uniform Resource 1146 Identifiers (URI): Generic Syntax and Semantics" [RFC2396]. This 1147 specification adopts the definitions of "authority", "abs_path", 1148 "query", "reg_name", "server", "userinfo", and "hostport" from 1149 [RFC2396], as updated by [RFC2732] and [RFC2373] (for IPv6 addresses 1150 in URLs). 1152 The 'ippget' URL scheme syntax in ABNF is as follows: 1154 ippget_URL = "ippget:" "//" authority [ abs_path [ "?" query ]] 1155 authority = server | reg_name 1156 reg_name = 1*( unreserved | escaped | "$" | "," | 1157 ";" | ":" | "@" | "&" | "=" | "+" ) 1158 server = [ [ userinfo "@" ] hostport ] 1159 userinfo = *( unreserved | escaped | 1160 ";" | ":" | "&" | "=" | "+" | "$" | "," ) 1161 hostport = host [ ":" port ] 1162 abs_path = "/" path_segments 1164 If the port is empty or not given, then no port is assumed. The 1165 semantics are that the 'ippget' URL is a unique identifier for an IPP 1166 Client that will retrieve IPP event notifications via the IPP Get- 1167 Notifications operation. 1169 Note: The use of IP addresses in URLs SHOULD be avoided whenever 1170 possible (see [RFC1900]). 1172 11.5.1 IPPGET URL Examples 1174 The following are examples of valid 'ippget' URLs for IPP Clients 1175 (using DNS host names): 1177 ippget://abc.com 1178 ippget://abc.com/listener 1179 ippget://bob@abc.com 1180 ippget://bob@abc.com/listener/1232 1182 Note: The use of IP addresses in URLs SHOULD be avoided whenever 1183 possible (see [RFC1900]). 1185 The IPP Client that creates the Subscription object and the 1186 Notification Recipient have to agree on a unique IPPGET URL value in 1187 order for the Get-Notifications operations to retrieve the proper 1188 Event Notifications. Therefore, the choice of 'userinfo@hostport' 1189 versus the simpler 'hostport' production in an 'ippget' URL may be 1190 influenced by the intended usage. 1192 If a given IPP Client creates an IPP Subscription object for event 1193 notifications intended for retrieval by the same IPP Client, then the 1194 simple 'hostport' production may be most appropriate. In this case, 1195 the IPP Client and the Notification Recipient both know the 1196 'hostport' of the client. 1198 On the other hand, if a given IPP Client creates an IPP Subscription 1199 object for event notifications intended for retrieval by a different 1200 IPP Client, then the 'userinfo@hostport' production (using, for 1201 example, the right-hand side of a 'mailto:' URL, see [RFC2368]) may 1202 be most appropriate. For this case, a mail address serves as the 1203 prior agreement on the IPPGET URL value between the IPP Client and 1204 the Notification Recipient. 1206 11.5.2 IPPGET URL Comparisons 1208 When comparing two 'ippget' URLs to decide if they match or not, an 1209 IPP Client or IPP Printer MUST use the same rules as those defined 1210 for HTTP URI comparisons in [RFC2616]. 1212 12 Encoding and Transport 1214 This section defines the encoding and transport considerations for 1215 this Delivery Method based on [RFC2910]. 1217 The encoding of a Get-Notifications Response is modeled the Get-Jobs 1218 Response (see [RFC2911]). In a Get-Notifications Response, each 1219 Event Notification Attributes Group MUST start with an 'event- 1220 notification-attributes-tag' (see the section "Encodings of 1221 Additional Attribute Tags" in [ipp-ntfy]), and end with an 'end-of- 1222 attributes-tag'. In addition, for Event Wait Mode the multi- 1223 part/related is used to separate each multiple response (in time) to 1224 a single Get-Notifications Request. 1226 The Printer returns Get-Notification Response as follows: 1228 1. If the Notification Recipient client did not request Event Wait 1229 Mode ("notify-wait" = 'false' or omitted), the Printer ends the 1230 response with an 'end-of-attributes-tag' (see [RFC2911] Get-Jobs 1231 encoding) as with any operation response. 1233 2. If the Notification Recipient client requests Event Wait Mode 1234 ("notify-wait" = 'true') and the Printer wishes to honor the 1235 request, the Printer MUST return the response as an 1236 application/ipp part inside a multi-part/related MIME media 1237 type. When one or more additional Events occur, the Printer 1238 returns each as an additional Event Notification Group using a 1239 separate application/ipp part under the multi-part/related type. 1241 3. If the client requested Event Wait Mode ("notify-wait" = 1242 'true'), but the Printer does not wish to honor the request in 1243 the initial response but wants the client explicitly poll for 1244 Event Notifications, the Printer MUST return the "notify-get- 1245 interval" operation attribute (see section 5.2.1). The Printer 1246 returns the response as an application/ipp part which MAY be 1247 inside an multi-part/related type. The client MUST accept this 1248 response and re-issue the Get-Notifications request in the 1249 future indicated by the value of the "notify-get-interval" 1250 attribute value.. 1252 4. If the client requested Event Wait Mode ("notify-wait" = 1253 'true'), and the Printer initially honored the request, but 1254 later wishes to leave Event Wait Mode, the Printer MUST return 1255 the "notify-get-interval" operation attribute (see section 1256 5.2.1). The Printer returns the response as an application/ipp 1257 part which MUST be inside an multi-part/related type. 1259 Note: All of the above is without either the Printer or the 1260 Notification Recipient closing the connection. In fact, the 1261 connection SHOULD remain open for any subsequent IPP operations. 1262 However, either the Notification Recipient or the Printer can 1263 abnormally terminate by closing the connection. But, if the Printer 1264 closes the connection too soon after returning the response, the 1265 client may not receive the response. 1267 The Printer MAY chunk the responses, but this has no significance to 1268 the IPP semantics. 1270 Note: While HTTP/1.1 allows a proxy to collect chunked responses 1271 over a period of time and return them back as a single un-chunked 1272 response (with a Content Length instead). However, in practice no 1273 proxy wants to have an infinite buffer. Also no proxy want to hold 1274 up responses, since user would be furious. 1276 This notification delivery method uses the IPP transport and encoding 1277 [RFC2910] for the Get-Notifications operation with the following 1278 extension allocated in [ipp-ntfy]: 1280 Table 8 - The "event-notification-attributes-tag" value 1282 Tag Value (Hex) Meaning 1284 0x07 "event-notification-attributes-tag" 1286 13 Conformance Requirements 1288 The 'ippget' Delivery Method is RECOMMEND for Printers to support. 1290 13.1 Conformance for IPP Printers 1292 IPP Printers that conform to this specification: 1294 1. MUST meet the conformance requirements defined in [ipp-ntfy]; 1296 2. MUST support the Get-Notifications operation defined in section 1297 5, including Event Wait Mode; 1299 3. MUST support the Subscription Template object attributes as 1300 defined in section 6; 1302 4. MUST support the Subscription Description object attributes as 1303 defined in section 7; 1305 5. MUST support the "ippget-event-life" Printer Description 1306 attribute defined in section 8.1, including retaining jobs in 1307 the Job Retention and/or Job History phases for at least as long 1308 as the value specified by the Printer's "ippget-event-life"; 1310 6. MUST support the additional values for IPP/1.1 Printer 1311 Description attributes defined in section 9; 1313 7. MUST support the 'successful-ok-events-complete' status code as 1314 described in section 10.1; 1316 8. MUST support the "redirection-other-site" status code defined 1317 10.2, if it redirects Get-Notifications operations; 1319 9. MUST listen for the IPP Get-Notifications operation requests on 1320 IANA-assigned well-known port 631, unless explicitly configured 1321 by system administrators or site policies; 1323 10. SHOULD NOT listen for IPP Get-Notifications operation requests 1324 on any other port, unless explicitly configured by system 1325 administrators or site policies. 1327 13.2 Conformance for IPP Clients 1329 IPP Clients that conform to this specification: 1331 1.MUST create unambiguously unique 'ippget' URLs in all cases that 1332 conform to the ABNF specified in section 11.5 of this document; 1334 2.;MUST send IPP Get-Notifications operation requests via the port 1335 specified in the associated 'ipp' URL (if present) or otherwise 1336 via IANA assigned well-known port 631; 1338 3.MUST convert the associated 'ipp' URLs for use in IPP Get- 1339 Notifications operation to their corresponding 'http' URL forms 1340 for use in the HTTP layer according to the rules in section 5 1341 "IPP URL Scheme" in [RFC2910]. 1343 Note: The use of ambiguous 'ippget' URLs is NOT an optional feature 1344 for IPP Clients; it is a non-conformant implementation error. 1346 14 IANA Considerations 1348 IANA shall register the 'ippget' URL scheme as defined in section 11 1349 according to the procedures of [RFC2717]. 1351 The rest of this section contains the exact information for IANA to 1352 add to the IPP Registries according to the procedures defined in RFC 1353 2911 [RFC2911] section 6. 1355 Note to RFC Editors: Replace RFC NNNN below with the RFC number 1356 for this document, so that it accurately reflects the content of 1357 the information for the IANA Registry. 1359 14.1 Additional attribute value registrations for existing attributes 1361 This section lists additional attribute value registrations for use 1362 with existing attributes defined in other documents. 1364 14.1.1 Additional values for the "notify-schemes-supported" Printer 1365 attribute 1367 The following table lists the uriScheme value defined in this 1368 document as an additional uriScheme value for use with the "notify- 1369 schemes-supported" Printer attribute defined in [ipp-ntfy]. This 1370 is to be registered according to the procedures in RFC 2911 [RFC2911] 1371 section 6.1. 1373 uriScheme Attribute Values: Ref. Section: 1374 ippget RFC NNNN 9.1 1375 The resulting URI scheme attribute value registrations will be 1376 published in the 1377 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 1378 values/notify-schemes-supported/ 1379 area. 1381 14.1.2 Additional values for the "operations-supported" Printer 1382 attribute 1384 The following table lists the enum attribute value defined in this 1385 document as an additional type2 enum value for use with the 1386 "operations-supported" Printer attribute defined in [RFC2911]. This 1387 is to be registered according to the procedures in RFC 2911 [RFC2911] 1388 section 6.1. 1390 type2 enum Attribute Values: Value Ref. Section: 1391 Get-Notifications 0x001C RFC NNNN 9.2 1393 The resulting enum attribute value registration will be published in 1394 the 1395 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute- 1396 values/operations-supported/ 1397 area. 1399 14.2 Operation Registrations 1401 The following table lists the operation defined in this document. 1402 This is to be registered according to the procedures in RFC 2911 1403 [RFC2911] section 6.4. 1405 Operations: Ref. Section: 1406 Get-Notifications operation RFC NNNN 5 1408 The resulting operation registration will be published in the 1409 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/operations/ 1410 area. 1412 14.3 Attribute Registrations 1414 The following table lists the attribute defined in this document. 1415 This is to be registered according to the procedures in RFC 2911 1416 [RFC2911] section 6.2. 1418 Printer Description attributes: Ref. Section: 1419 ippget-event-life (integer(15:MAX)) RFC NNNN 8.1 1421 The resulting attribute registration will be published in the 1422 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attributes/ 1423 area. 1425 14.4 Status code Registrations 1427 The following table lists the status code defined in this document. 1428 This is to be registered according to the procedures in RFC 2911 1429 [RFC2911] section 6.6. 1431 Status codes: Ref. Section: 1432 successful-ok-events-complete (0x0007) RFC NNNN 10.1 1433 redirection-other-site (0x0300) RFC NNNN 10.2 1435 The resulting status code registration will be published in the 1436 ftp://ftp.iana.org/in-notes/iana/assignments/ipp/status-codes/ 1437 area. 1439 15 Internationalization Considerations 1441 The IPP Printer MUST localize the "notify-text" attribute as 1442 specified in section 14 of [ipp-ntfy]. 1444 In addition, when the client receives the Get-Notifications response, 1445 it is expected to localize the attributes that have the 'keyword' 1446 attribute syntax according to the charset and natural language 1447 requested in the Get-Notifications request. 1449 16 Security Considerations 1451 The IPP Model and Semantics document [RFC2911] discusses high-level 1452 security requirements (Client Authentication, Server Authentication 1453 and Operation Privacy). Client Authentication is the mechanism by 1454 which the client proves its identity to the server in a secure 1455 manner. Server Authentication is the mechanism by which the server 1456 proves its identity to the client in a secure manner. Operation 1457 Privacy is defined as a mechanism for protecting operations from 1458 eavesdropping. 1460 Unlike other Event Notification delivery methods in which the IPP 1461 Printer initiates the Event Notification, with the method defined in 1462 this document, the Notification Recipient is the client who initiates 1463 the Get-Notifications operation. Therefore, there is no chance of 1464 "spam" notifications with this method. Furthermore, such a client 1465 can close down the HTTP channel at any time, and so can avoid future 1466 unwanted Event Notifications at any time. 1468 Because the Get-Notifications operation is sent in the same direction 1469 as Job Creation operations, this Event Notification Delivery Method 1470 poses no additional firewall or port assignment issues. 1472 17 References 1474 [IANA-MT] 1475 IANA Registry of Media Types: ftp://ftp.iana.orgisi.edu/in- 1476 notes/iana/assignments/media-types/ 1478 [IANA-PORTREG] 1479 IANA Port Numbers Registry. ftp://ftp.isi.edu/in- 1480 notes/iana/assignments/port-numbers 1482 [ipp-iig] 1483 Hastings, T., Manros, C., Kugler, K, Holst H., Zehler, P., 1484 "Internet Printing Protocol/1.1: draft-ietf-ipp-implementers- 1485 guide-v11-03.txt, work in progress, July 17, 2001 1487 [ipp-ntfy] 1488 R. Herriot, Hastings, T., Isaacson, S., Martin, J., deBry, R., 1489 Shepherd, M., Bergman, R., "Internet Printing Protocol/1.1: IPP 1490 Event Notifications and Subscriptions", , August 20, 2001. 1493 [RFC1900] 1494 B. Carpenter, Y. Rekhter. Renumbering Needs Work, RFC 1900, 1495 February 1996. 1497 [RFC2026] 1498 S. Bradner, "The Internet Standards Process -- Revision 3", RFC 1499 2026, October 1996. 1501 [RFC2119] 1502 S. Bradner, "Key words for use in RFCs to Indicate Requirement 1503 Levels", RFC 2119 , March 1997 1505 [RFC2368] 1506 P. Hoffman, L. Masinter, J. Zawinski. The "mailto" URL Scheme, RFC 1507 2368, July 1998. 1509 [RFC2373] 1510 R. Hinden, S. Deering. IP Version 6 Addressing Architecture, RFC 1511 2373, July 1998. 1513 [RFC2396] 1514 Berners-Lee, T. et al. Uniform Resource Identifiers (URI): Generic 1515 Syntax, RFC 2396, August 1998 1517 [RFC2565] 1518 Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet 1519 Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 1520 1999. 1522 [RFC2566] 1523 R. deBry, T. Hastings, R. Herriot, S. Isaacson, and P. Powell, 1524 "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, 1525 April 1999. 1527 [RFC2567] 1528 Wright, D., "Design Goals for an Internet Printing Protocol", RFC 1529 2567, April 1999. 1531 [RFC2568] 1532 Zilles, S., "Rationale for the Structure and Model and Protocol for 1533 the Internet Printing Protocol", RFC 2568, April 1999. 1535 [RFC2569] 1536 Herriot, R., Hastings, T., Jacobs, N., Martin, J., "Mapping between 1537 LPD and IPP Protocols", RFC 2569, April 1999. 1539 [RFC2616] 1540 R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. 1541 Leach, T. Berners-Lee, "Hypertext Transfer Protocol - HTTP/1.1", 1542 RFC 2616, June 1999. 1544 [RFC2707] 1545 Bergman, R., Hastings, T., Isaacson, S., and H. Lewis, "Job 1546 Monitoring MIB - V1.0", November 1999. 1548 [RFC2717] 1549 R. Petke and I. King, "Registration Procedures for URL Scheme 1550 Names", RFC 2717, November 1999. 1552 [RFC2732] 1553 R. Hinden, B. Carpenter, L. Masinter. Format for Literal IPv6 1554 Addresses in URL's, RFC 2732, December 1999. 1556 [RFC2910] 1557 Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing 1558 Protocol/1.1: Encoding and Transport", RFC 2910, September 2000. 1560 [RFC2911] 1561 R. deBry, T. Hastings, R. Herriot, S. Isaacson, P. Powell, 1562 "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, 1563 September 2000. 1565 18 Authors' Addresses 1567 Robert Herriot 1568 Xerox Corp. 1569 3400 Hill View Ave, Building 1 1570 Palo Alto, CA 94304 1572 Phone: 650-813-7696 1573 Fax: 650-813-6860 1574 e-mail: robert.herriot@pahv.xerox.com 1576 Carl Kugler 1577 IBM 1578 P.O. Box 1900 1579 Boulder, CO 80301-9191 1581 Phone: 1582 Fax: 1583 e-mail: kugler@us.ibm.com 1585 Harry Lewis 1586 IBM 1587 P.O. Box 1900 1588 Boulder, CO 80301-9191 1590 Phone: 303-924-5337 1591 FAX: 1592 e-mail: harryl@us.ibm.com 1593 IPP Web Page: http://www.pwg.org/ipp/ 1594 IPP Mailing List: ipp@pwg.org 1596 To subscribe to the ipp mailing list, send the following email: 1597 1) send it to majordomo@pwg.org 1598 2) leave the subject line blank 1599 3) put the following two lines in the message body: 1600 subscribe ipp 1601 end 1603 Implementers of this specification document are encouraged to join 1604 the IPP Mailing List in order to participate in any discussions of 1605 clarification issues and review of registration proposals for 1606 additional attributes and values. In order to reduce spam the 1607 mailing list rejects mail from non-subscribers, so you must subscribe 1608 to the mailing list in order to send a question or comment to the 1609 mailing list. 1611 19 Description of Base IPP documents 1613 The base set of IPP documents includes: 1615 Design Goals for an Internet Printing Protocol [RFC2567] 1616 Rationale for the Structure and Model and Protocol for the Internet 1617 Printing Protocol [RFC2568] 1618 Internet Printing Protocol/1.1: Model and Semantics [RFC2911] 1619 Internet Printing Protocol/1.1: Encoding and Transport [RFC2910] 1620 Internet Printing Protocol/1.1: Implementer's Guide [ipp-iig] 1621 Mapping between LPD and IPP Protocols [RFC2569] 1622 Internet Printing Protocol (IPP): IPP Event Notifications and 1623 Subscriptions [ipp-ntfy] 1625 The "Design Goals for an Internet Printing Protocol" document takes a 1626 broad look at distributed printing functionality, and it enumerates 1627 real-life scenarios that help to clarify the features that need to be 1628 included in a printing protocol for the Internet. It identifies 1629 requirements for three types of users: end users, operators, and 1630 administrators. It calls out a subset of end user requirements that 1631 are satisfied in IPP/1.0. A few OPTIONAL operator operations have 1632 been added to IPP/1.1. 1634 The "Rationale for the Structure and Model and Protocol for the 1635 Internet Printing Protocol" document describes IPP from a high level 1636 view, defines a roadmap for the various documents that form the suite 1637 of IPP specification documents, and gives background and rationale 1638 for the IETF working group's major decisions. 1640 The "Internet Printing Protocol/1.1: Model and Semantics" document 1641 describes a simplified model with abstract objects, their attributes, 1642 and their operations that are independent of encoding and transport. 1643 It introduces a Printer and a Job object. The Job object optionally 1644 supports multiple documents per Job. It also addresses security, 1645 internationalization, and directory issues. 1647 The "Internet Printing Protocol/1.1: Encoding and Transport" document 1648 is a formal mapping of the abstract operations and attributes defined 1649 in the model document onto HTTP/1.1 [RFC2616]. It defines the 1650 encoding rules for a new Internet MIME media type called 1651 "application/ipp". This document also defines the rules for 1652 transporting over HTTP a message body whose Content-Type is 1653 "application/ipp". This document defines the 'ippget' scheme for 1654 identifying IPP printers and jobs. 1656 The "Internet Printing Protocol/1.1: Implementer's Guide" document 1657 gives insight and advice to implementers of IPP clients and IPP 1658 objects. It is intended to help them understand IPP/1.1 and some of 1659 the considerations that may assist them in the design of their client 1660 and/or IPP object implementations. For example, a typical order of 1661 processing requests is given, including error checking. Motivation 1662 for some of the specification decisions is also included. 1664 The "Mapping between LPD and IPP Protocols" document gives some 1665 advice to implementers of gateways between IPP and LPD (Line Printer 1666 Daemon) implementations. 1668 The "IPP Event Notifications and Subscriptions" document defines an 1669 extension to IPP/1.0 [RFC2566, RFC2565] and IPP/1.1 [RFC2911, 1670 RFC2910]. This extension allows a client to subscribe to printing 1671 related Events and defines the semantics for delivering asynchronous 1672 Event Notifications to the specified Notification Recipient via a 1673 specified Delivery Method (i.e., protocols) defined in (separate) 1674 Delivery Method documents. 1676 20 Full Copyright Statement 1678 Copyright (C) The Internet Society (2001). All Rights Reserved. 1680 This document and translations of it may be copied and furnished to 1681 others, and derivative works that comment on or otherwise explain it 1682 or assist in its implementation may be prepared, copied, published 1683 and distributed, in whole or in part, without restriction of any 1684 kind, provided that the above copyright notice and this paragraph are 1685 included on all such copies and derivative works. However, this 1686 document itself may not be modified in any way, such as by removing 1687 the copyright notice or references to the Internet Society or other 1688 Internet organizations, except as needed for the purpose of 1689 developing Internet standards in which case the procedures for 1690 copyrights defined in the Internet Standards process must be 1691 followed, or as required to translate it into languages other than 1692 English. 1694 The limited permissions granted above are perpetual and will not be 1695 revoked by the Internet Society or its successors or assigns. 1697 This document and the information contained herein is provided on an 1698 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1699 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1700 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1701 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1702 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1704 Acknowledgement 1706 Funding for the RFC Editor function is currently provided by the 1707 Internet Society.