Subscription Creation Request. A client MUST NOT supply both
"notify-recipient-uri" and "notify-pull-method" attributes in the
same Subscription Creation Request.
Note: The Default and Supported Printer attributes listed in column
2 of Table 1 do not have separate sections in this specification
defining their semantics. Instead, the section for the corresponding
Subscription Object attribute (column 1 of Table 1) contains the
semantics of these Printer attributes. This approach follows the
precedence of the Job Template attributes in section 4.2 of [RFC2911]
where the corresponding "xxx-default" and "xxx-supported" Printer
attributes are defined in the same section as the "xxx" Job
attribute.
Table 1 - Subscription Template Attributes
Attribute in Subscription Default and Supported Printer
Object Attributes
notify-recipient-uri (uri) * notify-schemes-supported (1setOf
uriScheme)
notify-pull-method (type2 notify-pull-method-supported (1setOf
keyword) ** type2 keyword)
notify-events (1setOf type2 notify-events-default (1setOf type2
keyword) keyword)
notify-events-supported (1setOf type2
keyword)
notify-max-events-supported
(integer(2:MAX))
notify-attributes (1setOf notify-attributes-supported (1setOf
type2 keyword) type2 keyword)
notify-user-data
(octetString(63))
notify-charset (charset) charset-supported (1setOf charset)
notify-natural-language generated-natural-language-supported
(naturalLanguage) (1setOf naturalLanguage)
notify-lease-duration notify-lease-duration-default
(integer(0:MAX)) (integer(0:67108863))
notify-lease-duration-supported
(1setOf (integer(0: 67108863) |
rangeOfInteger(0:67108863)))
notify-time-interval
(integer(0:MAX))
* "notify-recipient-uri" is for Push Delivery Methods only.
** "notify-pull-method" is for Pull Delivery Methods only.
5.3.1. notify-recipient-uri (uri)
This attribute’s value is a URL, which is a special case of a URI.
Its value consists of a scheme and an address. The address specifies
the Notification Recipient and the scheme specifies the Push Delivery
Method for each Event Notification associated with this Subscription
Object.
If a Printer supports any Push Delivery Methods, a Printer MUST
support this attribute and return the value as supplied by the client
(no case conversion or other canonicalization) in any operation
response that includes this attribute.
For a Push Delivery Method, a client MUST supply this attribute in a
Subscription Creation Operation. Thus there is no need for a default
Printer attribute.
The URI scheme of the value of this attribute on a Subscription
object MUST be a value of the "notify-schemes-supported (1setOf
uriScheme)" Printer attribute (see section 5.3.1.1). Note: According
to [RFC2396] the ":" terminates the scheme and so is not part of the
scheme. Therefore, values of the "notify-schemes-supported" Printer
attribute do not include the ":" character.
If the client supplies an unsupported scheme in the value of this
attribute, then the Printer MUST NOT create the Subscription Object
and MUST return the "notify-status-code" attribute with the ’client-
error-uri-scheme-not-supported’ value in the Subscription Attributes
Group in the response.
5.3.1.1. notify-schemes-supported (1setOf uriScheme)
This attribute contains the URI schemes supported in the "notify-
recipient-uri" Subscription Template attribute. See sections 5.1 and
5.2 for the behavior of "xxx-supported" Subscription Template Printer
attributes.
5.3.2. notify-pull-method (type2 keyword)
This attribute’s value is a type2 keyword indicating which Pull
Delivery Method is to be used.
Since a Printer MUST support the ’ippget’ Pull Delivery Method
[RFC3996] (see section 15), a Printer MUST support this attribute and
return the value as supplied by the client in any operation response
that includes this attribute.
For a Pull Delivery Method, a client MUST supply this attribute in a
Subscription Creation Operation. Thus there is no need for a default
Printer attribute.
The keyword value of this attribute on a Subscription object MUST be
a value of the "notify-pull-method-supported (1setOf type2 keyword)"
Printer attribute.
If the client supplies an unsupported method in the value of this
attribute, then the Printer MUST NOT create the Subscription Object
and MUST return the "notify-status-code" attribute with the ’client-
error-attributes-or-values-not-supported’ value in the Subscription
Attributes Group in the response.
5.3.2.1. notify-pull-method-supported (1setOf type2 keyword)
See sections 5.1 and 5.2 for the behavior of "xxx-supported"
Subscription Template Printer attributes.
5.3.3. notify-events (1setOf type2 keyword)
This attribute contains a set of Subscribed Events. When an Event
occurs and it "matches" a value of this attribute, the Printer
delivers an Event Notification using information in the Subscription
Object. The details of "matching" are described subsection 5.3.3.5.
A Printer MUST support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in
Subscription Creation Operation, the Printer MUST populate this
attribute on the Subscription Object with its "notify-events-default"
attribute value.
Each keyword value of this attribute on a Subscription Object MUST be
a value of the "notify-events-supported (1setOf type2 keyword)"
Printer attribute.
The number of values of this attribute MUST NOT exceed the value of
the "notify-max-events-supported" attribute. A Printer MUST support
at least 2 values per Subscription Object. If the number of values
supplied by a client in a Subscription Creation Operation exceeds the
value of this attribute, the Printer MUST treat extra values as
unsupported values and MUST use the value of ’successful-ok-too-
many-events’ for the "notify-status-code" attribute in the
Subscription Attributes Group of the response.
5.3.3.1. notify-events-default (1setOf type2 keyword)
See sections 5.1 and 5.2 for the behavior of "xxx-default"
Subscription Template Printer attributes.
5.3.3.2. notify-events-supported (1setOf type2 keyword)
See sections 5.1 and 5.2 for the behavior of "xxx-supported"
Subscription Template Printer attributes.
5.3.3.3. notify-max-events-supported (integer(2:MAX))
This attribute specified the maximum number of events that the
Printer supports for the "notify-events" Subscription Template
attribute. See sections 5.1 and 5.2 for the behavior of "xxx-
supported" Subscription Template Printer attributes.
5.3.3.4. Standard Values for Subscribed Events
Each value of this attribute is a keyword and it specifies a
Subscribed Event that represents certain changes. Some keywords
represent a subset of changes of another keyword, e.g., ’job-
completed’ is an Event value which is a sub-value of ’job-state-
change’. See section 5.3.3.5 for the case where this attribute
contains both a value and a sub-value.
The values in this section are divided into three categories: No
Events, Job Events and Printer Events.
A Printer MUST support the Events indicated as "REQUIRED" and MAY
support the Events indicated as "OPTIONAL".
5.3.3.4.1. No Events
The standard and only keyword value for No Events is:
’none’: REQUIRED - no Event Notifications for any Events. As the
sole value of "notify-events-supported", this value means that the
Printer does not support the delivery of Event Notifications. As
the sole value of "notify-events-default", this value means that a
client MUST specify the "notify-events" attribute in order for a
Subscription Creation Operation to succeed. If the Printer
receives this value as the sole value of a Subscription Creation
Operation, it does not create a Subscription Object. If a Printer
receives this value with other values of a Subscription Creation
Operation, the Printer MUST treat this value as an unsupported
value.
5.3.3.4.2. Subscribed Printer Events
The standard keyword values for Subscribed Printer Events are:
’printer-state-changed’: REQUIRED - the Printer changed state from
any state to any other state. Specifically, the value of the
Printer’s "printer-state", "printer-state-reasons" or "printer-
is-accepting-jobs" attributes changed.
This Subscribed Event value has the following sub-values:
’printer-restarted’ and ’printer-shutdown’. A client can listen
for any of these sub-values if it doesn’t want to listen to all
printer-state changes:
’printer-restarted’: OPTIONAL - when the printer is powered
up.
’printer-shutdown’: OPTIONAL - when the device is being
powered down.
’printer-stopped: REQUIRED - when the printer stops printing,
i.e., the value of the "printer-state" Printer attribute
becomes ’stopped’.
’printer-config-changed’: OPTIONAL - when the configuration of a
Printer has changed, i.e., the value of the "printer-message-
from-operator" or any "configuration" Printer attribute has
changed. A "configuration" Printer attribute is an attribute
which can change value because of some human interaction either
direct or indirect, and which is not covered by one of the other
Events in this section. Examples of "configuration" Printer
attributes are any of the Job Template attributes, such as "xxx-
supported", "xxx-ready" and "xxx-default". The client has to
perform a Get-Printer-Attributes to find out the new values of
these changed attributes. This Event is useful for GUI clients
and drivers to update the available printer capabilities to the
user.
This Event value has the following sub-values: ’printer-media-
changed’ and ’printer-finishings-changed’. A client can listen
for any of these sub-values if it doesn’t want to listen to all
printer-configuration changes:
’printer-media-changed’: OPTIONAL - when the media loaded on
a printer has been changed, i.e., the "media-ready"
attribute has changed. This Event includes two cases: an
input tray that goes empty and an input tray that receives
additional media of the same type or of a different type.
The client must check the "media-ready" Printer attribute
(see [RFC2911] section 4.2.11) separately to find out what
changed.
’printer-finishings-changed’: OPTIONAL - when the finisher on
a printer has been changed, i.e., the "finishings-ready"
attribute has changed. This Event includes two cases: a
finisher that goes empty and a finisher that is refilled
(even if it is not full). The client must check the
"finishings-ready" Printer attribute separately to find out
what changed.
’printer-queue-order-changed’: OPTIONAL - the order of jobs in the
Printer’s queue has changed, so that an application that is
monitoring the queue can perform a Get-Jobs operation to determine
the new order. This Event does not include when a job enters the
queue (the ’job-created’ Event covers that) and does not include
when a job leaves the queue (the ’job-completed’ Event covers
that).
5.3.3.4.3. Subscribed Job Events
The standard keyword values for Subscribed Job Events are:
’job-state-changed’: REQUIRED - the job has changed from any state
to any other state. Specifically, the Printer delivers this Event
whenever the value of the "job-state" attribute or "job-state-
reasons" attribute changes. When a Job is removed from the Job
Retention or Job History phases (see [RFC2911] section 4.3.7.1),
no Event is generated.
This Event value has the following sub-values: ’job-created’,
’job-completed’ and ’job-stopped’. A client can listen for any of
these sub-values if it doesn’t want to listen to all ’job-state
changes’.
’job-created’: REQUIRED - the Printer has accepted a Job
Creation operation, a Restart-Job operation [RFC2911], or any
job operation that creates a Job object from an existing Job
object. The Printer populates the job’s "time-at-creation"
attribute value (see [RFC2911] section 4.3.14.1). The Printer
puts the job in the ’pending’, ’pending-held’ or ’processing’
states.
’job-completed’: REQUIRED - the job has reached one of the
completed states, i.e., the value of the job’s "job-state"
attribute has changed to: ’completed’, ’aborted’, or
’canceled’. The Job’s "time-at-completed" and "date-time-at-
completed" (if supported) attributes are set (see [RFC2911]
section 4.3.14). When a Job completes, a Notification
Recipient MAY query the Job using the Get-Job-Attributes
operation. To allow such a query, the Printer retains the Job
in the Job Retention and/or the Job History phases (see
[RFC2911] section 4.3.7.1) for a suitable amount of time that
depends on implementation and the Delivery Methods supported.
The Printer also delivers this Event when a Job is removed with
the Purge-Job operation (see [RFC2911] section 3.2.9). In this
case, the Event Notification MUST report the ’job-state’ as
’canceled’ and the Job object is no longer present for query.
’job-stopped: OPTIONAL - when the job stops printing, i.e.,
the value of the "job-state" Job attribute becomes
’processing-stopped’.
’job-config-changed’: OPTIONAL - when the configuration of a job has
changed, i.e., the value of the "job-message-from-operator" or any
of the "configuration" Job attributes have changed. A
"configuration" Job attribute is an attribute that can change
value because of some human interaction either direct or indirect.
Examples of "configuration" Job attributes are any of the job
template attributes and the "job-name" attribute. The client
performs a Get-Job-Attributes to find out the new values of the
changed attributes. This Event is useful for GUI clients and
drivers to update the job information to the user.
’job-progress’: OPTIONAL - when the Printer has completed Printing a
sheet. See the separate [RFC3381] specification for additional
attributes that a Printer MAY deliver in an Event Notification
caused by this Event. The "notify-time-interval" attribute
affects this Event by causing the Printer NOT to deliver an Event
Notification every time a ’job-progress’ Events occurs. See
section 5.3.9 for full details.
5.3.3.5. Rules for Matching of Subscribed Events
When an Event occurs, the Printer MUST find each Subscription object
whose "notify-events" attribute "matches" the Event. The rules for
"matching" of Subscribed Events are described separately for Printer
Events and for Job Events. This section also describes some special
cases.
5.3.3.5.1. Rules for Matching of Printer Events
Given that the Printer causes Printer Event E to occur, for each
Per-Job or Per-Printer Subscription S in the Printer, if E equals a
value of this attribute in S or E is a sub-value of a value of this
attribute in S, the Printer MUST generate an Event Notification.
Consider the example. There are three Subscription Objects each with
the Subscribed Printer Event ’printer-state-changed’. Subscription
Object A is a Per-Printer Subscription Object. Subscription Object B
is a Per-Job Subscription Object for Job 1, and Subscription Object C
is a Per-Job Subscription Object for Job 2. When the Printer enters
the ’stopped’ state, the Printer delivers an Event Notification to
the Notification Recipients of Subscription Objects A, B, and C
because this is a Printer Event. Note if Job 1 has already
completed, the Printer would not deliver an Event Notification for
its Subscription Object, even if Job 1 is retained in the Job
Retention and/or the Job History phases (see [RFC2911] section
4.3.7.1).
5.3.3.5.2. Rules for Matching of Job Events
Given that Job J causes Job Event E to occur:
1. For each Per-Printer Subscription S in the Printer, if E equals a
value of this attribute in S or E is a sub-value of a value of
this attribute in S, the Printer MUST generate an Event
Notification.
2. For each Per-Job Subscription S associated with Job J, if E equals
a value of this attribute in S or E is a sub-value of a value of
this attribute in S, the Printer MUST generate an Event
Notification.
3. For each Per-Job Subscription S that is NOT associated Job J, if E
equals a value of this attribute in S or E is a sub-value of a
value of this attribute in, the Printer MUST NOT generate an Event
Notification from S.
Consider the example: There are three Subscription Objects listening
for the Job Event ’job-completed’. Subscription Object A is a Per-
Printer Subscription Object. Subscription Object B is a Per-Job
Subscription Object for Job 1, and Subscription Object C is a Per-Job
Subscription Object for Job 2. In addition, Per-Printer Subscription
Object D is listening for the Job Event ’job-state-changed’. When
Job 1 completes, the Printer delivers an Event Notification to the
Notification Recipient of Subscription Object A (because it is Per-
Printer) and Subscription Object B because it is a Per-Job
Subscription Object associated with the Job generating the Event.
The Printer also delivers an Event Notification to the Notification
Recipient of Subscription Object D because ’job-completed’ is a sub-
value of ’job-state-changed’ - the value that Subscription Object D
is listening for. The Printer does not deliver an Event Notification
to the Notification Recipients of Subscription Object C because it is
a Per-Job Subscription Object associated with some Job other than the
Job generating the Event.
5.3.3.5.3. Special Cases for Matching Rules
This section contains two rules for the special case where a single
Event produces multiple Event Notifications destined for the same
Notification Recipient. These two rules clarify whether a Printer
should send multiple Event Notifications or consolidate them into a
single Event Notification.
If an Event matches Subscribed Events in two different Subscription
Objects and the Printer would deliver two identical Event
Notifications (except for the "notify-subscription-id" attribute) to
the same Notification Recipient using the same Delivery Method, the
Printer MUST deliver both Event Notifications. That is, the Printer
MUST NOT try to consolidate seemingly identical Event Notifications
that occur in separate Subscription objects. Incidentally, the
Printer MUST NOT reject Subscription Creation Operations that would
create this scenario.
Consider the example: At the time a Job completes, there are two
Per-Printer Subscription Objects A and B with the same Notification
Recipient R. Subscription Object A has the Subscribed Job Event
’job-state-changed’. Subscription Object B has the Subscribed Job
Event ’job-completed’. Both Subscription Objects match the Event
’job-completed’. The Printer delivers two Event Notifications to the
Notification Recipient R. One with the value of ’job-state-changed’
for the "notify-subscribed-event" attribute and the other with the
value of ’job-completed’ for the "notify-subscribed-event"
attribute.
If an Event matches two Subscribed Events in a single Subscription
object (e.g., a value and its sub-value), a Printer MAY deliver one
Event Notification for each matched value in the Subscription Object
or it MAY deliver only a single Event Notification. The rules in
sections 5.3.3.5.1 and 5.3.3.5.2 are purposefully flexible about the
number of Event Notifications sent when Event E matches two or more
values in a Subscription Object.
Consider the example: At the time a Job completes, a Subscription
Object A has two Subscribed Job Events ’job-state-changed’ and ’job-
completed’. Both Subscribed Job Events match the Event ’job-
completed’. The Printer delivers either one or two Event
Notifications to the Notification Recipient of Subscription Object A,
depending on implementation. If it delivers two Event Notifications,
one has the value of ’job-state-changed’ for the "notify-
subscribed-event" attribute, and the other has the value of ’job-
completed’ for the "notify-subscribed-event" attribute. If it
delivers one Event Notification, it has the value of either ’job-
state-changed’ or ’job-completed’ for the "notify-subscribed-event"
attribute, depending on implementation. The algorithm for choosing
such a value is implementation dependent.
5.3.4. notify-attributes (1setOf type2 keyword)
This attribute contains a set of attribute names. When a Printer
delivers a Machine Consumable Event Notification, it includes a fixed
set of attributes (see section 9.1). If this attribute is present
and the Event Notification is Machine Consumable, the Printer also
includes the attributes specified by this attribute.
A Printer MAY support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in
Subscription Creation Operation or the Printer does not support this
attribute, the Subscription Object either (1) MAY contain the
"notify-attributes" attribute with a ’none’ value or (2) NEED NOT
contain the attribute at all. There is no "notify-attributes-
default" Printer attribute.
Each keyword value of this attribute on a Subscription Object MUST be
a value of the "notify-attributes-supported (1setOf type2 keyword)"
Printer attribute (see section 5.3.4.1). The "notify-attributes-
supported" MAY contain any Printer attribute, Job attribute or
Subscription Object attribute that the Printer supports in an Event
Notification. It MUST NOT contain any of the attributes in Section
9.1 that a Printer automatically puts in an Event Notification; it
would be redundant. If a client supplies an attribute in Section
9.1, the Printer MUST treat it as an unsupported attribute value of
the "notify-attributes" attribute.
The following rules apply to each keyword value N of the "notify-
attributes" attribute: If the value N names:
a) a Subscription attribute, the Printer MUST use the attribute N in
the Subscription Object that is being used to generate the Event
Notification.
b) a Job attribute and the Printer is generating an Event
Notification from a Per-Job Subscription Object S, the Printer
MUST use the attribute N in the Job object associated with S.
c) a Job attribute and the Printer is generating an Event
Notification from a Per-Printer Subscription Object and the Event
is:
- a Job Event, the Printer MUST use the attribute N in the Job
object that caused the Event.