Request for Comments: 3996 Global Workflow Solutions
Updates: 2911 T. Hastings
Category: Standards Track Xerox Corp.
H. Lewis
IBM Corp.
March 2005
Internet Printing Protocol (IPP):
The ’ippget’ Delivery Method for Event Notifications
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This document describes an extension to the Internet Printing
Protocol1.1: Model and Semantics (RFC 2911, RFC 2910). This document
specifies the ’ippget’ Pull Delivery Method for use with the
"Internet Printing Protocol (IPP): Event Notifications and
Subscriptions" specification (RFC 3995). This IPPGET Delivery Method
is REQUIRED for all clients and Printers that support RFC 3995. The
Notification Recipient, acting as a client, fetches (pulls) Event
Notifications by using the Get-Notifications operation defined in
this document.
Table of Contents
1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Conformance Terminology . . . . . . . . . . . . . . . . 4
2.2. Other Terminology . . . . . . . . . . . . . . . . . . . 4
3. Model and Operation . . . . . . . . . . . . . . . . . . . . . 4
4. General Information . . . . . . . . . . . . . . . . . . . . . 5
5. Get-Notifications Operation . . . . . . . . . . . . . . . . . 7
5.1. Get-Notifications Request . . . . . . . . . . . . . . . 8
5.1.1. notify-subscription-ids (1setOf integer(1:MAX)) 8
5.1.2. notify-sequence-numbers (1setOf integer(1:MAX)) 9
5.1.3. notify-wait (boolean) . . . . . . . . . . . . . 10
5.2. Get-Notifications Response. . . . . . . . . . . . . . . 10
5.2.1. notify-get-interval (integer(0:MAX)). . . . . . 13
5.2.2. printer-up-time (integer(1:MAX)). . . . . . . . 14
6. Additional Information about Subscription Template Attributes 17
6.1. notify-pull-method (type2 keyword). . . . . . . . . . . 17
7. Subscription Description Attributes . . . . . . . . . . . . . 18
8. Additional Printer Description Attributes . . . . . . . . . . 18
8.1. ippget-event-life (integer(15:MAX)) . . . . . . . . . . 18
9. New Values for Existing Printer Description Attributes. . . . 19
9.1. notify-pull-method-supported (1setOf type2 keyword) . . 19
9.2. operations-supported (1setOf type2 enum). . . . . . . . 19
10. New Status Codes. . . . . . . . . . . . . . . . . . . . . . . 19
10.1. successful-ok-events-complete (0x0007) . . . . . . . . 20
11. Encoding and Transport. . . . . . . . . . . . . . . . . . . . 20
12. Conformance Requirements. . . . . . . . . . . . . . . . . . . 21
12.1. Conformance for IPP Printers . . . . . . . . . . . . . 21
12.2. Conformance for IPP Clients. . . . . . . . . . . . . . 22
13. Normative References. . . . . . . . . . . . . . . . . . . . . 23
14. Informative References. . . . . . . . . . . . . . . . . . . . 23
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
15.1. Attribute Registrations. . . . . . . . . . . . . . . . 24
15.2. Delivery Method and Additional Keyword Attribute Value
registrations for Existing Attributes. . . . . . . . . 24
15.3. Additional Enum Attribute Values . . . . . . . . . . . 25
15.4. Operation Registrations. . . . . . . . . . . . . . . . 25
15.5. Status Code Registrations. . . . . . . . . . . . . . . 25
16. Internationalization Considerations . . . . . . . . . . . . . 25
17. Security Considerations . . . . . . . . . . . . . . . . . . . 26
17.1. Notification Recipient Client Access Rights. . . . . . 26
17.2. Printer Security Threats . . . . . . . . . . . . . . . 27
17.3. Notification Recipient Security Threats. . . . . . . . 27
17.4. Security Requirements for Printers . . . . . . . . . . 27
17.5. Security Requirements for clients. . . . . . . . . . . 28
18. Description of Base IPP Documents (Informative) . . . . . . . 28
19. Contributors. . . . . . . . . . . . . . . . . . . . . . . . . 29
Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 31
Table of Tables
Table 1. Information about the Delivery Method. . . . . . . . . . 5
Table 2. Combinations of "notify-wait", "status-code", and
"notify-get-interval". . . . . . . . . . . . . . . . . . 13
Table 3. Attributes in Event Notification Content . . . . . . . . 15
Table 4. Additional Attributes in Event Notification Content for
Job Events . . . . . . . . . . . . . . . . . . . . . . . 16
Table 5. Combinations of Events and Subscribed Events for "job-
impressions-completed" . . . . . . . . . . . . . . . . . 17
Table 6. Additional Attributes in Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . . . . . 17
Table 7. Operation-id Assignments . . . . . . . . . . . . . . . . 19
Table 8. The "event-notification-attributes-tag" Value. . . . . . 21
1. Introduction
This document describes an extension to the Internet Printing
Protocol/1.1: Model and Semantics [RFC 2911], [RFC 2910]. This
document specifies the ’ippget’ Pull Delivery Method for use with the
"Internet Printing Protocol (IPP): Event Notifications and
Subscriptions" specification [RFC3995]. This IPPGET Delivery Method
is REQUIRED for all clients and Printers that support [RFC3995]. The
Notification Recipient, acting as a client, fetches (pulls) Event
Notifications by using the Get-Notifications operation defined in
this document. For a description of the base IPP documents, see
section 21 of this document. For a description of the IPP Event
Notification Model, see [RFC3995].
With this Pull Delivery Method, when an Event occurs, the Printer
saves the Event Notification for a period of time called the Event
Life. The Notification Recipient fetches (pulls) the Event
Notifications by using the Get-Notifications operation. This
operation causes the Printer to return all Event Notifications held
for the specified Subscription object(s). If the Notification
Recipient has selected the Event Wait Mode option to wait for
additional Event Notifications, the Printer MAY continue to return
Event Notifications to the Notification Recipient as asynchronous
Get-Notification responses as Events occur using the transaction
originated by the Notification Recipient.
The Notification Recipient can terminate Event Wait Mode (without
closing the connection) by supplying the "notify-wait" (boolean)
attribute with a ’false’ value in a subsequent Get-Notifications
request. Similarly, the Printer can terminate Event Wait Mode
(without closing the connection) by returning the "notify-get-
interval" (integer) operation attribute in a Get-Notifications
response that tells the Notification Recipient how long to wait
before trying again.
2. Terminology
This section defines the following terms that are used throughout
this document:
2.1. Conformance Terminology
Capitalized terms such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
NOT, MAY, NEED NOT, and OPTIONAL have special meaning relating to
conformance as defined in [RFC2119] and [RFC2911], section 12.1. If
an implementation supports the extension defined in this document,
then these terms apply; otherwise, they do not. These terms define
conformance to this document only; they do not affect conformance to
other documents, unless it is explicitly stated otherwise.
2.2. Other terminology
This document uses the same terminology as [RFC2911], including
"client", "Printer", "Job", "attribute", "attribute value",
"keyword", "operation", "request", "response", and "support", with
the same meanings. This document also uses terminology defined in
[RFC3995], such as "Subscription (object)", "Notification Recipient",
"Event", "Event Notification", "Compound Event Notification", "Event
Life", and "Event Notification Attribute Group", with the same
meanings. In addition, this document defines the following terms for
use in this document:
Event Wait Mode: The mode requested by a Notification Recipient
client in its Get-Notifications Request and granted by a Printer
to keep the connection open while the Printer sends subsequent
Get-Notification operation responses to the Notification
Recipient in the form of Event Notifications as they occur.
3. Model and Operation
In a Subscription Creation Operation, when the "notify-pull-method"
attribute is present and has the "ippget" keyword value, the client
is requesting that the Printer use the "ippget" Pull Delivery Method
for the Event Notifications associated with the new Subscription
Object.
When an Event occurs, the Printer MUST generate an Event Notification
and MUST assign it the Event Life. The Printer MUST hold an Event
Notification for its assigned Event Life.
When a Notification Recipient wants to receive Event Notifications
for a Subscription object, it performs the Get-Notifications
operation supplying the Subscription object’s subscription-id, which
causes the Printer to return all un-expired Event Notifications held
for that Subscription object. If the Notification Recipient has
selected the Event Wait Mode option to wait for additional Event
Notifications, the response to the Get-Notifications request
continues indefinitely as the Printer continues to send Event
Notifications in the response as Events occur for that Subscription
object.
When the Notification Recipient requests Event Notifications for
Per-Job Subscription Objects, the Notification Recipient typically
performs the Get-Notifications operation within a second of
performing the Subscription Creation operation. Because the Printer
MUST save Event Notifications for at least 15 seconds (see section
8.1), the Notification Recipient is unlikely to miss any Event
Notifications that occur between the Subscription Creation and the
Get-Notifications operation.
The ’ippget’ Delivery Method is designed primarily for (1) a client
that wants to get Events (from the job’s Per-Job Subscription object)
for a job that it has submitted and (2) a privileged client that
wants to get all job or printer Events from a Per-Printer
Subscription object.
4. General Information
If a Printer supports this Delivery Method, the following are its
characteristics.
Table 1. Information about the Delivery Method
Document Method Conformance Requirement Delivery Method
Realization
1. What is the URL scheme name for the ’ippget’ keyword method
Push Delivery Method, or the keyword name
method name for the Pull Delivery
Method?
2. Is the Delivery Method REQUIRED, REQUIRED
RECOMMENDED, or OPTIONAL for an IPP
Printer to support?
3. What transport and delivery protocols IPP with one new
does the Printer use to deliver the operation.
Event Notification Content; i.e.,
what is the entire network stack?
4. Can several Event Notifications be Yes.
combined into a Compound Event
Notification?
5. Is the Delivery Method initiated by This Delivery Method is
the Notification Recipient (pull), a pull method with
or by the Printer (push)? aspects of a push
method, though the
Printer does not
initiate the operation.
6. Is the Event Notification content Machine Consumable.
Machine Consumable or Human
Consumable?
7. What section in this document answers Section 5.
the following questions? For a Machine
Consumable Event Notification, what is
the representation and encoding of
values defined in section 9.1 of
[RFC3995], and what are the
conformance requirements thereof? For
a Human Consumable Event Notification,
what is the representation and
encoding of pieces of information
defined in section 9.2 of
[RFC3995], and the conformance
requirements thereof?
8. What are the latency and reliability Same as IPP and the
of the transport and delivery underlying HTTP
protocol? transport.
9. What are the security aspects of the Same as IPP and the
transport and delivery protocol; underlying HTTP
e.g., how it is handled in transport and in the
firewalls? same direction, so no
new firewall
considerations.
10. What are the content length None.
restrictions?
11. What are the additional values or None.
pieces of information that a Printer
sends in an Event Notification content
and the conformance requirements
thereof?
12. What are the additional Subscription None.
Template and/or Subscription
Description attributes and the
conformance requirements thereof?
13. What are the additional Printer "ipp-event-life"
Description attributes and the (integer (15: MAX))
conformance requirements thereof?
5. Get-Notifications Operation
This operation is issued by a client acting in the role of a
Notification Recipient requesting the Printer to return all Event
Notifications held for the identified Subscription object(s).
A Printer MUST support this operation, MUST accept the request in any
state (see [RFC2911] "printer-state" and "printer-state-reasons"
attributes), and MUST remain in the same state with the same
"printer-state-reasons" values.
When a Printer performs this operation, it MUST return all and only
those Event Notifications
1. whose associated Subscription Object’s "notify-subscription-id"
Subscription Description attribute equals one of the values of
the "notify-subscription-ids" (1setOf integer(1:MAX)) operation
attribute AND
2. whose associated Subscription Object contains the "notify-pull-
method" attribute and it has the ’ippget’ keyword value, AND
3. whose "notify-sequence-number" is equal to or greater than the
corresponding value of the "notify-sequence-numbers" (1setOf
integer(1:MAX)) operation attribute if supplied AND
4. whose Event Life has not yet expired AND
5. where the Notification Recipient client has read-access rights to
the identified Subscription Object (see Access Rights paragraph
below).
The Notification Recipient client MUST either (a) request Event Wait
Mode by supplying the "notify-wait" operation attribute with a ’true’
value or (b) suppress Event Wait Mode by omitting the "notify-wait"
operation attribute or by supplying it with a ’false’ value. To
terminate Event Wait Mode subsequently, the Notification Recipient
client MUST close the connection. To terminate Event Wait Mode, the
Printer MUST either (a) return the "notify-get-interval" operation
attribute in a Get-Notifications response (RECOMMENDED behavior) or
(b) close the connection. The "notify-get-interval" operation
attributes tell the Notification Recipient how long to wait before
trying a subsequent Get-Notifications request.
Access Rights: The authenticated user (see [RFC2911], section 8.3)
performing this operation MUST be (1) the owner of each Subscription
Object identified by the "notify-subscription-ids" operation
attribute (see section 5.1.1), (2) an operator or administrator of
the Printer (see [RFC2911], sections 1 and 8.5), or (3) otherwise
authorized by the Printer’s administrator-configured security policy
to request Event Notifications from the target Subscription
Object(s). Otherwise, the IPP Printer MUST reject the operation and
return: ’client-error-forbidden’, ’client-error-not-authenticated’,
or ’client-error-not-authorized’ status code, as appropriate.
Furthermore, the Printer’s security policy MAY limit the attributes
returned by the Get-Notifications operation, in a manner similar to
that of the Get-Job-Attributes operation (see [RFC2911], end of
section 3.3.4.2).
5.1. Get-Notifications Request
The following groups of attributes are part of the Get-Notifications
Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes, as described in [RFC2911], section 3.1.4.1.
Target:
The "printer-uri" (uri) operation attribute that is the target
for this operation as described in [RFC2911], section 3.1.5.
Requesting User Name:
The "requesting-user-name" (name(MAX)) attribute SHOULD be
supplied by the client as described in [RFC2911], section 8.3.
5.1.1. notify-subscription-ids (1setOf integer(1:MAX))
This attribute identifies one or more Subscription objects for which
Events are requested. The client MUST supply this attribute with at
least one value. The Printer object MUST support this attribute with
multiple values.
If no Subscription Object exists with the supplied identifier, or if
the identified Subscription Object does not contain the "notify-
pull-method" attribute with the ’ippget’ keyword value, the Printer
MUST return the ’client-error-not-found’ status code.
Note: The name of both the "notify-subscription-ids" and
"notify-sequence-numbers" end in ’s’, as they are multi-valued.
However, there are other occurrences of these attribute names
without the ’s’ that are single valued.
5.1.2. notify-sequence-numbers (1setOf integer(1:MAX))
This attribute specifies one or more of the lowest Event Notification
sequence number values for the Subscription objects identified by the
corresponding values of the "notify-subscription-ids" operation
attribute. The Notification Recipient SHOULD supply this attribute,
and the number of values SHOULD be the same as that of the "notify-
subscriptions-ids" attribute. The Printer MUST support this
attribute with multiple values.
The Printer MUST NOT return Notification Events with lower sequence
numbers for the corresponding Subscription object. Therefore, by
supplying the proper values for this attribute the Notification
Recipient can prevent getting the same Event Notifications from a
Subscription object that were returned on a previous Get-
Notifications request. The Notification Recipient SHOULD remember
the highest "notify-sequence-number" value returned for each
Subscription object requested and SHOULD pass that value for each
requested Subscription object on the next Get-Notifications request.
If the Notification Recipient supplies fewer values for this
attribute (including omitting this attribute) than it does for the
"notify-subscription-ids" operation attribute, the Printer assumes a
’1’ value for each missing value. A value of ’1’ causes the Printer
to return any un-expired Event Notification for that Subscription
object, as ’1’ is the lowest possible sequence number. If the
Notification Recipient supplies more values for this attribute than
the number of values for the "notify-subscription-ids" operation
attribute, the Printer ignores the extra values.
Note: If a Notification Recipient performs two consecutive Get-
Notifications operations with the same value for "notify-sequence-
number" (or omits the attribute), the time stamp value of the first
Event Notification in the second Get-Notifications Response may be
less than that of the time stamp of the last Event Notification in
the first Get-Notification Response. This happens because the
Printer sends all unexpired Event Notifications with an equal or
higher sequence number according to the ordering specified in
[RFC3995], and some Event Notifications from the first Get-
Notifications operation may not have expired by the time the second
Get-Notifications operation occurs.
5.1.3. notify-wait (boolean)
This value indicates whether the Notification Recipient wants Event
Wait Mode. The client MAY supply this attribute. The Printer object
MUST support both values of this attribute.
If the client supplies the ’false’ value or omits this attribute, the
client is not requesting Event Wait Mode. If the value is ’true’,
the client is requesting Event Wait Mode. See the beginning of
section 5.2 for the rules for Event Wait Mode.
5.2. Get-Notifications Response
The Printer has the following options for responding to a Get-
Notifications Request:
1. The Printer can reject the request and return the ’server-error-
busy’ status code if the Printer is too busy to accept this
operation at this time. In this case, the Printer MUST return