standards/rfc3996.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                         R. Herriot
   8 Request for Comments: 3996                     Global Workflow Solutions
   9 Updates: 2911                                                T. Hastings
  10 Category: Standards Track                                    Xerox Corp.
  11                                                                 H. Lewis
  12                                                                IBM Corp.
  13                                                               March 2005
  14
  15
  16                    Internet Printing Protocol (IPP):
  17           The 'ippget' Delivery Method for Event Notifications
  18
  19 Status of This Memo
  20
  21    This document specifies an Internet standards track protocol for the
  22    Internet community, and requests discussion and suggestions for
  23    improvements.  Please refer to the current edition of the "Internet
  24    Official Protocol Standards" (STD 1) for the standardization state
  25    and status of this protocol.  Distribution of this memo is unlimited.
  26
  27 Copyright Notice
  28
  29    Copyright (C) The Internet Society (2005).
  30
  31 Abstract
  32
  33    This document describes an extension to the Internet Printing
  34    Protocol1.1: Model and Semantics (RFC 2911, RFC 2910).  This document
  35    specifies the 'ippget' Pull Delivery Method for use with the
  36    "Internet Printing Protocol (IPP): Event Notifications and
  37    Subscriptions" specification (RFC 3995).  This IPPGET Delivery Method
  38    is REQUIRED for all clients and Printers that support RFC 3995.  The
  39    Notification Recipient, acting as a client, fetches (pulls) Event
  40    Notifications by using the Get-Notifications operation defined in
  41    this document.
  42
  43 Table of Contents
  44
  45    1.   Introduction. . . . . . . . . . . . . . . . . . . . . . . . .  3
  46    2.   Terminology . . . . . . . . . . . . . . . . . . . . . . . . .  3
  47         2.1.  Conformance Terminology . . . . . . . . . . . . . . . .  4
  48         2.2.  Other Terminology . . . . . . . . . . . . . . . . . . .  4
  49    3.   Model and Operation . . . . . . . . . . . . . . . . . . . . .  4
  50    4.   General Information . . . . . . . . . . . . . . . . . . . . .  5
  51    5.   Get-Notifications Operation . . . . . . . . . . . . . . . . .  7
  52         5.1.  Get-Notifications Request . . . . . . . . . . . . . . .  8
  53               5.1.1.  notify-subscription-ids (1setOf integer(1:MAX))  8
  54               5.1.2.  notify-sequence-numbers (1setOf integer(1:MAX))  9
  55
  56
  57
  58 Herriot, et al.             Standards Track                     [Page 1]
  59 \f
  60 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
  61
  62
  63               5.1.3.  notify-wait (boolean) . . . . . . . . . . . . . 10
  64         5.2.  Get-Notifications Response. . . . . . . . . . . . . . . 10
  65               5.2.1.  notify-get-interval (integer(0:MAX)). . . . . . 13
  66               5.2.2.  printer-up-time (integer(1:MAX)). . . . . . . . 14
  67    6.   Additional Information about Subscription Template Attributes 17
  68         6.1.  notify-pull-method (type2 keyword). . . . . . . . . . . 17
  69    7.   Subscription Description Attributes . . . . . . . . . . . . . 18
  70    8.   Additional Printer Description Attributes . . . . . . . . . . 18
  71         8.1.  ippget-event-life (integer(15:MAX)) . . . . . . . . . . 18
  72    9.   New Values for Existing Printer Description Attributes. . . . 19
  73         9.1.  notify-pull-method-supported (1setOf type2 keyword) . . 19
  74         9.2.  operations-supported (1setOf type2 enum). . . . . . . . 19
  75    10.  New Status Codes. . . . . . . . . . . . . . . . . . . . . . . 19
  76         10.1.  successful-ok-events-complete (0x0007) . . . . . . . . 20
  77    11.  Encoding and Transport. . . . . . . . . . . . . . . . . . . . 20
  78    12.  Conformance Requirements. . . . . . . . . . . . . . . . . . . 21
  79         12.1.  Conformance for IPP Printers . . . . . . . . . . . . . 21
  80         12.2.  Conformance for IPP Clients. . . . . . . . . . . . . . 22
  81    13.  Normative References. . . . . . . . . . . . . . . . . . . . . 23
  82    14.  Informative References. . . . . . . . . . . . . . . . . . . . 23
  83    15.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
  84         15.1.  Attribute Registrations. . . . . . . . . . . . . . . . 24
  85         15.2.  Delivery Method and Additional Keyword Attribute Value
  86                registrations for Existing Attributes. . . . . . . . . 24
  87         15.3.  Additional Enum Attribute Values . . . . . . . . . . . 25
  88         15.4.  Operation Registrations. . . . . . . . . . . . . . . . 25
  89         15.5.  Status Code Registrations. . . . . . . . . . . . . . . 25
  90    16.  Internationalization Considerations . . . . . . . . . . . . . 25
  91    17.  Security Considerations . . . . . . . . . . . . . . . . . . . 26
  92         17.1.  Notification Recipient Client Access Rights. . . . . . 26
  93         17.2.  Printer Security Threats . . . . . . . . . . . . . . . 27
  94         17.3.  Notification Recipient Security Threats. . . . . . . . 27
  95         17.4.  Security Requirements for Printers . . . . . . . . . . 27
  96         17.5.  Security Requirements for clients. . . . . . . . . . . 28
  97    18.  Description of Base IPP Documents (Informative) . . . . . . . 28
  98    19.  Contributors. . . . . . . . . . . . . . . . . . . . . . . . . 29
  99    Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
 100    Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 31
 101
 102 Table of Tables
 103
 104    Table 1.  Information about the Delivery Method. . . . . . . . . .  5
 105    Table 2.  Combinations of "notify-wait", "status-code", and
 106              "notify-get-interval". . . . . . . . . . . . . . . . . . 13
 107    Table 3.  Attributes in Event Notification Content . . . . . . . . 15
 108    Table 4.  Additional Attributes in Event Notification Content for
 109              Job Events . . . . . . . . . . . . . . . . . . . . . . . 16
 110
 111
 112
 113
 114 Herriot, et al.             Standards Track                     [Page 2]
 115 \f
 116 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 117
 118
 119    Table 5.  Combinations of Events and Subscribed Events for "job-
 120              impressions-completed" . . . . . . . . . . . . . . . . . 17
 121    Table 6.  Additional Attributes in Event Notification Content for
 122              Printer Events . . . . . . . . . . . . . . . . . . . . . 17
 123    Table 7.  Operation-id Assignments . . . . . . . . . . . . . . . . 19
 124    Table 8.  The "event-notification-attributes-tag" Value. . . . . . 21
 125
 126 1.  Introduction
 127
 128    This document describes an extension to the Internet Printing
 129    Protocol/1.1: Model and Semantics [RFC 2911], [RFC 2910].  This
 130    document specifies the 'ippget' Pull Delivery Method for use with the
 131    "Internet Printing Protocol (IPP): Event Notifications and
 132    Subscriptions" specification [RFC3995].  This IPPGET Delivery Method
 133    is REQUIRED for all clients and Printers that support [RFC3995].  The
 134    Notification Recipient, acting as a client, fetches (pulls) Event
 135    Notifications by using the Get-Notifications operation defined in
 136    this document.  For a description of the base IPP documents, see
 137    section 21 of this document.  For a description of the IPP Event
 138    Notification Model, see [RFC3995].
 139
 140    With this Pull Delivery Method, when an Event occurs, the Printer
 141    saves the Event Notification for a period of time called the Event
 142    Life.  The Notification Recipient fetches (pulls) the Event
 143    Notifications by using the Get-Notifications operation.  This
 144    operation causes the Printer to return all Event Notifications held
 145    for the specified Subscription object(s).  If the Notification
 146    Recipient has selected the Event Wait Mode option to wait for
 147    additional Event Notifications, the Printer MAY continue to return
 148    Event Notifications to the Notification Recipient as asynchronous
 149    Get-Notification responses as Events occur using the transaction
 150    originated by the Notification Recipient.
 151
 152    The Notification Recipient can terminate Event Wait Mode (without
 153    closing the connection) by supplying the "notify-wait" (boolean)
 154    attribute with a 'false' value in a subsequent Get-Notifications
 155    request.  Similarly, the Printer can terminate Event Wait Mode
 156    (without closing the connection) by returning the "notify-get-
 157    interval" (integer) operation attribute in a Get-Notifications
 158    response that tells the Notification Recipient how long to wait
 159    before trying again.
 160
 161 2.  Terminology
 162
 163    This section defines the following terms that are used throughout
 164    this document:
 165
 166
 167
 168
 169
 170 Herriot, et al.             Standards Track                     [Page 3]
 171 \f
 172 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 173
 174
 175 2.1.  Conformance Terminology
 176
 177    Capitalized terms such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
 178    NOT, MAY, NEED NOT, and OPTIONAL have special meaning relating to
 179    conformance as defined in [RFC2119] and [RFC2911], section 12.1.  If
 180    an implementation supports the extension defined in this document,
 181    then these terms apply; otherwise, they do not.  These terms define
 182    conformance to this document only; they do not affect conformance to
 183    other documents, unless it is explicitly stated otherwise.
 184
 185 2.2.  Other terminology
 186
 187    This document uses the same terminology as [RFC2911], including
 188    "client", "Printer", "Job", "attribute", "attribute value",
 189    "keyword", "operation", "request", "response", and "support", with
 190    the same meanings.  This document also uses terminology defined in
 191    [RFC3995], such as "Subscription (object)", "Notification Recipient",
 192    "Event", "Event Notification", "Compound Event Notification", "Event
 193    Life", and "Event Notification Attribute Group", with the same
 194    meanings.  In addition, this document defines the following terms for
 195    use in this document:
 196
 197    Event Wait Mode: The mode requested by a Notification Recipient
 198        client in its Get-Notifications Request and granted by a Printer
 199        to keep the connection open while the Printer sends subsequent
 200        Get-Notification operation responses to the Notification
 201        Recipient in the form of Event Notifications as they occur.
 202
 203 3.  Model and Operation
 204
 205    In a Subscription Creation Operation, when the "notify-pull-method"
 206    attribute is present and has the "ippget" keyword value, the client
 207    is requesting that the Printer use the "ippget" Pull Delivery Method
 208    for the Event Notifications associated with the new Subscription
 209    Object.
 210
 211    When an Event occurs, the Printer MUST generate an Event Notification
 212    and MUST assign it the Event Life.  The Printer MUST hold an Event
 213    Notification for its assigned Event Life.
 214
 215    When a Notification Recipient wants to receive Event Notifications
 216    for a Subscription object, it performs the Get-Notifications
 217    operation supplying the Subscription object's subscription-id, which
 218    causes the Printer to return all un-expired Event Notifications held
 219    for that Subscription object.  If the Notification Recipient has
 220    selected the Event Wait Mode option to wait for additional Event
 221    Notifications, the response to the Get-Notifications request
 222    continues indefinitely as the Printer continues to send Event
 223
 224
 225
 226 Herriot, et al.             Standards Track                     [Page 4]
 227 \f
 228 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 229
 230
 231    Notifications in the response as Events occur for that Subscription
 232    object.
 233
 234    When the Notification Recipient requests Event Notifications for
 235    Per-Job Subscription Objects, the Notification Recipient typically
 236    performs the Get-Notifications operation within a second of
 237    performing the Subscription Creation operation.  Because the Printer
 238    MUST save Event Notifications for at least 15 seconds (see section
 239    8.1), the Notification Recipient is unlikely to miss any Event
 240    Notifications that occur between the Subscription Creation and the
 241    Get-Notifications operation.
 242
 243    The 'ippget' Delivery Method is designed primarily for (1) a client
 244    that wants to get Events (from the job's Per-Job Subscription object)
 245    for a job that it has submitted and (2) a privileged client that
 246    wants to get all job or printer Events from a Per-Printer
 247    Subscription object.
 248
 249 4.  General Information
 250
 251    If a Printer supports this Delivery Method, the following are its
 252    characteristics.
 253
 254               Table 1.  Information about the Delivery Method
 255
 256    Document Method Conformance Requirement    Delivery Method
 257    Realization
 258
 259    1.  What is the URL scheme name for the     'ippget' keyword method
 260        Push Delivery Method, or the keyword     name
 261        method name for the Pull Delivery
 262        Method?
 263
 264    2.  Is the Delivery Method REQUIRED,        REQUIRED
 265        RECOMMENDED, or OPTIONAL for an IPP
 266        Printer to support?
 267
 268    3.  What transport and delivery protocols   IPP with one new
 269        does the Printer use to deliver the     operation.
 270        Event Notification Content; i.e.,
 271        what is the entire network stack?
 272
 273    4.  Can several Event Notifications be      Yes.
 274        combined into a Compound Event
 275        Notification?
 276
 277
 278
 279
 280
 281
 282 Herriot, et al.             Standards Track                     [Page 5]
 283 \f
 284 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 285
 286
 287    5.  Is the Delivery Method initiated by     This Delivery Method is
 288        the Notification Recipient (pull),      a pull method with
 289        or by the Printer (push)?               aspects of a push
 290                                                method, though the
 291                                                Printer does not
 292                                                initiate the operation.
 293
 294    6.  Is the Event Notification content       Machine Consumable.
 295        Machine Consumable or Human
 296        Consumable?
 297
 298    7.  What section in this document answers   Section 5.
 299        the following questions? For a Machine
 300        Consumable Event Notification, what is
 301        the representation and encoding of
 302        values defined in section 9.1 of
 303        [RFC3995], and what are the
 304        conformance requirements thereof? For
 305        a Human Consumable Event Notification,
 306        what is the representation and
 307        encoding of pieces of information
 308        defined in section 9.2 of
 309        [RFC3995], and the conformance
 310        requirements thereof?
 311
 312    8.  What are the latency and reliability    Same as IPP and the
 313        of the transport and delivery           underlying HTTP
 314        protocol?                               transport.
 315
 316    9.  What are the security aspects of the    Same as IPP and the
 317        transport and delivery protocol;        underlying HTTP
 318        e.g., how it is handled in              transport and in the
 319        firewalls?                              same direction, so no
 320                                                new firewall
 321                                                considerations.
 322
 323    10. What are the content length             None.
 324        restrictions?
 325
 326    11. What are the additional values or       None.
 327        pieces of information that a Printer
 328        sends in an Event Notification content
 329        and the conformance requirements
 330        thereof?
 331
 332
 333
 334
 335
 336
 337
 338 Herriot, et al.             Standards Track                     [Page 6]
 339 \f
 340 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 341
 342
 343    12. What are the additional Subscription    None.
 344        Template and/or Subscription
 345        Description attributes and the
 346        conformance requirements thereof?
 347
 348    13. What are the additional Printer         "ipp-event-life"
 349        Description attributes and the          (integer (15: MAX))
 350        conformance requirements thereof?
 351
 352 5.  Get-Notifications Operation
 353
 354    This operation is issued by a client acting in the role of a
 355    Notification Recipient requesting the Printer to return all Event
 356    Notifications held for the identified Subscription object(s).
 357
 358    A Printer MUST support this operation, MUST accept the request in any
 359    state (see [RFC2911] "printer-state" and "printer-state-reasons"
 360    attributes), and MUST remain in the same state with the same
 361    "printer-state-reasons" values.
 362
 363    When a Printer performs this operation, it MUST return all and only
 364    those Event Notifications
 365
 366    1.  whose associated Subscription Object's "notify-subscription-id"
 367        Subscription Description attribute equals one of the values of
 368        the "notify-subscription-ids" (1setOf integer(1:MAX)) operation
 369        attribute AND
 370
 371    2.  whose associated Subscription Object contains the "notify-pull-
 372        method" attribute and it has the 'ippget' keyword value, AND
 373
 374    3.  whose "notify-sequence-number" is equal to or greater than the
 375        corresponding value of the "notify-sequence-numbers" (1setOf
 376        integer(1:MAX)) operation attribute if supplied AND
 377
 378    4.  whose Event Life has not yet expired AND
 379
 380    5.  where the Notification Recipient client has read-access rights to
 381        the identified Subscription Object (see Access Rights paragraph
 382        below).
 383
 384    The Notification Recipient client MUST either (a) request Event Wait
 385    Mode by supplying the "notify-wait" operation attribute with a 'true'
 386    value or (b) suppress Event Wait Mode by omitting the "notify-wait"
 387    operation attribute or by supplying it with a 'false' value.  To
 388    terminate Event Wait Mode subsequently, the Notification Recipient
 389    client MUST close the connection.  To terminate Event Wait Mode, the
 390    Printer MUST either (a) return the "notify-get-interval" operation
 391
 392
 393
 394 Herriot, et al.             Standards Track                     [Page 7]
 395 \f
 396 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 397
 398
 399    attribute in a Get-Notifications response (RECOMMENDED behavior) or
 400    (b) close the connection.  The "notify-get-interval" operation
 401    attributes tell the Notification Recipient how long to wait before
 402    trying a subsequent Get-Notifications request.
 403
 404    Access Rights: The authenticated user (see [RFC2911], section 8.3)
 405    performing this operation MUST be (1) the owner of each Subscription
 406    Object identified by the "notify-subscription-ids" operation
 407    attribute (see section 5.1.1), (2) an operator or administrator of
 408    the Printer (see [RFC2911], sections 1 and 8.5), or (3) otherwise
 409    authorized by the Printer's administrator-configured security policy
 410    to request Event Notifications from the target Subscription
 411    Object(s).  Otherwise, the IPP Printer MUST reject the operation and
 412    return: 'client-error-forbidden', 'client-error-not-authenticated',
 413    or 'client-error-not-authorized' status code, as appropriate.
 414    Furthermore, the Printer's security policy MAY limit the attributes
 415    returned by the Get-Notifications operation, in a manner similar to
 416    that of the Get-Job-Attributes operation (see [RFC2911], end of
 417    section 3.3.4.2).
 418
 419 5.1.  Get-Notifications Request
 420
 421    The following groups of attributes are part of the Get-Notifications
 422    Request:
 423
 424    Group 1: Operation Attributes
 425
 426       Natural Language and Character Set:
 427          The "attributes-charset" and "attributes-natural-language"
 428          attributes, as described in [RFC2911], section 3.1.4.1.
 429
 430       Target:
 431          The "printer-uri" (uri) operation attribute that is the target
 432          for this operation as described in [RFC2911], section 3.1.5.
 433
 434       Requesting User Name:
 435          The "requesting-user-name" (name(MAX)) attribute SHOULD be
 436          supplied by the client as described in [RFC2911], section 8.3.
 437
 438 5.1.1.  notify-subscription-ids (1setOf integer(1:MAX))
 439
 440    This attribute identifies one or more Subscription objects for which
 441    Events are requested.  The client MUST supply this attribute with at
 442    least one value.  The Printer object MUST support this attribute with
 443    multiple values.
 444
 445    If no Subscription Object exists with the supplied identifier, or if
 446    the identified Subscription Object does not contain the "notify-
 447
 448
 449
 450 Herriot, et al.             Standards Track                     [Page 8]
 451 \f
 452 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 453
 454
 455    pull-method" attribute with the 'ippget' keyword value, the Printer
 456    MUST return the 'client-error-not-found' status code.
 457
 458          Note:  The name of both the "notify-subscription-ids" and
 459          "notify-sequence-numbers" end in 's', as they are multi-valued.
 460          However, there are other occurrences of these attribute names
 461          without the 's' that are single valued.
 462
 463 5.1.2.  notify-sequence-numbers (1setOf integer(1:MAX))
 464
 465    This attribute specifies one or more of the lowest Event Notification
 466    sequence number values for the Subscription objects identified by the
 467    corresponding values of the "notify-subscription-ids" operation
 468    attribute.  The Notification Recipient SHOULD supply this attribute,
 469    and the number of values SHOULD be the same as that of the "notify-
 470    subscriptions-ids" attribute.  The Printer MUST support this
 471    attribute with multiple values.
 472
 473    The Printer MUST NOT return Notification Events with lower sequence
 474    numbers for the corresponding Subscription object.  Therefore, by
 475    supplying the proper values for this attribute the Notification
 476    Recipient can prevent getting the same Event Notifications from a
 477    Subscription object that were returned on a previous Get-
 478    Notifications request.  The Notification Recipient SHOULD remember
 479    the highest "notify-sequence-number" value returned for each
 480    Subscription object requested and SHOULD pass that value for each
 481    requested Subscription object on the next Get-Notifications request.
 482
 483    If the Notification Recipient supplies fewer values for this
 484    attribute (including omitting this attribute) than it does for the
 485    "notify-subscription-ids" operation attribute, the Printer assumes a
 486    '1' value for each missing value.  A value of '1' causes the Printer
 487    to return any un-expired Event Notification for that Subscription
 488    object, as '1' is the lowest possible sequence number.  If the
 489    Notification Recipient supplies more values for this attribute than
 490    the number of values for the "notify-subscription-ids" operation
 491    attribute, the Printer ignores the extra values.
 492
 493    Note: If a Notification Recipient performs two consecutive Get-
 494    Notifications operations with the same value for "notify-sequence-
 495    number" (or omits the attribute), the time stamp value of the first
 496    Event Notification in the second Get-Notifications Response may be
 497    less than that of the time stamp of the last Event Notification in
 498    the first Get-Notification Response.  This happens because the
 499    Printer sends all unexpired Event Notifications with an equal or
 500    higher sequence number according to the ordering specified in
 501    [RFC3995], and some Event Notifications from the first Get-
 502
 503
 504
 505
 506 Herriot, et al.             Standards Track                     [Page 9]
 507 \f
 508 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 509
 510
 511    Notifications operation may not have expired by the time the second
 512    Get-Notifications operation occurs.
 513
 514 5.1.3.  notify-wait (boolean)
 515
 516    This value indicates whether the Notification Recipient wants Event
 517    Wait Mode.  The client MAY supply this attribute.  The Printer object
 518    MUST support both values of this attribute.
 519
 520    If the client supplies the 'false' value or omits this attribute, the
 521    client is not requesting Event Wait Mode.  If the value is 'true',
 522    the client is requesting Event Wait Mode.  See the beginning of
 523    section 5.2 for the rules for Event Wait Mode.
 524
 525 5.2.  Get-Notifications Response
 526
 527    The Printer has the following options for responding to a Get-
 528    Notifications Request:
 529
 530    1.  The Printer can reject the request and return the 'server-error-
 531        busy' status code if the Printer is too busy to accept this
 532        operation at this time.  In this case, the Printer MUST return
 533        the "get-notify-interval" operation attribute to indicate when
 534        the client SHOULD try again.
 535
 536    2.  If the Notification Recipient did not request Event Wait Mode
 537        ("notify-wait-mode" = 'false' or omitted), the Printer MUST
 538        immediately return whatever Event Notifications it currently
 539        holds in the requested Subscription object(s) and MUST return the
 540        "notify-get-interval" operation attribute with the number of
 541        seconds from now, at which the Notification Recipient SHOULD
 542        repeat the Get-Notifications Request to get future Event
 543        Notifications.
 544
 545    3.  If the Notification Recipient requested Event Wait Mode
 546        ("notify-wait-mode" = 'true'), the Printer MUST immediately
 547        return whatever Event Notifications it currently holds in the
 548        requested Subscription object(s) and MUST continue to return
 549        Event Notifications as they occur until all the requested
 550        Subscription Objects are canceled.  A Subscription Object is
 551        canceled either via the Cancel-Subscription operation or by the
 552        Printer (e.g., the Subscription Object is canceled when the
 553        associated Job completes and is no longer in the Job Retention or
 554        Job History phase; see the "ippget-event-life (integer(15:MAX))"
 555        attribute discussion in section 8.1).
 556
 557        However, the Printer MAY decide to terminate Event Wait Mode at
 558        any time, including in the first response.  In this case, the
 559
 560
 561
 562 Herriot, et al.             Standards Track                    [Page 10]
 563 \f
 564 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 565
 566
 567        Printer MUST return the "notify-get-interval" operation
 568        attribute.  This attribute indicates that the Printer wishes to
 569        leave Event Wait Mode and the number of seconds in the future
 570        that the Notification Recipient SHOULD try the Get-Notifications
 571        operation again.  The Notification Recipient MUST accept this
 572        response and MUST disconnect.  If the Notification Recipient does
 573        not disconnect, the Printer SHOULD do so.
 574
 575    From the Notification Recipient's view, the response appears as an
 576    initial burst of data, which includes the Operation Attributes Group
 577    and one Event Notification Attributes Group per Event Notification
 578    that the Printer is holding.  After the initial burst of data, if the
 579    Notification Recipient has selected the Event Wait Mode option to
 580    wait for additional Event Notifications, the Notification Recipient
 581    receives occasional Event Notification Attribute Groups.  Proxy
 582    servers may delay some Event Notifications or cause time-outs to
 583    occur.  The client MUST be prepared to perform the Get-Notifications
 584    operation again when time-outs occur.
 585
 586    Each attribute is encoded by using the IPP rules for encoding
 587    attributes [RFC2910] and MAY be encoded in any order.  Note:  the
 588    Get-Jobs response in [RFC2911] acts as a model for encoding multiple
 589    groups of attributes.  See section 11 for the encoding and transport
 590    rules.
 591
 592    The following groups of attributes are part of the Get-Notifications
 593    Response:
 594
 595    Group 1: Operation Attributes
 596
 597       Status Message:  In addition to the REQUIRED status code returned
 598          in every response, the response OPTIONALLY includes a "status-
 599          message" (text(255)) and/or a "detailed-status-message"
 600          (text(MAX)) operation attribute, as described in [RFC2911],
 601          sections 13 and 3.1.6.
 602
 603          The Printer can return any status codes defined in [RFC2911].
 604          If the status code is not 'successful-xxx', the Printer MUST
 605          NOT return any Event Notification Attribute groups.  The
 606          following are descriptions of the important status codes:
 607
 608             successful-ok: The response contains all Event Notification
 609                associated with the specified subscription-ids that had
 610                been supplied in the "notify-subscription-ids" operation
 611                attribute in the request.  If the requested Subscription
 612                Objects have no associated Event Notification, the
 613                response MUST contain zero Event Notifications.
 614
 615
 616
 617
 618 Herriot, et al.             Standards Track                    [Page 11]
 619 \f
 620 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 621
 622
 623             successful-ok-events-complete:  Indicates when this return
 624                is the last return for all Subscription objects that
 625                match the request, whether or not Event Notifications are
 626                returned.  This condition occurs for Event Wait Mode with
 627                Notification Recipients waiting for responses when (1)
 628                the Subscription Object is canceled with a Cancel-
 629                Subscription operation, (2) the Subscription Object is
 630                deleted, when the Per-Printer Subscription lease time
 631                expires, or (3) the 'job-completed' event occurs for a
 632                Per-Job Subscription.  This condition also occurs for a
 633                Get-Notifications request that a Notification Recipient
 634                makes after the job completes, but before the Event Life
 635                expires.  See section 10.1.
 636             client-error-not-found: The Printer has no Subscription
 637                Objects whose "notify-subscription-id" attribute equals
 638                any of the values of the "notify-subscription-ids"
 639                operation attribute supplied, or the identified
 640                Subscription Object does not contain the "notify-pull-
 641                method" attribute with the 'ippget' keyword value.
 642             server-error-busy: The Printer is too busy to accept this
 643                operation.  The Printer SHOULD return the "notify-get-
 644                interval" operation attribute in the Operation Attributes
 645                of the response; then the Notification Recipient SHOULD
 646                wait for the number of seconds specified by the "notify-
 647                get-interval" operation attribute before performing this
 648                operation again.  If the "notify-get-interval" Operation
 649                Attribute is not present, the Notification Recipient
 650                SHOULD use the normal network back-off algorithms to
 651                determine when to perform this operation again.
 652
 653       Natural Language and Character Set:
 654          The "attributes-charset" and "attributes-natural-language"
 655          attributes, as described in [RFC2911], section 3.1.4.2.
 656
 657          The Printer MUST use the values of "notify-charset" and
 658          "notify-natural-language", respectively, from one Subscription
 659          Object associated with the Event Notifications in this
 660          response.
 661
 662          Normally, there is only one matched Subscription Object, or the
 663          value of the "notify-charset" and "notify-natural-language"
 664          attributes is the same in all Subscription Objects.  If not,
 665          the Printer MUST pick one Subscription Object from which to
 666          obtain the value of these attributes.  The algorithm for
 667          picking the Subscription Object is implementation dependent.
 668          The choice of natural language is not critical, because 'text'
 669          and 'name' values can override the "attributes-natural-
 670          language" operation attribute.  The Printer's choice of charset
 671
 672
 673
 674 Herriot, et al.             Standards Track                    [Page 12]
 675 \f
 676 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 677
 678
 679          is critical because a bad choice may leave it unable to send
 680          some 'text' and 'name' values accurately.
 681
 682 5.2.1.  notify-get-interval (integer(0:MAX))
 683
 684    The value of this operation attribute is the number of seconds that
 685    the Notification Recipient SHOULD wait before trying the Get-
 686    Notifications operation again.  The Printer MUST return this
 687    operation attribute if (1) it is too busy to return events, (2) the
 688    Notification Recipient client did not request Event Wait Mode, or (3)
 689    the Printer is terminating Event Wait Mode.  The client MUST accept
 690    this attribute and SHOULD reissue the Get-Notifications operation
 691    (with or without "notify-wait" = 'true') at the indicated number of
 692    seconds in the future in order to get more Event Notifications  This
 693    value is intended to help the client be a good network citizen.
 694
 695    The value of this attribute MUST be at least as large as that of the
 696    Printer's "ippget-event-life" Printer Description attribute (see
 697    section 8.1).  The Printer MAY return a value that is larger than
 698    that of the "ippget-event-life" Printer Description attribute
 699    provided that the Printer increases the Event Life for this
 700    Subscription object so that Notification Recipients taking account of
 701    the larger value and polling with a longer interval will not miss
 702    events.  Note:  Implementing such an algorithm requires some hidden
 703    attributes in the Subscription object that are IMPLEMENTATION
 704    DEPENDENT.
 705
 706    If the Printer wants to remain in Event Wait Mode, then the Printer
 707    MUST NOT return this attribute in the response.
 708
 709    Here is a complete table of combinations of "notify-wait", "status-
 710    code", "notify-get-interval", and Event Notification Attributes
 711    Groups for Get-Notification initial (Wait and No Wait) Responses and
 712    subsequent Event Wait Mode Responses (which may stay in Event Wait
 713    Mode or may request the Notification Recipient to leave Event Wait
 714    Mode):
 715
 716        Table 2.  Combinations of "notify-wait", "status-code", and
 717                            "notify-get-interval"
 718
 719          Client sends:  Printer returns:  Printer       Event
 720                                           returns:      Notification
 721          "notify-wait"  "status-code"     "notify-get-  Attribute
 722                                           interval"     Groups
 723
 724          1.  'false'*   'successful-ok'   MUST return N maybe
 725          2.  'false'*   'not-found'       MUST NOT      MUST NOT
 726          3.  'false'*   'busy'            MUST return N MUST NOT
 727
 728
 729
 730 Herriot, et al.             Standards Track                    [Page 13]
 731 \f
 732 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 733
 734
 735          4.  'false'*   'events-          MUST NOT      'job-
 736                         complete'                        completed'
 737          5.  'true'     'successful-ok'   MUST NOT      MUST
 738          6.  'true'     'successful-ok'   MUST return N maybe
 739          7.  'true'     'not-found'       MUST NOT      MUST NOT
 740          8.  'true'     'busy'            MUST return N MUST NOT
 741          9.  'true'     'events-          MUST NOT      'job-
 742                         complete'                        completed' or
 743                                                          maybe other
 744          * 'false' or client omits the "notify-wait" attribute.
 745
 746          Explanation:
 747
 748          1-4:  Client does not request Event Wait Mode.
 749          5-9:  Client requests Event Wait Mode.
 750          2,7:  Subscription object not found, or was canceled earlier;
 751                client should NOT try again.
 752          3,8:  Server busy, tells client to try later; client should try
 753                again in N seconds.
 754          4:    Client polled after job completed, but before Event Life
 755                expired, and got the 'job-completed' event, so the client
 756                shouldn't bother trying again; client should NOT try
 757                again later.
 758          5:    Printer returns one or more Event Notifications and is OK
 759                to stay in Event Wait Mode; the client waits for more
 760                Event Notifications to be returned.
 761          6:    Printer wants to leave Event Wait mode.  Can happen on
 762                the first response (with or without Event Notifications)
 763                or happen on a subsequent response with or without Event
 764                Notifications; the client SHOULD try again in N seconds.
 765          9:    Either (1) the printer returns 'job-completed' event, or
 766                (2) the Subscription Object was canceled by either a
 767                Cancel-Job or a Per-Printer Subscription expired without
 768                being renewed.  For case (1), at least one Event
 769                Notification MUST be returned; for case (2), it is
 770                unlikely that any Event Notifications are returned, and
 771                the client should NOT try again.
 772
 773 5.2.2.  printer-up-time (integer(1:MAX))
 774
 775    The value of this attribute is the Printer's "printer-up-time"
 776    attribute at the time when the Printer sends this response.  The
 777    Printer MUST return this attribute.  Because each Event Notification
 778    also contains the value of this attribute when the event occurred,
 779    the value of this attribute lets a Notification Recipient know when
 780    each Event Notification occurred relative to the time of this
 781    response.
 782
 783
 784
 785
 786 Herriot, et al.             Standards Track                    [Page 14]
 787 \f
 788 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 789
 790
 791    Group 2: Unsupported Attributes
 792          See [RFC2911], section 3.1.7, for details on returning
 793          Unsupported Attributes.
 794
 795    Group 3 through N: Event Notification Attributes
 796          The Printer responds with one Event Notification Attributes
 797          Group per matched Event Notification.  The entire response is
 798          considered a single Compound Event Notification (see
 799          [RFC3995]).  The matched Event Notifications are all un-expired
 800          Event Notifications associated with the matched Subscription
 801          Objects and MUST follow the "Event Notification Ordering"
 802          requirements for Event Notifications within a Compound Event
 803          Notification specified in [RFC3995] section 9.  In other words,
 804          the Printer MUST order these Event Notification groups in
 805          ascending time stamp (and sequence number) order for a
 806          Subscription object.  If Event Notifications for multiple
 807          Subscription objects are being returned, the Notification
 808          Events for the next Subscription object follow in ascending
 809          time stamp order, etc.
 810
 811          Each Event Notification Group MUST contain all of attributes
 812          specified in section 9.1 ("Content of Machine Consumable Event
 813          Notifications") of [RFC3995], with exceptions denoted by
 814          asterisks in the tables below.
 815
 816          The tables below are identical to those in section 9.1
 817          ("Content of Machine Consumable Event Notifications") of
 818          [RFC3995], except that each cell in the "Sends" column is a
 819          "MUST".
 820
 821          If more than one Event Notification is being returned and the
 822          status of each is not the same, then the Printer MUST return a
 823          "notify-status-code" attribute in each Event Notification
 824          Attributes group to indicate the differing status values.
 825
 826          For an Event Notification for all Events, the Printer includes
 827          the attributes shown in Table 3.
 828
 829                Table 3.  Attributes in Event Notification Content
 830
 831    Source Value                              Sends     Source Object
 832
 833    notify-subscription-id (integer(1:MAX))   MUST      Subscription
 834    notify-printer-uri (uri)                  MUST      Subscription
 835    notify-subscribed-event (type2 keyword)   MUST      Event
 836                                                         Notification
 837    printer-up-time (integer(1:MAX)) *        MUST      Printer
 838    printer-current-time (dateTime)           MUST **   Printer
 839
 840
 841
 842 Herriot, et al.             Standards Track                    [Page 15]
 843 \f
 844 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 845
 846
 847    notify-sequence-number (integer (0:MAX))  MUST      Subscription
 848    notify-charset (charset)                  MUST      Subscription
 849    notify-natural-language (naturalLanguage) MUST      Subscription
 850    notify-user-data (octetString(63))        MUST ***  Subscription
 851    notify-text (text)                        MUST      Event
 852                                                         Notification
 853    attributes from the "notify-attributes"   MUST **** Printer
 854    attribute
 855    attributes from the "notify-attributes"   MUST **** Job
 856    attribute
 857    attributes from the "notify-attributes"   MUST **** Subscription
 858    attribute
 859
 860       * As specified in [RFC3995] section 9, the value of the
 861       "printer-up-time" attribute sent in each Event Notification
 862       MUST be the time at which the Event occurred, not the time at
 863       which the Event Notification was sent.
 864
 865       ** The Printer MUST send the "printer-current-time" attribute
 866       if and only if it supports the "printer-current-time" attribute
 867       on the Printer object.
 868
 869       *** If the associated Subscription Object does not contain a
 870       "notify-user-data" attribute, the Printer MUST send an
 871       octet-string of length 0.
 872
 873       **** If the "notify-attributes" attribute is present on the
 874       Subscription Object, the Printer MUST send all attributes
 875       specified by the "notify-attributes" attribute.  Note:  If the
 876       Printer doesn't support the "notify-attributes" attribute, it
 877       is not present on the associated Subscription Object.
 878
 879       For Event Notifications for Job Events, the Printer includes
 880       the additional attributes shown in Table 4.
 881
 882      Table 4.  Additional Attributes in Event Notification Content for
 883                                 Job Events
 884
 885    Source Value                                  Sends  Source Object
 886
 887    job-id (integer(1:MAX))                       MUST   Job
 888    job-state (type1 enum)                        MUST   Job
 889    job-state-reasons (1setOf type2 keyword)      MUST   Job
 890    job-impressions-completed (integer(0:MAX))    MUST * Job
 891
 892
 893
 894
 895
 896
 897
 898 Herriot, et al.             Standards Track                    [Page 16]
 899 \f
 900 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 901
 902
 903       *  The Printer MUST send the "job-impressions-completed" attribute
 904       in an Event Notification only for the combinations of Events and
 905       Subscribed Events shown in Table 5.
 906
 907         Table 5.  Combinations of Events and Subscribed Events for
 908                        "job-impressions-completed"
 909
 910    Job Event                 Subscribed Job Event
 911
 912    'job-progress'            'job-progress'
 913    'job-completed'           'job-completed'
 914    'job-completed'           'job-state-changed'
 915
 916       For Event Notification for Printer Events, the Printer includes
 917       the additional attributes shown in Table 6.
 918
 919      Table 6.  Additional Attributes in Event Notification Content for
 920                               Printer Events
 921
 922    Source Value                                  Sends   Source
 923    Object
 924
 925    printer-state (type1 enum)                    MUST    Printer
 926    printer-state-reasons (1setOf type2 keyword)  MUST    Printer
 927    printer-is-accepting-jobs (boolean)           MUST    Printer
 928
 929 6.  Additional Information about Subscription Template Attributes
 930
 931    The 'ippget' Delivery Method does not define any addition
 932    Subscription Template attributes and has the conformance requirements
 933    for Subscription Template attributes defined in [RFC3995].  This
 934    section defines additional information about Subscription Template
 935    attributes defined in [RFC3995].
 936
 937 6.1.  notify-pull-method (type2 keyword)
 938
 939    This Subscription Template attribute identifies the Pull Delivery
 940    Method to be used for the Subscription Object (see [RFC3995]).  To
 941    support the 'ippget' Pull Delivery Method defined in this document,
 942    the Printer MUST support this attribute with the following keyword
 943    value:
 944
 945      'ippget':  Indicates that the 'ippget' Pull Delivery Method is to
 946        be used for this Subscription Object.
 947
 948
 949
 950
 951
 952
 953
 954 Herriot, et al.             Standards Track                    [Page 17]
 955 \f
 956 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
 957
 958
 959 7.  Subscription Description Attributes
 960
 961    The 'ippget' Delivery Method has the conformance requirements for
 962    Subscription Description attributes defined in [RFC3995].  The
 963    'ippget' Delivery Method does not define any addition Subscription
 964    Description attributes.
 965
 966 8.  Additional Printer Description Attributes
 967
 968    This section defines additional Printer Description attributes for
 969    use with the 'ippget' Delivery Method.
 970
 971 8.1.  ippget-event-life (integer(15:MAX))
 972
 973    This Printer Description attribute specifies the Event Life value
 974    that the Printer assigns to each Event; i.e., the number of seconds
 975    after an Event occurs during which a Printer will return that Event
 976    in an Event Notification in a Get-Notifications response.  After the
 977    Event Life expires for the Event, the Printer MAY no longer return an
 978    Event Notification for that Event in a Get-Notifications response.
 979
 980    The Printer MUST support this attribute if it supports the 'ippget'
 981    Delivery Method.  The value MUST be 15 or more (at least 15 seconds),
 982    and 60 (seconds) is the RECOMMENDED value to align with the PWG Job
 983    Monitoring MIB [RFC2707] jmGeneralJobPersistence and
 984    jmGeneralAttributePersistence objects.
 985
 986    For example, assume the following:
 987
 988    1.  A client performs a Job Creation operation that creates a
 989        Subscription Object associated with the 'ippget' Delivery Method;
 990
 991    2.  An Event associated with the new Job occurs immediately after the
 992        Subscription Object is created;
 993
 994    3.  the same client or some other client performs a Get-Notifications
 995        operation so that the client is connected N seconds after the Job
 996        Creation operation.
 997
 998    Then, if N is less than the value of this attribute, the client(s)
 999    performing the Get-Notifications operations can expect not to miss
1000    any Event-Notifications, barring some unforeseen lack of memory space
1001    in the Printer.  Note:  The client MUST initiate the Get-
1002    Notifications at a time that is sufficiently less that N seconds to
1003    account for network latency so that it is connected to the Printer
1004    before N seconds elapses.
1005
1006
1007
1008
1009
1010 Herriot, et al.             Standards Track                    [Page 18]
1011 \f
1012 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1013
1014
1015    If a Printer supports the 'ippget' Delivery Method, it MUST keep
1016    'completed', 'canceled', or 'aborted' Job objects in the Job
1017    Retention and/or Job History phases for at least as long as this
1018    attribute's value.  The Printer MAY retain jobs longer that this
1019    value.  See [RFC2911], section 4.3.7.1, and the discussion in
1020    [RFC3995] (regarding the 'job-completed' event).  The latter explains
1021    that a Notification Recipient can query the Job after receiving a
1022    'job-completed' Event Notification in order to find out other
1023    information about the job that is 'completed', 'aborted', or
1024    'canceled'.  However, this attribute has no effect on the Cancel-
1025    Subscription operation, which deletes the Subscription object
1026    immediately whether or not it contains the "notify-pull-method"
1027    attribute with the 'ippget' keyword value.  Immediately thereafter,
1028    subsequent Get-Notifications Responses MUST NOT contain Event
1029    Notifications associated with the canceled Subscription object.
1030
1031 9.  New Values for Existing Printer Description Attributes
1032
1033    This section defines additional values for existing Printer
1034    Description attributes as defined in [RFC3995].
1035
1036 9.1.  notify-pull-method-supported (1setOf type2 keyword)
1037
1038    The following keyword value for the "notify-pull-method-supported"
1039    attribute is added in order to support the new Delivery Method
1040    defined in this document:
1041
1042       'ippget':   The IPP Notification Pull Delivery Method defined in
1043         this document.
1044
1045 9.2.  operations-supported (1setOf type2 enum)
1046
1047    Table 7 lists the "operation-id" value defined in order to support
1048    the new Get-Notifications operation defined in this document.
1049
1050                     Table 7.  Operation-id Assignments
1051
1052       Value       Operation Name
1053
1054       0x001C      Get-Notifications
1055
1056 10.  New Status Codes
1057
1058    The following status code is defined as an extension for this
1059    Delivery Method and is returned as the status code of the Get-
1060    Notifications operation in Group 1 or Group 3 to N (see section 5.2).
1061
1062
1063
1064
1065
1066 Herriot, et al.             Standards Track                    [Page 19]
1067 \f
1068 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1069
1070
1071 10.1.  successful-ok-events-complete (0x0007)
1072
1073    The Printer MUST return the 'successful-ok-events-complete' status
1074    code to indicate when this Get-Notifications response is the last
1075    response for a Subscription object, whether or not there are Event
1076    Notifications being returned.  This condition occurs for Event Wait
1077    Mode with Notification Recipients waiting for responses when (1) the
1078    Subscription Object is canceled with a Cancel-Subscription operation,
1079    (2) the Subscription object is deleted, when the Per-Printer
1080    Subscription lease time expires, or (3) the 'job-completed' event
1081    occurs for a Per-Job Subscription.  This condition also occurs for a
1082    Get-Notifications request that a Notification Recipient makes after
1083    the job completes, but before the Event Life expires.
1084
1085 11.  Encoding and Transport
1086
1087    This section defines the encoding and transport considerations for
1088    this Delivery Method based on [RFC2910].
1089
1090    The encoding of a Get-Notifications Response is modeled after the
1091    Get-Jobs Response (see [RFC2911]).  In a Get-Notifications Response,
1092    each Event Notification Attributes Group MUST start with an 'event-
1093    notification-attributes-tag' (see the section "Encodings of
1094    Additional Attribute Tags" in [RFC3995]), and end with an 'end-of-
1095    attributes-tag'.  In addition, for Event Wait Mode the multi-
1096    part/related is used to separate each multiple response (in time) to
1097    a single Get-Notifications Request.
1098
1099    The Printer returns Get-Notification Response as follows:
1100
1101    1.  If the Notification Recipient client did not request Event Wait
1102        Mode ("notify-wait" = 'false' or omitted), the Printer ends the
1103        response with an 'end-of-attributes-tag' (see [RFC2911], Get-Jobs
1104        encoding), as with any operation response.
1105
1106    2.  If the Notification Recipient client requests Event Wait Mode
1107        ("notify-wait" = 'true') and the Printer wishes to honor the
1108        request, the Printer MUST return the response as an
1109        application/ipp part inside a multi-part/related MIME media type.
1110        When one or more additional Events occur, the Printer returns
1111        each as an additional Event Notification Group using a separate
1112        application/ipp part under the multi-part/related type.
1113
1114    3.  If the client requested Event Wait Mode ("notify-wait" = 'true'),
1115        but the Printer does not wish to honor the request in the initial
1116        response and wants the client explicitly polled for Event
1117        Notifications, the Printer MUST return the "notify-get-interval"
1118        operation attribute (see section 5.2.1).  The Printer returns the
1119
1120
1121
1122 Herriot, et al.             Standards Track                    [Page 20]
1123 \f
1124 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1125
1126
1127        response as an application/ipp part that MAY be inside an multi-
1128        part/related type.  The client MUST accept this response and
1129        reissue the Get-Notifications request in the future indicated by
1130        the value of the "notify-get-interval" attribute value.
1131
1132    4.  If the client requested Event Wait Mode ("notify-wait" = 'true'),
1133        and the Printer initially honored the request but later wishes to
1134        leave Event Wait Mode,  the Printer MUST return the "notify-get-
1135        interval" operation attribute (see section 5.2.1).  The Printer
1136        returns the response as an application/ipp part that MUST be
1137        inside an multi-part/related type.
1138
1139    NOTE:  If a Notification Recipient fails to receive a response, it
1140    can ask the Printer for the same Event Notifications again.  The
1141    Notification Recipient will receive the same Event Notifications that
1142    it should have received the first time, except for those Event
1143    Notifications that have expired in the meantime.
1144
1145    The Printer MAY chunk the responses, but this has no significance to
1146    the IPP semantics.
1147
1148    This notification delivery method uses the IPP transport and encoding
1149    [RFC2910] for the Get-Notifications operation with the following
1150    extension, allocated in [RFC3995]:
1151
1152           Table 8.  The "event-notification-attributes-tag" Value
1153
1154       Tag Value (Hex)   Meaning
1155
1156       0x07              "event-notification-attributes-tag"
1157
1158 12.  Conformance Requirements
1159
1160    This section lists the conformance requirements for clients and
1161    Printers.
1162
1163 12.1.  Conformance for IPP Printers
1164
1165    It is OPTIONAL for a Printer to support IPP Notifications as defined
1166    in [RFC3995].  However, if a Printer supports IPP Notifications, the
1167    Printer MUST support the 'ippget' Delivery Method, as defined in this
1168    document, as one of its Delivery Methods.  IPP Printers that conform
1169    to this specification
1170
1171    1.  MUST meet the conformance requirements defined in [RFC3995] for a
1172        Pull Delivery Method;
1173
1174
1175
1176
1177
1178 Herriot, et al.             Standards Track                    [Page 21]
1179 \f
1180 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1181
1182
1183    2.  MUST support the Get-Notifications operation defined in section
1184        5, including Event Wait Mode;
1185
1186    3.  MUST support the Subscription Template object attributes, as
1187        defined in section 6;
1188
1189    4.  MUST support the Subscription Description object attributes, as
1190        defined in section 7;
1191
1192    5.  MUST support the "ippget-event-life" Printer Description
1193        attribute defined in section 8.1, including retaining jobs in the
1194        Job Retention and/or Job History phases for at least as long as
1195        the value specified by the Printer's "ippget-event-life";
1196
1197    6.  MUST support the additional values for IPP/1.1 Printer
1198        Description attributes defined in section 9;
1199
1200    7.  MUST support the 'successful-ok-events-complete' status code, as
1201        described in section 10.1;
1202
1203    8.  MUST listen for the IPP Get-Notifications operation requests on
1204        IANA-assigned well-known port 631, unless explicitly configured
1205        by system administrators or site policies;
1206
1207    9.  SHOULD NOT listen for IPP Get-Notifications operation requests on
1208        any other port, unless explicitly configured by system
1209        administrators or site policies; and
1210
1211    10. MUST meet the security conformance requirements stated in section
1212        18.4.
1213
1214 12.2.  Conformance for IPP Clients
1215
1216    It is OPTIONAL for an IPP Client to support IPP Notifications as
1217    defined in [RFC3995].  However, if a client supports IPP
1218    Notifications, the client MUST support the 'ippget' Delivery Method
1219    as defined in this document as one of its Delivery Methods.  IPP
1220    Clients that conform to this specification:
1221
1222    1.  MUST create Subscription Objects by sending Subscription Creation
1223        operation requests containing the "notify-pull-method" attribute
1224        (as opposed to the "notify-recipient-uri" attribute) using the
1225        'ippget' keyword value (see sections 6.1 and 15.2);
1226
1227    2.  MUST send IPP Get-Notifications operation requests (see section
1228        5.1) via the port specified in the associated 'ipp' URL (if
1229        present) or otherwise via IANA-assigned well-known port 631;
1230
1231
1232
1233
1234 Herriot, et al.             Standards Track                    [Page 22]
1235 \f
1236 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1237
1238
1239    3.  MUST convert the associated 'ipp' URLs for use in IPP Get-
1240        Notifications operation to their corresponding 'http' URL forms
1241        for use in the HTTP layer, according to the rules in section 5,
1242        "IPP URL Scheme", in [RFC2910]; and
1243
1244    4.  MUST meet the security conformance requirements stated in section
1245        18.5.
1246
1247 13.  Normative References
1248
1249    [RFC2119]    Bradner, S., "Key words for use in RFCs to Indicate
1250                 Requirement Levels", BCP 14, RFC 2119, March 1997.
1251
1252    [RFC2910]    Herriot, R., Butler, S., Moore, P., Turner, R., and J.
1253                 Wenn, "Internet Printing Protocol/1.1: Encoding and
1254                 Transport", RFC 2910, September 2000.
1255
1256    [RFC2911]    Hastings, T., Herriot, R., deBry, R., Isaacson, S., and
1257                 P. Powell, "Internet Printing Protocol/1.1: Model and
1258                 Semantics", RFC 2911, September 2000.
1259
1260    [RFC3995]   Herriot, R. and T. Hastings, "Internet Printing Protocol
1261                 (IPP): Event Notifications and Subscriptions", RFC 3995,
1262                 March 2005.
1263
1264 14.  Informative References
1265
1266    [RFC2565]    Herriot, R., Butler, S., Moore, P., and R. Turner,
1267                 "Internet Printing Protocol/1.0: Encoding and
1268                 Transport", RFC 2565, April 1999.
1269
1270    [RFC2566]    deBry, R., Hastings, T., Herriot, R., Isaacson, S., and
1271                 P. Powell, "Internet Printing Protocol/1.0: Model and
1272                 Semantics", RFC 2566, April 1999.
1273
1274    [RFC2567]    Wright, F., "Design Goals for an Internet Printing
1275                 Protocol", RFC 2567, April 1999.
1276
1277    [RFC2568]    Zilles, S., "Rationale for the Structure of the Model
1278                 and Protocol for the Internet Printing Protocol", RFC
1279                 2568, April 1999.
1280
1281    [RFC2569]    Herriot, R., Hastings, T., Jacobs, N., and J. Martin,
1282                 "Mapping between LPD and IPP Protocols", RFC 2569, April
1283                 1999.
1284
1285
1286
1287
1288
1289
1290 Herriot, et al.             Standards Track                    [Page 23]
1291 \f
1292 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1293
1294
1295    [RFC2616]    Fielding,  R., Gettys, J., Mogul, J., Frystyk, H.,
1296                 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1297                 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1298
1299    [RFC2707]    Bergman, R., Hastings, T., Isaacson, S., and H. Lewis,
1300                 "Job Monitoring MIB - V1.0", RFC 2707, November 1999.
1301
1302    [RFC3196]    Hastings, T., Manros, C., Zehler, P., Kugler, C., and H.
1303                 Holst, "Internet Printing Protocol/1.1: Implementor's
1304                 Guide", RFC 3196, November 2001.
1305
1306    [RFC3997]    Hastings, T., Ed., deBry, R., and H. Lewis, "Internet
1307                 Printing Protocol (IPP): Requirements for IPP
1308                 Notifications", RFC 3997, March 2005.
1309
1310 15.  IANA Considerations
1311
1312    This section contains the exact information that the IANA has added
1313    to the IPP Registries according to the procedures defined in
1314    [RFC2911], section 6.  These registrations have been published in the
1315    http://www.iana.org/assignments/ipp-registrations registry.
1316
1317 15.1.  Attribute Registrations
1318
1319    The following table lists the attributes defined in this document.
1320    This has been registered according to the procedures in RFC 2911
1321    [RFC2911] section 6.2.
1322
1323    Printer Description attributes:                Reference   Section
1324    -------------------------------                ---------   -------
1325    ippget-event-life (integer(15:MAX))            [RFC3996]   8.1
1326
1327 15.2.  Delivery Method and Additional Keyword Attribute Value
1328        Registrations for Existing Attributes
1329
1330    This section lists additional keyword attribute value registrations
1331    for use with existing attributes defined in other documents.  These
1332    have been registered according to the procedures in [RFC2911],
1333    section 6.1.  According to [RFC3995], section 24.7.3, Pull Delivery
1334    Method registrations are the keyword attribute value registrations
1335    for the "notify-pull-method" and "notify-pull-method-supported"
1336    attributes.
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346 Herriot, et al.             Standards Track                    [Page 24]
1347 \f
1348 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1349
1350
1351    Attribute (attribute syntax)
1352      Values                                       Reference   Section
1353      -----------------------                      ---------   -------
1354    notify-pull-method (type2 keyword)             [RFC3995]   5.3.2
1355    notify-pull-method-supported (1setOf type2 keyword)
1356                                                   [RFC3995]   5.3.2.1
1357      ippget                                       [RFC3996]   9.1
1358
1359 15.3.  Additional Enum Attribute Values
1360
1361    The following table lists the enum attribute values defined in this
1362    document.  These have been registered according to the procedures in
1363    [RFC2911], section 6.1.
1364
1365    Attribute (attribute syntax)
1366      Value    Name                                Reference   Section
1367      ------   -----------------------------       ---------   -------
1368    operations-supported (1setOf type2 enum)       [RFC2911]   4.4.15
1369      0x001C   Get-Notifications                   [RFC3996]   9.2
1370
1371 15.4.  Operation Registrations
1372
1373    The following table lists the operations defined in this document.
1374    This has been registered according to the procedures in RFC 2911
1375    [RFC2911] section 6.4.
1376
1377    Operations:                                    Reference   Section
1378    -----------                                    ---------   -------
1379    Get-Notifications                              [RFC3996]   5
1380
1381 15.5.  Status Code Registrations
1382
1383    The following table lists the status codes defined in this document.
1384    This has been registered according to the procedures in [RFC2911],
1385    section 6.6.
1386
1387    Status codes:                                  Reference  Section
1388    -------------                                  ---------  -------
1389    successful-ok-events-complete (0x0007)         [RFC3996]  10.1
1390
1391 16.  Internationalization Considerations
1392
1393    The IPP Printer MUST localize the "notify-text" attribute as
1394    specified in section 14 of [RFC3995].
1395
1396
1397
1398
1399
1400
1401
1402 Herriot, et al.             Standards Track                    [Page 25]
1403 \f
1404 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1405
1406
1407    In addition, when the client receives the Get-Notifications response,
1408    it is expected to localize the attributes that have the 'keyword'
1409    attribute syntax according to the charset and natural language
1410    requested in the Get-Notifications request.
1411
1412 17.  Security Considerations
1413
1414    The IPP Model and Semantics document [RFC2911, section 8] discusses
1415    high-level security requirements (Client Authentication, Server
1416    Authentication and Operation Privacy).  The IPP Transport and
1417    Encoding document [RFC2910, section 8] discusses the security
1418    requirements for the IPP protocol.  Client Authentication is the
1419    mechanism by which the client proves its identity to the server in a
1420    secure manner.  Server Authentication is the mechanism by which the
1421    server proves its identity to the client in a secure manner.
1422    Operation Privacy is defined as a mechanism for protecting operations
1423    from eavesdropping.
1424
1425    The 'ippget' Delivery Method with its Get-Notifications operations
1426    leverages the security mechanism that are used in IPP/1.1 [RFC2910
1427    and RFC2911] without adding any additional security mechanisms in
1428    order to maintain the same security support as IPP/1.1.
1429
1430    The access control model for the Get-Notifications operation defined
1431    in this document is the same as the access control model for the
1432    Get-Job-Attributes operation (see [RFC2911], section 3.2.6).  The
1433    primary difference is that a Get-Notifications operation is directed
1434    at Subscription Objects rather than at Job objects, and a returned
1435    attribute group contains Event Notification attributes rather than
1436    Job object attributes.
1437
1438 17.1.  Notification Recipient Client Access Rights
1439
1440    The Notification Recipient client MUST have the following access
1441    rights to the Subscription object(s) targeted by the Get-
1442    Notifications operation request:
1443
1444       The authenticated user (see [RFC2911], section 8.3) performing
1445       this operation MUST be (1) the owner of each Subscription Object
1446       identified by the "notify-subscription-ids" operation attribute
1447       (see section 5.1.1), (2) an operator or administrator of the
1448       Printer (see [RFC2911], sections 1 and 8.5), or (3) otherwise
1449       authorized by the Printer's administrator-configured security
1450       policy to request Event Notifications from the target Subscription
1451       Object(s).  Furthermore, the Printer's security policy MAY limit
1452
1453
1454
1455
1456
1457
1458 Herriot, et al.             Standards Track                    [Page 26]
1459 \f
1460 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1461
1462
1463       the attributes returned by the Get-Notifications operation, in a
1464       manner similar to that of the Get-Job-Attributes operation (see
1465       [RFC2911], end of section 3.3.4.2).
1466
1467 17.2.  Printer Security Threats
1468
1469    Because the Get-Notifications operation is sent in the same direction
1470    as are Job Creation operations, usually by the same client, this
1471    Event Notification Delivery Method poses no additional
1472    authentication, authorization, privacy, firewall, or port assignment
1473    issues above those for the IPP Get-Job-Attributes and Get-Printer-
1474    Attributes operations (see [RFC2911], sections 3.2.6 and 3.2.5).
1475
1476 17.3.  Notification Recipient Security Threats
1477
1478    Unwanted Events Notifications (spam):  Unlike Push Event Notification
1479    Delivery Methods in which the IPP Printer initiates the Event
1480    Notification, with the Pull Delivery Method defined in this document,
1481    the Notification Recipient is the client that initiates the Get-
1482    Notifications operation (see section 5).  Therefore, with this method
1483    there is no chance of "spam" notifications.
1484
1485    Note:  When a client stays connected to a Printer by using the Event
1486    Wait Mode (see section 5.1.3) in order to receive Event Notifications
1487    as they occur, it can close down the IPP connection at any time and
1488    so can avoid future unwanted Event Notifications at any time.
1489
1490    It is true that the client has control over whether to ask for Event
1491    Notifications.  However, if the client subscribes to an event and
1492    does a Get-Notifications request, it gets all events for the
1493    Subscription Object in the sequence number range (see section 5.1.2),
1494    not just those it wants.  If a client subscribes to a Per-Printer
1495    Subscription job event, such as 'job-completed', and someone then
1496    starts and cancels thousands of jobs, the client would have to
1497    receive these events in addition to those it is interested in.  A
1498    client can protect itself better by subscribing to its own jobs by
1499    using a Per-Job Subscription, rather than create a Per-Printer
1500    subscription whose Job events apply to all jobs.
1501
1502 17.4.  Security Requirements for Printers
1503
1504    For the Get-Notifications operation defined in this document, the
1505    same Printer conformance requirements apply for supporting and using
1506    Client Authentication, Server Authentication and Operation Privacy as
1507    stated in [RFC2910] section 8 for all IPP operations.
1508
1509
1510
1511
1512
1513
1514 Herriot, et al.             Standards Track                    [Page 27]
1515 \f
1516 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1517
1518
1519 17.5.  Security Requirements for Clients
1520
1521    For the Get-Notifications operation defined in this document, the
1522    same client conformance requirements apply for supporting and using
1523    Client Authentication, Server Authentication, and Operation Privacy
1524    as stated in [RFC2910], section 8, for all IPP operations.
1525
1526 18.  Description of Base IPP Documents (Informative)
1527
1528    The base set of IPP documents includes the following:
1529
1530      Design Goals for an Internet Printing Protocol [RFC2567]
1531      Rationale for the Structure and Model and Protocol for the Internet
1532        Printing Protocol [RFC2568]
1533      Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
1534      Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
1535      Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
1536      Mapping between LPD and IPP Protocols [RFC2569]
1537
1538    "Design Goals for an Internet Printing Protocol" takes a broad look
1539    at distributed printing functionality, and it enumerates real-life
1540    scenarios that help clarify the features that need to be included in
1541    a printing protocol for the Internet.  It identifies requirements for
1542    three types of users: end users, operators, and administrators.  It
1543    calls out a subset of end user requirements that are satisfied in
1544    IPP/1.0 [RFC2566, RFC2565].  A few OPTIONAL operator operations have
1545    been added to IPP/1.1.
1546
1547    "Rationale for the Structure and Model and Protocol for the Internet
1548    Printing Protocol" describes IPP from a high-level view, defines a
1549    roadmap for the various documents that form the suite of IPP
1550    specification documents, and gives background and rationale for the
1551    IETF working group's major decisions.
1552
1553    "Internet Printing Protocol/1.1: Model and Semantics" describes a
1554    simplified model with abstract objects, their attributes, and their
1555    operations that are independent of encoding and transport.  It
1556    introduces a Printer and a Job object.  The Job object optionally
1557    supports multiple documents per Job.  It also addresses security,
1558    internationalization, and directory issues.
1559
1560    "Internet Printing Protocol/1.1: Encoding and Transport" is a formal
1561    mapping of the abstract operations and attributes defined in the
1562    model document onto HTTP/1.1 [RFC2616].  It defines the encoding
1563    rules for a new Internet MIME media type called "application/ipp".
1564    This document also defines the rules for transporting over HTTP a
1565    message body whose Content-Type is "application/ipp".  This document
1566    defines the 'ipp' scheme for identifying IPP printers and jobs.
1567
1568
1569
1570 Herriot, et al.             Standards Track                    [Page 28]
1571 \f
1572 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1573
1574
1575    "Internet Printing Protocol/1.1: Implementer's Guide" gives insight
1576    and advice to implementers of IPP clients and IPP objects.  It is
1577    intended to help them understand IPP/1.1 and some of the
1578    considerations that may assist them in the design of their client
1579    and/or IPP object implementations.  For example, a typical order of
1580    processing requests is given, including error checking.  Motivation
1581    for some of the specification decisions is also included.
1582
1583    "Mapping between LPD and IPP Protocols" gives some advice to
1584    implementers of gateways between IPP and LPD (Line Printer Daemon)
1585    implementations.
1586
1587 19.  Contributors
1588
1589    Carl Kugler and Harry Lewis contributed the basic idea of in-band
1590    "smart polling" coupled with multiple responses for a single
1591    operation on the same connection, with one response for each event as
1592    it occurs.  Without their continual persuasion, we would not have
1593    arrived at this Delivery Method specification and would not have been
1594    able to agree on a single REQUIRED Delivery Method for IPP.
1595
1596    Carl Kugler
1597    IBM Corporation
1598    6300 Diagonal Highway
1599    Boulder, CO 80301
1600
1601    EMail: kugler@us.ibm.com
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626 Herriot, et al.             Standards Track                    [Page 29]
1627 \f
1628 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1629
1630
1631 Authors' Addresses
1632
1633    Robert Herriot
1634    Global Workflow Solutions
1635    706 Colorado Ave.
1636    Palo Alto, CA 94303
1637
1638    Phone: 650-324-4000
1639    EMail: bob@herriot.com
1640
1641
1642    Thomas N. Hastings
1643    Xerox Corporation
1644    710 S Aviation Blvd.  ESAE 242
1645    El Segundo CA 90245
1646
1647    Phone: 310-333-6413
1648    Fax:   310-333-6342
1649    EMail: hastings@cp10.es.xerox.com
1650
1651
1652    Harry Lewis
1653    IBM Corporation
1654    6300 Diagonal Hwy
1655    Boulder, CO 80301
1656
1657    Phone: (303) 924-5337
1658    EMail: harryl@us.ibm.com
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682 Herriot, et al.             Standards Track                    [Page 30]
1683 \f
1684 RFC 3996           IPP: The 'ippget' Delivery Method          March 2005
1685
1686
1687 Full Copyright Statement
1688
1689    Copyright (C) The Internet Society (2005).
1690
1691    This document is subject to the rights, licenses and restrictions
1692    contained in BCP 78, and except as set forth therein, the authors
1693    retain all their rights.
1694
1695    This document and the information contained herein are provided on an
1696    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1697    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
1698    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
1699    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1700    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1701    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1702
1703 Intellectual Property
1704
1705    The IETF takes no position regarding the validity or scope of any
1706    Intellectual Property Rights or other rights that might be claimed to
1707    pertain to the implementation or use of the technology described in
1708    this document or the extent to which any license under such rights
1709    might or might not be available; nor does it represent that it has
1710    made any independent effort to identify any such rights.  Information
1711    on the procedures with respect to rights in RFC documents can be
1712    found in BCP 78 and BCP 79.
1713
1714    Copies of IPR disclosures made to the IETF Secretariat and any
1715    assurances of licenses to be made available, or the result of an
1716    attempt made to obtain a general license or permission for the use of
1717    such proprietary rights by implementers or users of this
1718    specification can be obtained from the IETF on-line IPR repository at
1719    http://www.ietf.org/ipr.
1720
1721    The IETF invites any interested party to bring to its attention any
1722    copyrights, patents or patent applications, or other proprietary
1723    rights that may cover technology that may be required to implement
1724    this standard.  Please address the information to the IETF at ietf-
1725    ipr@ietf.org.
1726
1727 Acknowledgement
1728
1729    Funding for the RFC Editor function is currently provided by the
1730    Internet Society.
1731
1732
1733
1734
1735
1736
1737
1738 Herriot, et al.             Standards Track                    [Page 31]
1739 \f