We held the telecon, Wednesday, July 18, 2001 and reached the
following agreements on the Event Notification specs. This mail note is
also available as a .doc file at:
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/notification-clarification-agreements.
doc
Please send any comments on this today to help with my editing so we can
meet the Internet-Drafts deadline of this Friday. After today, any comments
will be good comments for the Last Call on the IPP GET spec.
Thanks,
Tom
SUBJECT: IPP Notification spec ISSUES and agreements
Date: 7/18/01
File: notification-clarification-agreements.doc
We held the telecon, Wednesday, July 18, 2001 and reached the
following agreements on the Event Notification specs.
Attendees: Carl Kugler (IBM), Harry Lewis (IBM), Ted Tronson
(Novell), Marty Joel (Netreon), Carl-Uno Manros (Xerox), Tom
Hastings (Xerox).
1 Summary of agreements
1. Base Event Notifications spec: We agreed to clarify that the
Printer MUST send Event Notifications for any given Subscription
Object in time stamp order, but MAY interleave Event Notifications
from other Subscription Objects. See explicit text below. This
clarification will be included in the updated Internet-Draft
requested by our Area Director, Ned Freed, along with his
requested updates.
2. IPPGET spec: We agreed to a number of changes and agreed that
this spec needs another WG Last Call which will start next week
when the updated Internet-Draft is published and will end the week
following the IETF meeting, August 17, 2000. IPPGET is the only
REQUIRED Delivery Method for IPP FAX, so it is worth having the
second WG Last Call, now that we are gaining some implementation
experience. The Area Director is still reviewing the previous
Internet-Draft we sent last Fall, and we will request that the new
version be substituted following the IETF procedures for this,
after the Last Call completes. The IPPGET spec changes are:
1. Change the terminology in IPPGET not to use "push", since
the term "push" outside of IPP Notification means create
the connection as well as send. In IPPGET use the term
"wait mode" instead.
2. Clarify that a Printer that supports the IPPGET Delivery
Method, MUST use HTTP chunking (HTTP/1.1 required feature)
in the Get-Notifications response if it keeps the
connection open, i.e., honors the client's request for
"wait mode".
3. Clarify that "using the Get-Jobs model for returning
multiple groups of attributes" means that the Printer
returns the 'end-of-attributes' (0x03) tag at the end of
the last Get-Notifications Response to indicate that there
are no more events that will come.
4. REQUIRE URI matching rules for ippget scheme
5. REQUIRE that a Printer MUST return the "notify-recipient-
uri" value as submitted by the Subscribing Client.
6. Reduce the length of the "notify-recipient-uri" attribute
for ippget to 255 octets (since this doesn't really specify
a resource and an implementation may want to keep a
canonical form copy as well).
7. In a Get-Notifications response when the client has
requested the wait mode, allow a Printer to return the
unexpired Notification Events, but also indicate to the
client to please disconnect and try again at the indicate
interval ("suggested-ask-again-time-interval" renamed to
"notify-get-interval"). (IPPGET currently only allows the
interval to be returned if the client didn't ask for wait
mode or if the Printer is too busy to return any Event
Notifications).
8. Do not generalize Get-Notifications for use with indp or
mailto Delivery Methods. REQUIRE the Printer to reject the
Get-Notifications Request if the scheme is not 'ippget'.
But allow a future Delivery Method Document to use the Get-
Notifications operation if polling makes sense for that
Delivery Method
9. Don't change the Get-Notifications operation name and keep
it in the ippget spec.
10. Change the sense of the Get-Notifications "notify-no-wait"
(boolean) operation attribute to a positive "notify-wait"
(boolean), so that omitted and 'false' mean the easier non-
wait operation.
11. Rename "notify-ippget-redirect" (uri) to "redirect-uri"
(uri), so that it could in principle be used for other
operations.
12. Rename "suggested-ask-again-time-interval" (integer(0:MAX))
to "notify-get-interval", to shorten it, and indicate that
it is for notification, but only events returned by the
Get-Notifications operation.
13. Rename "begin-to-expire-time-interval" (integer(0:MAX)) to
"ippget-event-time-to-live", to shorten it somewhat, use
recognized terms for this concept, and indicate that it is
for events, but only ippget events.
14. Clarify that for Subscriptions that contain Job events,
that the Subscription Object that has the ippget scheme
MUST stay around for the "ippget-event-time-to-live" value
and so MUST the corresponding Job object, so that the
Notification Recipient can query the Job after receiving
the 'job-completed' Event Notification. (For the other
Delivery Methods, the usual Job History mechanism can be
used to retain the Job objects after the job completion, so
that the Notification Recipient can query the Job object
after receiving the 'job-completed' Event Notification.)
15. Clarify that the Cancel-Subscriptions operation does not
need to keep the Subscription object after the request, no
matter what kind of Delivery Method it contains.
Therefore, any events associated with the Subscription
object MUST NOT be returned by the Get-Notifications
operation after the Cancel-Subscription operation for that
Subscription Object.
2 Clarifications to the ordering that the Printer sends Event
Notifications
In the Base Event Notifications spec [ipp-ntfy] section 9 after
paragraph 2 add the following text:
Event Notification Ordering:
When a Printer sends Event Notifications, the Event Notifications
from any given Subscription Object MUST be in time stamp order,
i.e., in order of increasing "printer-up-time" attribute value in
the Event Notification (see Table 5). These Event Notifications
MAY be interleaved with those from other Subscription Objects, as
long as those others are also in time stamp order. The Printer
MUST observe these ordering requirements whether sending multiple
pending Events as multiple separate Event Notifications or
together in a single Compound Event Notification.
If a Subscribing Client wants the Printer to send certain Event
Notifications in time stamp order, the Subscribing Client uses a
single Subscription Object. Even so, depending on the underlying
transport, the actual order that a Notification Recipient receives
separate Event Notifications may differ from the order sent by the
Printer (e.g., email).
Example: Consider two Per-Printer Subscription Objects: SO1 and
SO2. SO1 requests 'job-state-changed' events and SO2 requests
'printer-state-changed' events. The number in parens is the time
stamp. The following Event Notification sequences are the only
ones that conform to the ordering requirements for the Printer to
send the Event Notifications:
(a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1:
'job-completed' (1009), SO2: 'printer-stopped' (1005)
(b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2:
'printer-stopped' (1005), SO1: 'job-completed' (1009)
(c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1:
'job-stopped' (1005), SO1: 'job-completed' (1009)
(d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1:
'job-stopped' (1005), SO1: 'job-completed' (1009)
Examples (b) and (c) are interleaved; examples (a) and (d) are not
and may not be appropriate for some Delivery Methods.
IPPGET:
Make the following changes to the first paragraph in the Get-
Notifications Response, section 5.2 (I put [] around new text, but
deleted old text without indication):
Group 3 through N: Event Notification Attributes
The Printer responds with one Event Notification Attributes Group
per matched Event Notification. [The entire response is
considered a single Compound Event Notification (see [ipp-ntfy]).]
The initial matched Event Notifications are all un-expired Event
Notifications associated with the matched Subscription Objects
[and MUST follow the ordering requirements for Event Notifications
within a Compound Event Notification specified for the "Event
Notification Ordering" in [ipp-ntfy] section 9].
If the Notification Recipient has selected the option to wait for
additional Event Notifications [(the "notify-no-wait" attribute
was set to 'false' or was omitted)], the Printer {sends}
subsequent Event Notifications in the response [each time it
processes additional Events]. [Each time the Printer sends such
Event Notifications, their ordering MUST be the ordering specified
for the "Event Notification Ordering" in [ipp-ntfy] section 9.]
[ Note: If a Notification Recipient performs two consecutive Get-
Notifications operations, the time stamp of the first Event
Notification in the second Get-Notifications Response may be less
than the time stamp of the last Event Notification in the first
Get-Notification Response. This happens because the Printer sends
all unexpired Event Notification according to the ordering
specified in [ipp-ntfy] and some Event Notifications from the
first Get-Notifications operation may not have expired by the time
the second Get-Notifications operation occurs. ]
INDP:
In INDP section 8.1 Send-Notifications Request, 2nd paragraph (I
put [] around the new text):
The Printer composes the information defined for an IPP
Notification [ipp-ntfy] and sends it using the Send-Notifications
operation to the Notification Recipient supplied in the
Subscription object. [The ordering of separate Send-Notifications
operations that a Printer sends MUST be the ordering specified for
the "Event Notification Ordering" in [ipp-ntfy] section 9.]
In INDP section 8.1.1 Send-Notifications Request (I put [] around
the new text):
Group 2 to N: Event Notification Attributes
In each group 2 to N, each attribute is encoded using the IPP
rules for encoding attributes [RFC2910] and [the attributes within
a group] MAY be encoded in any order. [The entire request is
considered a single Compound Event Notification and MUST follow
the ordering requirements for Event Notifications within a
Compound Event Notification specified for the "Event Notification
Ordering" in [ipp-ntfy] section 9.] Note: the Get-Jobs response
in [RFC2911] acts as a model for encoding multiple groups of
attributes.
MAILTO:
MAILTO section 6, add the following after the existing 2nd
paragraph:
While the "Event Notification Ordering" in [ipp-ntfy] section 9
specifies ordering requirements for Printers when sending separate
Event Notifications, email messages are not guaranteed to arrive
in the order sent so that the Notification Recipient may not
receive them in the same order.
MAILTO section 6 Event Notification Content, right before section
6.1 (I put [] around the new text):
The Event Notification content has two parts, the headers and the
message body. The headers precede the message body and are
separated by a blank line (see [RFC 822]).
[A Printer implementation MAY combine several Event Notifications
into a single email message body. Such an email message is
considered a single Compound Event Notification and MUST follow
the ordering requirements for Event Notifications within a
Compound Event Notification specified for the "Event Notification
Ordering" in [ipp-ntfy] section 9.]
3 Some of the text changes for the IPPGET Delivery Method
Here are some of the text changes for the agreed changes to the
IPPGET Delivery Method spec:
3.1 IPPGET: Matching "notify-recipient-uri"
Change IPPGET Section 5.1 from:
"notify-recipient-uri" (url):
The client MUST supply this attribute. The Printer object
MUST support this attribute. The Printer matches the value
of this attribute (byte for byte with no case conversion)
against the value of the "notify-recipient-uri" in each
Subscription Object in the Printer. If there are no matches,
the IPP Printer MUST return the 'client-error-not-found'
status code.
to:
"notify-recipient-uri" (url):
The client MUST supply this attribute. The Printer object
MUST support this attribute. The Printer matches the value
of this attribute against the value of the "notify-
recipient-uri" in each Subscription Object in the Printer
following the normal URI comparison rules (see section
9.5.2). If the scheme is not the ippget scheme, the Printer
MUST reject the request and return the 'client-error-uri-
scheme-not-supported' status code. If there are no matches,
the IPP Printer MUST reject the request and return the
'client-error-not-found' status code.
3.2 IPPGET: Allow the Printer to request the client to disconnect
Change section 5.2:
"suggested-ask-again-time-interval" (integer(0:MAX)):
The value of this attribute is the number of seconds that
the Notification Recipient SHOULD wait before trying this
operation again when
a) the Printer returns the 'server-error-busy' status code
OR
b) the Printer returns the 'successful-ok' status code and
the client supplied the "notify-no-wait" attribute with
a value of 'true'.
This value is intended to help the client be a good network
citizen.
to:
"notify-get-interval" (integer(0:MAX)):
The value of this attribute is the number of seconds that
the Notification Recipient SHOULD wait before trying this
operation again when
a) the Printer returns the 'server-error-busy' status code
OR
b) the Printer returns the 'successful-ok' status code and
the client supplied the "notify-no-wait" attribute with
a value of 'true' (the no wait case)
OR
c) the Printer returns the 'successful-ok' status code and
the client supplied the "notify-no-wait" attribute with
either 'false' value or omitted the attribute all
together (the wait case) and the Printer wants the
client to disconnect, instead of staying connected. The
client MUST accept this response and MUST disconnect.
If the client does not disconnect, the Printer SHOULD do
so. The Printer returns this attribute for this case
only if the implementation does not want to keep the
connection open at this time. If the Printer wants the
client to keep the connection open, then the Printer
MUST NOT return this attribute in the response.
This value is intended to help the client be a good network
citizen.
3.3 Change the sense of the "notify-no-wait" operation attribute to
"notify-wait"
Change section 5.1, "notify-no-wait" (boolean) from:
"notify-no-wait" (boolean):
The client MAY supply this attribute. The Printer object
MUST support this attribute. If the value of this attribute
is 'false', the Printer MUST send all un-expired Event
Notifications (as defined in the previous attribute) and it
MUST continue to send responses for as long as the
Subscription Objects associated with the specified "notify-
recipient-uri" continue to exist. If the value of this
attribute is 'true', the Printer MUST send all un-expired
Event Notifications (as defined in the previous attribute)
and the Printer MUST conclude the operation without waiting
for any additional Events to occur. If the client doesn't
supply this attribute, the Printer MUST behave as if the
client had supplied this attribute with the value of
'false'.
to:
"notify-wait" (boolean):
The client MAY supply this attribute. The Printer object
MUST support this attribute. If the value of this attribute
is 'false' or omitted, the Printer MUST send all un-expired
Event Notifications (as defined in the previous attribute)
and the Printer MUST conclude the operation without waiting
for any additional Events to occur. If the value of this
attribute is 'true', the Printer MUST send all un-expired
Event Notifications (as defined in the previous attribute)
and it MUST continue to send responses for as long as the
Subscription Objects associated with the specified "notify-
recipient-uri" continue to exist or return the "notify-get-
interval" attribute in the response (see section 5.2).