relationship.
embedded printer:
output device or server
PDA, desktop, or server +---------------+
+--------+ | ########### |
| client |-----Subscription ---------># Printer # |
+--------+ Creation Operation | # Object # |
+------------+ | #####|##### |
|Notification| +-------|-------+
|Recipient |<----IPP Event Notifications----+
+------------+ (Job and/or Printer Events)
Figure 1 - Model for Notification
2.2. Additional Models for Notification (Informative)
Additional models have been proposed (see Appendices 16, 17, and 18).
3. Terminology
This section defines terminology used throughout this document.
Other terminology is defined in [RFC2911].
3.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 RFC 2119 [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 explicitly stated otherwise.
Note: a feature that is OPTIONAL in this document becomes REQUIRED if
the Printer implements a Delivery Method that REQUIRES the feature.
READ-ONLY - an adjective used in an attribute definition to indicate
that an IPP Printer MUST NOT allow the attribute’s value to be
modified.
3.2. Other Terminology
This document uses the same terminology as [RFC2911], such as
"client", "Printer", "attribute", "attribute value", "keyword",
"operation", "request", "response", "administrator", "operator", and
"support". In addition, the following terms are defined for use in
this document and the Delivery Method Documents:
Compound Event Notification - two or more Event Notifications that a
Printer delivers together as a single request or response. The
Delivery Method Document specifies whether the Delivery Method
supports Compound Event Notifications.
Delivery Method - the mechanism by which the Printer delivers an
Event Notification.
Delivery Method Document - a document, separate from this document,
that defines a Delivery Method.
Event - some occurrence (either expected or unexpected) within the
printing system of a change of state, condition, or configuration of
a Job or Printer object. An Event occurs only at one instant in time
and does not span the time the physical Event takes place. For
example, jam-occurred and jam-cleared are two distinct, instantaneous
Events, even though the jam may last for a while.
Event Life - For a Pull Delivery Method, the length of time in
seconds after an Event occurs during which the Printer will retain
that Event for delivery in an Event Notification. After the Event
Life expires, the Printer will no longer deliver an Event
Notification for that Event in such a response.
Event Notification - the information about an Event that the Printer
delivers when an Event occurs.
Event Notification Attributes Group - The attributes group which is
used to deliver an Event Notification in a request (Push Delivery
Methods) or a response (Pull Delivery Methods).
Human Consumable Event Notification - localized text for human
consumption only. There is no standardized format and thus programs
should not try to parse this text.
Job Creation operation - One of the operations that creates a Job
object: Print-Job, Print-URI and Create-Job. The Restart-Job
operation [RFC2911] is not considered a Job Creation operation, since
the Printer re-uses the existing Job object. The Validate-Job
operation is not considered a Job Creation operation because no Job
object is created. Therefore, when a statement also applies to
either the Restart-Job and/or the Validate-Job operation, they are
mentioned explicitly.
Job Event - an Event caused by some change in a particular job on the
Printer, e.g., ’job-completed’.
Machine Consumable Event Notification - bytes for program
consumption. The bytes are formatted according to the Delivery
Method document.
Notification - when not in the phrases ’Event Notification’ and
’Notification Recipient’ - the concepts of this specification, i.e.,
Events, Subscription Objects, and Event Notifications.
Notification Recipient - the entity to which the Printer delivers an
Event Notification. For Push Delivery Methods, the IPP Printer sends
the Notifications to a Notification Recipient. For Pull Delivery
Methods, the Notification Recipient is acting in the role of an IPP
client and requests Event Notifications and so the terms "client" and
"Notification Recipient" are used interchangeably with such Delivery
Methods. For example, see [RFC3996].
Per-Job Subscription Object - A Subscription Object that is
associated with a single Job. The Create-Job-Subscriptions operation
and Job Creation operations create such an object.
Per-Printer Subscription Object - A Subscription Object that is
associated with the Printer as a whole. The Create-Printer-
Subscriptions operation creates such an object.
Printer Event - an Event caused by some change in the Printer that is
not specific to a job, e.g., ’printer-state-changed’.
Pull Delivery Method - The Printer saves Event Notifications for some
event life time and expects the Notification Recipient to request
Event Notifications. The Printer delivers the Event Notifications in
a response to such a request.
Push Delivery Method -The Printer delivers the Event Notification
shortly after an Event occurs.
Subscribed Event - an Event that the Subscribing Client expresses
interest in by making it a value of the "notify-events" attribute on
a Subscription Object.
Subscribed Job Event - a Subscribed Event that is a Job Event.
Subscribed Printer Event - a Subscribed Event that is a Printer
Event.
Subscribing Client - The client that creates the Subscription Object.
Subscription Attributes Group - The attributes group in a response
that contains Subscription Object attributes.
Subscription Creation Operation - An operation that creates a
Subscription Object: Job Creation operations, Create-Job-
Subscriptions operation, Create-Printer-Subscriptions operation. In
the context of a Job Creation operation, a Subscription Creation
Operation is the part of the Job Creation operation that creates one
or more Subscription objects. The Restart-Job operation [RFC2911] is
not considered a Subscription Creation Operation, since the Printer
re-uses the Job’s existing Subscription Objects, rather than creating
any new Subscription Objects.
Subscription Creation Request - The request portion of a Subscription
Creation Operation.
Subscription Description Attributes - Subscription Object attributes
that a Printer supplies during a Subscription Creation Operation.
Subscription Object - An object containing a set of attributes that
indicate: the Notification Recipient (for Push Delivery Method
only), the Delivery Method, the Subscribed Events that cause the
Printer to deliver an Event Notification, and the information to
include in an Event Notification.
Subscription Template Attributes - Subscription Object attributes
that a client can supply in a Subscription Creation Operation and
associated Printer Object attributes that specify supported and
default values for the Subscription Object attributes.
Subscription Template Attributes Group - The attributes group in a
request that contains Subscription Object attributes that are
Subscription Template Attributes.
4. Object Relationships
This section defines the object relationships between the Printer,
Job, and Subscription Objects. It does not define the
implementation. For an illustration of these relationships, see
Appendix 19.
4.1. Printer and Per-Printer Subscription Objects
1. A Printer object can be associated with zero or more Per-Printer
Subscription Objects.
2. Each Per-Printer Subscription Object is associated with exactly
one Printer object.
4.2. Printer, Job and Per-Job Subscription Objects
1. A Printer object is associated with zero or more Job objects.
2. Each Job object is associated with exactly one Printer object.
3. A Job object is associated with zero or more Per-Job Subscription
Objects.
4. Each Per-Job Subscription Object is associated with exactly one
Job object.
5. Subscription Object
A Subscribing Client creates a Subscription Object with a
Subscription Creation Operation in order to indicate its interest in
certain Events. See section 11 for a description of these
operations. When an Event occurs, the Subscription Object specifies
to the Printer where to deliver Event Notifications for Push Delivery
Methods only, how to deliver them, and what to include in them. See
section 9 for details on the contents of an Event Notification.
Using the IPP Job Template attributes as a model (see [RFC2911]
section 4.2), the attributes of a Subscription Object are divided
into two categories: Subscription Template Attributes and
Subscription Description Attributes.
Subscription Template attributes are, in turn, like the Job Template
attributes, divided into
1. Subscription Object attributes that a client can supply in a
Subscription Creation Request and
2. their associated Printer Object attributes that specify supported
and default values for the Subscription Object attributes
The remainder of this section specifies general rules for
Subscription Template Attributes and describes each attribute in a
Subscription Object.
5.1. Rules for Support of Subscription Template Attributes
Subscription Template Attributes are fundamental to the Notification
model described in this specification. The client supplies these
attributes in Subscription Creation Operations and the Printer uses
these attributes to populate a newly created Subscription Object.
Subscription Objects attributes that are Subscription Template
Attributes conform to the following rules:
1. Each attribute’s name starts with the prefix string "notify-" and
this document calls such attributes "notify-xxx".
2. For each "notify-xxx" Subscription Object attribute defined in
column 1 of Table 1 in section 5.3, Table 1 specifies
corresponding Printer attributes: "notify-xxx-default", "notify-
xxx-supported", "yyy-supported" and "notify-max-xxx-supported"
defined in column 2 of Table 1. Note "xxx" stands for the same
string in each case and "yyy" stands for some other string.
3. If a Printer supports "notify-xxx" in column 1 of Table 1, then
the Printer MUST support all associated attributes specified in
column 2 of Table 1. For example, Table 1 shows that if the
Printer supports "notify-events", it MUST support "notify-events-
default", "notify-events-supported" and "notify-max-events-
supported".
4. If a Printer does not support "notify-xxx" in column 1 of Table 1,
then the Printer MUST NOT support any associated "notify-yyy"
attributes specified in column 2 of Table 1. For example, Table 1
shows that if the Printer doesn’t support "notify-events", it MUST
NOT support "notify-events-default", "notify-events-supported" and
"notify-max-events-supported". Note this rule does not apply to
attributes whose names do not start with the string "notify-" and
are thus defined in another object and used by other attributes.
5. Most "notify-xxx" attributes have a corresponding "yyy-supported"
attribute that specifies the supported values for "notify-xxx".
Column 2 of Table 1 specifies the name of each "yyy-supported"
attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used
when "yyy-supported" is "notify-xxx-supported".
6. Some "notify-xxx" attributes have a corresponding "notify-xxx-
default" attribute that specifies the value for "notify-xxx" if
the client does not supply it. Column 2 of Table 1 specifies the
name of each "notify-xxx-default" attribute. The naming rules of
IPP/1.1 (see [RFC2911]) are used.
If a client wishes to present an end user with a list of supported
values from which to choose, the client SHOULD query the Printer for
its supported value attributes. The client SHOULD also query the
default value attributes. If the client then limits selectable
values to only those values that are supported, the client can
guarantee that the values supplied by the client in the create
request all fall within the set of supported values at the Printer.
When querying the Printer, the client MAY enumerate each attribute by
name in the Get-Printer-Attributes Request, or the client MAY just
supply the ’subscription-template’ group name in order to get the
complete set of supported attributes (both supported and default
attributes - see section 11.2.3).
5.2. Rules for Processing Subscription Template Attributes
This section defines a detailed set of rules that a Printer follows
when it processes Subscription Template Attributes in a Subscription
Creation Request. These rules are similar to the rules for
processing Operation attributes in [RFC2911]. That is, the Printer
may or may not support an attribute and a client may or may not
supply the attribute. Some combinations of these cases are OK.
Others return warnings or errors, and perhaps a list of unsupported
attributes.
A Printer MUST implement the following behavior for processing
Subscription Template Attributes in a Subscription Creation Request:
1. If a client supplies a "notify-xxx" attribute from column 1 of
Table 1 and the Printer supports it and its value, the Printer
MUST populate the attribute on the created Subscription Object.
2. If a client supplies a "notify-xxx" attribute from column 1 of
Table 1 and the Printer doesn’t support it or its value, the
Printer MUST NOT populate the attribute on the created
Subscription Object with it. The Printer MUST do one of the
following:
a) If the value of the "notify-xxx" attribute is unsupported, the
Printer MUST return the attribute with its value in the
Subscription Attributes Group of the response.
b) If "notify-xxx" is an unsupported attribute, the Printer MUST
return the attribute in the Subscription Attributes Group of
the response with the ’unsupported’ out-of-band value.
Note: The rules of this step are the same as for Unsupported
Attributes [RFC2911] section 3.1.7. except that the unsupported
attributes are returned in the Subscription Attributes Group
rather than the Unsupported Attributes Group because Subscription
Creation Operations can create more than one Subscription Object).
3. If a client is REQUIRED to supply a "notify-xxx" attribute from
column 1 of Table 1 and the Printer doesn’t support the supplied
value, the Printer MUST NOT create a Subscription Object. The
rules for Unsupported Attributes in step #2 still apply.
4. If a client does not supply a "notify-xxx" attribute from column 1
of Table 1 and the attribute is REQUIRED for the client to supply,
the Printer MUST reject the Subscription Creation Operation
(including Job Creation operations) without creating a
Subscription Object, and MUST return in the response:
a) the status code ’client-error-bad-request’ AND
b) no Subscription Attribute Groups.
5. If a client does not supply a "notify-xxx" attribute from column 1
of Table 1 that is OPTIONAL for the client to supply, and column 2
of Table 1 either:
a) specifies a "notify-xxx-default" attribute, the Printer MUST
behave as if the client had supplied the "notify-xxx-default"
attribute (see step #1) and populate the Subscription object
with the value of the "notify-xxx-default" attribute as part of
the Subscription Creation operation (unlike Job Template
attributes where the Printer does not populate the Job object
with defaults - see [RFC2911]) OR
b) does not specify a "notify-xxx-default" attribute, the Printer
MUST populate the "notify-xxx" attribute on the Subscription
Object according to the definition of the "notify-xxx"
attribute in a section 5.3. For some attributes, the "notify-
xxx" is populated with the value of some other attribute, and
for others, the "notify-xxx" is NOT populated on the
Subscription object at all.
6. A Printer MUST create a Subscription Object for each Subscription
Template Attributes group in a request unless the Printer:
a) encounters some attributes in a Subscription Template
Attributes Group that require the Printer not to create the
Subscription Object OR
b) would create a Per-Job Subscription Object when it doesn’t have
space for another Per-Job Subscription Object OR
c) would create a Per-Printer Subscription Object when it doesn’t
have space for another Per-Printer Subscription Object.
7. A response MUST contain one Subscription Attributes Group for each
Subscription Template Attributes Group in the request (and in the
same order) whether the Printer creates a Subscription Object from
the Subscription Template Attributes Group or not. However, the
attributes in each Subscription Attributes Group can be in any
order.
8. The Printer MUST populate each Subscription Attributes Group of
the response such that each contains:
a) the "notify-subscription-id" attribute (see section 5.4.1), if
and only if the Printer creates a Subscription Object.
b) the "notify-lease-duration" attribute (see section 5.3.8), if
and only if the Printer creates a Per-Printer Subscription
Object. The value of this attribute is the value of the
Subscription Object’s "notify-lease-duration" attribute. This
value MAY be different from the client-supplied value (see
section 5.3.8). If a client supplies this attribute in the
creation of a Per-Job Subscription Object, it MUST appear in
this group with the out-of-band value ’unsupported’ to indicate
that the Printer doesn’t support it in this context.
c) all of the unsupported Subscription Template Attributes from
step #2. Note, they are not returned in the Unsupported
Attributes Group in order to separate the unsupported
attributes for each Subscription Object.
d) the "notify-status-code" attribute if the Printer does not
create the Subscription Object or if there are unsupported
attributes from step #2. The possible values of the "notify-
status-code" attribute are shown below (see section 13 for more
details). The Printer returns the first value in the list
below that describes the status.
’client-error-uri-scheme-not-supported’: the Subscription
Object was not created because the scheme of the "notify-
recipient-uri" attribute is not supported. See section 13.1
for more details about this status code. See step #3 in
this section for the case that causes this error, and the
resulting step #6a) that causes the Printer not to create
the Subscription Object.
’client-error-attributes-or-values-not-supported’: the
Subscription Object was not created because the method of
the "notify-pull-method" attribute is not supported. See
section 13.1 for more details about this status code. See
step #3 in this section for the case that causes this error,
and the resulting step #6a) that causes the Printer not to
create the Subscription Object.
’client-error-too-many-subscriptions’: the Subscription
Object was not created because the Printer has no space for
additional Subscription Objects. The client MAY try again
later. See section 13.3 for more details about this status
code. See steps #6b) and #6c) in this section for the cases
that causes this error.
’successful-ok-too-many-events’: the Subscription Object was
created without the "notify-events" values included in this
Subscription Attributes Group because the "notify-events"
attribute contains too many values. See section 13.4 for
more details about this status code. See step #2 in this
section and section 5.3.3 for the cases that cause this
status code.
’successful-ok-ignored-or-substituted-attributes’: the
Subscription Object was created but some supplied
Subscription Template Attributes are unsupported. These
unsupported attributes are also in the Subscription
Attributes Group. See section 13.5 for more details about
this status code. See step #2 in this section for the cases
that cause this status code.
9. The Printer MUST validate all Subscription Template Attributes and
MUST return all unsupported attributes and values in the
corresponding Subscription Attributes Group of the response (see
step #2) unless it determines that it could not create additional
Subscription Objects because of condition #6b) or condition #6c).
Then, the Printer NEED NOT validate these additional Subscription
Template Attributes and the client MUST NOT expect to find
unsupported attributes from step #2 in such additional
Subscription Attribute Groups.
5.3. Subscription Template Attributes
This section contains the Subscription Template Attributes defined
for the Subscription and Printer objects.
Table 1 below shows the Subscription Template Attributes and has two
columns:
- Attribute in Subscription Object: the name and attribute syntax of
each Subscription Object Attribute that is a Subscription Template
Attribute
- Default and Supported Printer Attributes: the default attribute
and supported Printer attributes that are associated with the
attribute in column 1.
The "notify-recipient-uri" attribute is for use with Push Delivery
Methods. The "notify-pull-method" attribute is for use with Pull
Delivery Methods.
For Push Delivery Methods, a Printer MUST support all attributes in
Table 1 below except for "notify-pull-method" and "notify-attributes"
(and "notify-pull-method-supported" and "notify-attributes-
supported"). For Pull Delivery Methods, a Printer MUST support all
attributes in Table 1 below except for "notify-recipient-uri" and
"notify-attributes" (and "notify-schemes-supported" and "notify-
attributes-supported"). If a Printer supports both Push and Pull
Delivery Methods, then it MUST support both "notify-recipient-uri"
and "notify-pull-method" attributes.
For Pull Delivery Methods, a client MUST supply "notify-recipient-
uri" and MAY omit any of the rest of the attributes in column 1 of
Table 1 in a Subscription Creation Request. For Push Delivery
Methods, a client MUST supply "notify-pull-method" and MAY omit any
of the rest of the attributes in column 1 of Table 1 in a