These are the agreements reached at the IPP WG meeting, 5/17/00. Please
send any comments to the mailing list. Bob and I are updating the
notification documents according to these agreements. A more readable
version is uploaded at:
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/notification-agreements-000517.doc
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/notification-agreements-000517.pdf
Notification Spec and Mailto: Agreements, 5/17/00
From: Tom Hastings and Bob Herriot
File: notification-agreements-000517.doc
1. The Notification Specification [ipp-ntfy] contains common semantics
for all delivery methods. [ipp-ntfy] contains conformance requirements
Subscribing clients, Printers, and Notification Sources that apply for all
delivery methods. [ipp-ntfy] also contains conformance requirements for the
delivery method documents. The delivery method documents will not duplicate
information that is in [ipp-ntfy].
2. It was agreed that the number of tables should be drastically
reduced, while still designing them to be readable in the plain text
Internet-Draft and RFC versions.
3. Some terms will be defined and use consistently throughout the
specification document (capitalized, but not quoted), in order to shorten
the document and improve the precision of the document. The term "Job
Creation operation" will mean the Print-Job, Print-URI, and Create-Job
operations. If the Validate-Job operation is intended, it will be
explicitly listed. The term "Subscription Creation operation" will mean the
Job Creation operations along with the Create-Printer-Subscription and
Create-Job-Subscription operations.
4. It was agreed to use the term "Subscribing client", instead of just
"client" or "Subscriber". The Subscription client sends Subscription
Creation requests to the Printer. The verb "MAY" will be clarified for use
with the Printer object to include, but not be limited to, the following
implementation-dependent possibilities: hard-coded, configurable, either
locally, or via the IPP protocol or other protocols, and/or able to
accept/return due to current state and conditions. The verb "populate" will
be used as in the [ipp-mod] document to indicate the Printer action of
filling in Subscription object attributes.
5. We will use the term "Notification Source", instead of "Printer",
when specifying conformance requirements for the Event Notification content,
so that these requirement cover both e when the Printer is the Notification
Source and when the Printer is using a Notification Service as the
Notification Source (transparently to the Subscribing client).
6. Various documents use "Event Notification Attributes" group/tag
versus "Notification Attributes" group/tag. We will use the Event
Notification Attributes group/tag consistently, since the term
"Notification" can refer to everything as well as just Event Notification
(content).
7. It was agreed to introduce the concept of Subscription Template
attributes, like Job Template attributes in [ipp-mod]. The goal is to
shorten the document by defining each attribute only once in the document,
instead of once as a Subscription object attribute and for each operation.
The Printer attributes that relate to the Subscription Template attributes
that the Subscribing client supplies will be described with each
Subscription attribute. Thus the related attributes will be defined
altogether in the document. There may be some attribute renaming to conform
to the usual "xxx", "xxx-supported" pattern for Template attributes, as in
[ipp-mod].
The table below summarizes the names and relationships for all
Subscription Template attributes (revision marks show changes from the
5/11/00 [ipp-ntfy] document). The first column of the table (labeled
"Subscription Attribute") shows the name and syntax for each Subscription
Template attribute in the Subscription object. The Printer MUST support all
of these Subscription Template attributes, except for
"notify-requested-attributes". The Subscribing client MAY omit any of these
in a Subscription Creation request, except for the "notify-recipient-uri"
attribute. The last two columns (labeled "Printer: Default Value Attribute"
and "Printer: Supported Values Attribute") show the name and syntax for each
Job Template attribute in the Printer object (the default value attribute
and the supported values attribute). A "No" in the table means the Printer
MUST NOT support the attribute (that is, the attribute is simply not
applicable). Other sources or fixed values are given for defaults when
there is no "xxx-default" Printer attribute defined.
Subscription Attribute Printer: Default Value Attribute Printer:
Supported Values Attribute
notify-recipient-uri (uri) No notify-recipient-supported (1setOf
uriScheme)
notify-requested-events (1setOf type2 keyword)
notify-requested-events-default (1setOf type2 keyword)
notify-requested-events-supported (1setOf type2 keyword)
notify-max-events-supported (integer(5:MAX))
notify-requested-attributes (1setOf type2 keyword) 'none'
notify-requested-attributes-supported (1 setOf type2 keyword)
notify-user-data (octetString(63)) No No
notify-charset (charset) "attributes-charset" in the request
charset-supported (1setOf charset)
notify-natural-languages ( naturalLanguage)
"attributes-natural-language" in the request
generated-natural-language-supported (1setOf naturalLanguage)
8. The following table summarizes the Subscription Description
attributes (revision marks show changes from the 5/11/00 [ipp-ntfy]
document). The Printer MUST support and populate all the Subscription
Description attributes. The Subscribing client MUST NOT supply any of them.
Subscription Description attributes: Related Printer Description
attribute(s)
notify-sequence-id (integer(0:MAX)) n/a
notify-subscription-id (integer(1:MAX)) n/a
notify-lease-expiration-time (integer(0:MAX)) notify-lease-time-default
(integer(0:MAX)) notify-lease-time-supported (rangeOfInteger(0:MAX))
notify-printer-uri (uri) printer-uri-supported (1setOf uri)
notify-subscriber-user-name (name(MAX)) n/a
notify-server-up-time (integer(1:MAX)) printer-up-time (integer(1:MAX))
notify-persistence-granted (boolean) persistent-subscriptions-supported
(boolean)
9. It was agreed to change the event definitions so that they are not
disjoint. For example, the 'job-created' and 'job-completed' events will
also be part of the 'job-state-change' event. This will reduce the number
of events that a Subscribing client need supply, since it did not seem
useful to be able to request 'job-state-change' without getting the
'job-created' and 'job-completed' events. This also means that a grouping
event whether REQUIRED or OPTIONAL can include other events that are
OPTIONAL for a Printer to support. The following table summarizes the event
groupings and their conformance requirements for Printers to support:
Individual event: Printer MUST support? Grouping event: Printer MUST
support?
none yes no
job-created yes job-state-changed yes
job-completed yes job-state-changed yes
job-config-changed no
job-purged no no
printer-restarted no printer-state-changed yes
printer-shutdown no printer-state-changed yes
printer-media-changed no printer-config-changed no
printer-queue-changed no no
printer-no-longer-full no no
printer-almost-idle no no
10. It was agreed to add the Subscription Attributes tag and group to
the IPP/1.1 Job Creation and Validate-Job operations, instead of passing the
Subscription Template attributes in the Operation attribute group. Then the
IPP/1.1 operations will be consistent with the new Subscription operations
which have the separate Subscription Attributes tag and group in requests
and responses. The handling of unrecognized attribute groups was in the
Model appendix that was moved to the Implementer's Guide. According to it,
existing IPP/1.1 Printers are supposed to ignore completely any attribute
groups they do not recognize (and not return anything in the Unsupported
Attribute Group and not change the return status code). Thus introducing a
new attribute group and tag into existing operations should not impact
current Printer implementations.
11. It was agreed to remove the Subscription Attributes tag and group
from the Get-Subscription-Attributes request and move the
"notify-subscription-id" and "requested-attributes" to the Operation
attribute group in order to be more like the Get-Printer-Attributes
operation in [ipp-mod].
12. It was agreed that the Subscribing client can supply one or more
Subscription Attribute groups in each Job Creation request. The Printer
MUST accept these multiple subscriptions, if it supports more than one
Per-Job Subscription. If any of the subscriptions have bad syntax or any
REQUIRED attributes (such as the "notify-recipient-uri" attribute) is
missing, the Printer MUST reject the operation and return the
'client-error-bad-request' status code, independent of the value that the
Subscribing client supplies for "ipp-attribute-fidelity", since such a
mal-formed request is a development time error. However, if there is any
other validation errors, the Printer MUST ignore them and accept the Job
Creation operation, independent of the value that the Subscribing client
supplies for "ipp-attribute-fidelity".
It was also agreed that the Printer MUST return one subscription
object in the response for each subscription object in the request and in
the same order. That subscription object contains the following. If the
subscription succeeds, it contains a "notify-subscription-id" attribute. If
it fails, it contains the attributes to be determined during the rewrite.
13. It was tentatively agreed that the Subscribing client can supply one
or more Subscription Attribute groups in each Create-Printer-Subscription
and Create-Job-Subscription request, unless the error handling becomes too
complicated when there are multiple subscriptions. If these operations
remain as one subscription per request, the Subscribing client could perform
multiple operations to get multiple subscriptions, one for each
subscription. The editors (Bob Herriot and Tom Hastings) will look at the
complexity and make a recommendation. If these two operations are changed
to allow multiple subscriptions in a single request, the operation name will
have an "s" added to them.
14. If the Subscribing client omits the "notify-charset" Subscription
Template attribute in the Subscription Creation request, the Printer MUST
populate the "notify-charset" Subscription object attribute with the value
from the "attributes-charset" operation attribute that the Subscribing
client MUST supply in the request (as in any other IPP request). Same for
the "notify-natural-language" Subscription Template attribute.
15. A delivery method document MAY add additional Subscription Template
and/or Printer Description attributes.
We agreed to eliminate the ability to send Machine Consumable, such
as application/ipp, with the mailto: delivery scheme. We agreed to delete
the "notify-additional-formats" (1setOf mimeMediaType) and
"notify-text-format" (mimeMediaType) Subscription Template attributes from
[ipp-ntfy] and replace them with the "notify-mailto-text-only" (boolean)
Subscription Template attribute in [ipp-mailto]. A 'true' value means that
the Notification Source MUST include only a text/plain format using the
charset indicated by the "notify-charset" Subscription object attribute. A
'false' values means that the Event Notification MAY contain other formats,
in addition to this text format. If the Subscribing client omits this
attribute, the Printer MUST populate it with the 'false' value.
It was agreed that this attribute is 'boolean', not 'type2 keyword'
so that it cannot be extended. Using a boolean simplifies the Subscribing
client and Printer implementations since this Subscription Template
attribute will have neither a "notify-mailto-text-only-default" nor a
"notify-mailto-text-only-supported" Printer attribute, since the default is
defined to be 'false' and an implementation MUST support both values. Note:
not having an "xxx-default" and "xxx-supported" breaks the usual pattern for
Template attributes, but this deviation was thought to be ok in order to
further simplify implementation of both the Subscribing client and the
Printer.
The naming pattern: "notify-xxx-yyy" where xxx is the delivery
scheme is intended to help a base implementation support arbitrary plug-in
notification methods and to clarify that this attribute applies only to the
mailto: delivery scheme. The following table shows the mailto: REQUIRED
Subscription Template attribute:
Subscription Attribute Printer: Default Value Attribute Printer:
Supported Values Attribute
notify-mailto-text-only (boolean) 'false' No
16. A delivery method document MUST include conformance requirements for
any such additional Subscription Template and/or Printer Description
attributes that apply to a Subscribing client and/or a Printer if that
delivery method is requested and/or supported, respectively.
A Printer MUST support the "notify-mailto-text-only" (boolean)
Subscription Template attribute if it supports the mailto: delivery method.
17. A delivery method document MAY define more specific semantics for
the "notify-recipient" (scheme parameters) and "notify-user-data"
Subscription Template attributes.
[ipp-mailto:] The "notify-user-data" Subscription Template attribute
is defined to be an RFC 822 mailbox address which has both the display name
of the subscribing user and the email address of the subscribing user
(inside angle brackets)
18. The [ipp-ntfy] document defines the requirements for the
Notification Source to include in any Machine Consumable Event Notification
content. These requirements are defined in terms of the source of the
information in terms of Subscription, Job, and Printer attributes. However,
the delivery method document defines the format for the information. The
delivery method document MAY increase, but not decrease, the conformance
requirements that are defined in [ipp-ntfy]. The mailto: no longer has a
way to send Machine Consumable Event Notification content (see agreement
#15).
19. The [ipp-ntfy] document defines the RECOMMENDATIONS for Human
Consumable Event Notification content. Each of the four delivery methods
have ways to send Human Consumable form. Those that also support Machine
Consumable send Human Consumable as the value of the "notify-text" attribute
in the Machine Consumable format.
20. The main purpose of each delivery method document is to define how
the Notification Source MUST map the REQUIRED and OPTIONAL source attribute
values (as populated by the Printer) to the Event Notification content. In
addition, each delivery method document MUST define the encoding and
transport of the Event Notification.
For the mailto: notification delivery method, the Notification
Source MUST supply each of the following RFC 822 fields from the indicated
Subscription object attributes as populated by the Printer:
From: An RFC 822 mailbox address string consisting of the
"printer-name" Printer attribute concatenated with a "configurable email
address" inside angle brackets. This "configurable email address" could be
that of the administrator or the device, but it NEED NOT be capable of
receiving mail. There will not be a Printer attribute defined to hold this
"configurable email address", so that it cannot be configured using the IPP
protocol without an implementation-defined attribute extension.
Reply-To: and Sender: The "notify-user-data" Subscription object
attribute which the Subscribing client SHOULD supply as an RFC 822 "mailbox
address" (see item 17 above). If the Subscribing client did not supply a
syntactically valid "RFC 822 mailbox address", the Notification Source MUST
NOT supply these headers.
To: The remainder of the "notify-recipient-uri" Subscription object
attribute after the mailto: scheme.
21. For any Subscription Template attribute that a Subscribing client
can omit and that [ipp-ntfy] doesn't define how the Printer MUST populate
the Subscription object attribute, the delivery method document MUST specify
the value that the Notification Source MUST supply in the Event Notification
content.
[ipp-mailto]: If the Subscribing client omits the "notify-user-data"
Subscription Template attribute or supplies a syntactically invalid "mailbox
address", the Notification Source MUST omit the Reply-To: MUST omit the
Sender: field (as required by RFC 822 when the Sender: field would be the
same as the From: field).
22. For the mailto: delivery method, the Notification Source MUST
support the SMTP protocol and MAY support other mail protocols. When
sending the text/plain in the body of the message, the Notification Source
MUST fill in the SMTP mail header with the 'text/plain' value concatenated
with the string: "; charset=" and the value of the "notify-charset"
Subscription object attribute.
This archive was generated by hypermail 2b29 : Tue May 23 2000 - 15:24:29 EDT