the "get-notify-interval" operation attribute to indicate when
the client SHOULD try again.
2. If the Notification Recipient did not request Event Wait Mode
("notify-wait-mode" = ’false’ or omitted), the Printer MUST
immediately return whatever Event Notifications it currently
holds in the requested Subscription object(s) and MUST return the
"notify-get-interval" operation attribute with the number of
seconds from now, at which the Notification Recipient SHOULD
repeat the Get-Notifications Request to get future Event
Notifications.
3. If the Notification Recipient requested Event Wait Mode
("notify-wait-mode" = ’true’), the Printer MUST immediately
return whatever Event Notifications it currently holds in the
requested Subscription object(s) and MUST continue to return
Event Notifications as they occur until all the requested
Subscription Objects are canceled. A Subscription Object is
canceled either via the Cancel-Subscription operation or by the
Printer (e.g., the Subscription Object is canceled when the
associated Job completes and is no longer in the Job Retention or
Job History phase; see the "ippget-event-life (integer(15:MAX))"
attribute discussion in section 8.1).
However, the Printer MAY decide to terminate Event Wait Mode at
any time, including in the first response. In this case, the
Printer MUST return the "notify-get-interval" operation
attribute. This attribute indicates that the Printer wishes to
leave Event Wait Mode and the number of seconds in the future
that the Notification Recipient SHOULD try the Get-Notifications
operation again. The Notification Recipient MUST accept this
response and MUST disconnect. If the Notification Recipient does
not disconnect, the Printer SHOULD do so.
From the Notification Recipient’s view, the response appears as an
initial burst of data, which includes the Operation Attributes Group
and one Event Notification Attributes Group per Event Notification
that the Printer is holding. After the initial burst of data, if the
Notification Recipient has selected the Event Wait Mode option to
wait for additional Event Notifications, the Notification Recipient
receives occasional Event Notification Attribute Groups. Proxy
servers may delay some Event Notifications or cause time-outs to
occur. The client MUST be prepared to perform the Get-Notifications
operation again when time-outs occur.
Each attribute is encoded by using the IPP rules for encoding
attributes [RFC2910] and MAY be encoded in any order. Note: the
Get-Jobs response in [RFC2911] acts as a model for encoding multiple
groups of attributes. See section 11 for the encoding and transport
rules.
The following groups of attributes are part of the Get-Notifications
Response:
Group 1: Operation Attributes
Status Message: In addition to the REQUIRED status code returned
in every response, the response OPTIONALLY includes a "status-
message" (text(255)) and/or a "detailed-status-message"
(text(MAX)) operation attribute, as described in [RFC2911],
sections 13 and 3.1.6.
The Printer can return any status codes defined in [RFC2911].
If the status code is not ’successful-xxx’, the Printer MUST
NOT return any Event Notification Attribute groups. The
following are descriptions of the important status codes:
successful-ok: The response contains all Event Notification
associated with the specified subscription-ids that had
been supplied in the "notify-subscription-ids" operation
attribute in the request. If the requested Subscription
Objects have no associated Event Notification, the
response MUST contain zero Event Notifications.
successful-ok-events-complete: Indicates when this return
is the last return for all Subscription objects that
match the request, whether or not Event Notifications are
returned. This condition occurs for Event Wait Mode with
Notification Recipients waiting for responses when (1)
the Subscription Object is canceled with a Cancel-
Subscription operation, (2) the Subscription Object is
deleted, when the Per-Printer Subscription lease time
expires, or (3) the ’job-completed’ event occurs for a
Per-Job Subscription. This condition also occurs for a
Get-Notifications request that a Notification Recipient
makes after the job completes, but before the Event Life
expires. See section 10.1.
client-error-not-found: The Printer has no Subscription
Objects whose "notify-subscription-id" attribute equals
any of the values of the "notify-subscription-ids"
operation attribute supplied, or the identified
Subscription Object does not contain the "notify-pull-
method" attribute with the ’ippget’ keyword value.
server-error-busy: The Printer is too busy to accept this
operation. The Printer SHOULD return the "notify-get-
interval" operation attribute in the Operation Attributes
of the response; then the Notification Recipient SHOULD
wait for the number of seconds specified by the "notify-
get-interval" operation attribute before performing this
operation again. If the "notify-get-interval" Operation
Attribute is not present, the Notification Recipient
SHOULD use the normal network back-off algorithms to
determine when to perform this operation again.
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes, as described in [RFC2911], section 3.1.4.2.
The Printer MUST use the values of "notify-charset" and
"notify-natural-language", respectively, from one Subscription
Object associated with the Event Notifications in this
response.
Normally, there is only one matched Subscription Object, or the
value of the "notify-charset" and "notify-natural-language"
attributes is the same in all Subscription Objects. If not,
the Printer MUST pick one Subscription Object from which to
obtain the value of these attributes. The algorithm for
picking the Subscription Object is implementation dependent.
The choice of natural language is not critical, because ’text’
and ’name’ values can override the "attributes-natural-
language" operation attribute. The Printer’s choice of charset
is critical because a bad choice may leave it unable to send
some ’text’ and ’name’ values accurately.
5.2.1. notify-get-interval (integer(0:MAX))
The value of this operation attribute is the number of seconds that
the Notification Recipient SHOULD wait before trying the Get-
Notifications operation again. The Printer MUST return this
operation attribute if (1) it is too busy to return events, (2) the
Notification Recipient client did not request Event Wait Mode, or (3)
the Printer is terminating Event Wait Mode. The client MUST accept
this attribute and SHOULD reissue the Get-Notifications operation
(with or without "notify-wait" = ’true’) at the indicated number of
seconds in the future in order to get more Event Notifications This
value is intended to help the client be a good network citizen.
The value of this attribute MUST be at least as large as that of the
Printer’s "ippget-event-life" Printer Description attribute (see
section 8.1). The Printer MAY return a value that is larger than
that of the "ippget-event-life" Printer Description attribute
provided that the Printer increases the Event Life for this
Subscription object so that Notification Recipients taking account of
the larger value and polling with a longer interval will not miss
events. Note: Implementing such an algorithm requires some hidden
attributes in the Subscription object that are IMPLEMENTATION
DEPENDENT.
If the Printer wants to remain in Event Wait Mode, then the Printer
MUST NOT return this attribute in the response.
Here is a complete table of combinations of "notify-wait", "status-
code", "notify-get-interval", and Event Notification Attributes
Groups for Get-Notification initial (Wait and No Wait) Responses and
subsequent Event Wait Mode Responses (which may stay in Event Wait
Mode or may request the Notification Recipient to leave Event Wait
Mode):
Table 2. Combinations of "notify-wait", "status-code", and
"notify-get-interval"
Client sends: Printer returns: Printer Event
returns: Notification
"notify-wait" "status-code" "notify-get- Attribute
interval" Groups
1. ’false’* ’successful-ok’ MUST return N maybe
2. ’false’* ’not-found’ MUST NOT MUST NOT
3. ’false’* ’busy’ MUST return N MUST NOT
4. ’false’* ’events- MUST NOT ’job-
complete’ completed’
5. ’true’ ’successful-ok’ MUST NOT MUST
6. ’true’ ’successful-ok’ MUST return N maybe
7. ’true’ ’not-found’ MUST NOT MUST NOT
8. ’true’ ’busy’ MUST return N MUST NOT
9. ’true’ ’events- MUST NOT ’job-
complete’ completed’ or
maybe other
* ’false’ or client omits the "notify-wait" attribute.
Explanation:
1-4: Client does not request Event Wait Mode.
5-9: Client requests Event Wait Mode.
2,7: Subscription object not found, or was canceled earlier;
client should NOT try again.
3,8: Server busy, tells client to try later; client should try
again in N seconds.
4: Client polled after job completed, but before Event Life
expired, and got the ’job-completed’ event, so the client
shouldn’t bother trying again; client should NOT try
again later.
5: Printer returns one or more Event Notifications and is OK
to stay in Event Wait Mode; the client waits for more
Event Notifications to be returned.
6: Printer wants to leave Event Wait mode. Can happen on
the first response (with or without Event Notifications)
or happen on a subsequent response with or without Event
Notifications; the client SHOULD try again in N seconds.
9: Either (1) the printer returns ’job-completed’ event, or
(2) the Subscription Object was canceled by either a
Cancel-Job or a Per-Printer Subscription expired without
being renewed. For case (1), at least one Event
Notification MUST be returned; for case (2), it is
unlikely that any Event Notifications are returned, and
the client should NOT try again.
5.2.2. printer-up-time (integer(1:MAX))
The value of this attribute is the Printer’s "printer-up-time"
attribute at the time when the Printer sends this response. The
Printer MUST return this attribute. Because each Event Notification
also contains the value of this attribute when the event occurred,
the value of this attribute lets a Notification Recipient know when
each Event Notification occurred relative to the time of this
response.
Group 2: Unsupported Attributes
See [RFC2911], section 3.1.7, for details on returning
Unsupported Attributes.
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
[RFC3995]). The matched Event Notifications are all un-expired
Event Notifications associated with the matched Subscription
Objects and MUST follow the "Event Notification Ordering"
requirements for Event Notifications within a Compound Event
Notification specified in [RFC3995] section 9. In other words,
the Printer MUST order these Event Notification groups in
ascending time stamp (and sequence number) order for a
Subscription object. If Event Notifications for multiple
Subscription objects are being returned, the Notification
Events for the next Subscription object follow in ascending
time stamp order, etc.
Each Event Notification Group MUST contain all of attributes
specified in section 9.1 ("Content of Machine Consumable Event
Notifications") of [RFC3995], with exceptions denoted by
asterisks in the tables below.
The tables below are identical to those in section 9.1
("Content of Machine Consumable Event Notifications") of
[RFC3995], except that each cell in the "Sends" column is a
"MUST".
If more than one Event Notification is being returned and the
status of each is not the same, then the Printer MUST return a
"notify-status-code" attribute in each Event Notification
Attributes group to indicate the differing status values.
For an Event Notification for all Events, the Printer includes
the attributes shown in Table 3.
Table 3. Attributes in Event Notification Content
Source Value Sends Source Object
notify-subscription-id (integer(1:MAX)) MUST Subscription
notify-printer-uri (uri) MUST Subscription
notify-subscribed-event (type2 keyword) MUST Event
Notification
printer-up-time (integer(1:MAX)) * MUST Printer
printer-current-time (dateTime) MUST ** Printer
notify-sequence-number (integer (0:MAX)) MUST Subscription
notify-charset (charset) MUST Subscription
notify-natural-language (naturalLanguage) MUST Subscription
notify-user-data (octetString(63)) MUST *** Subscription
notify-text (text) MUST Event
Notification
attributes from the "notify-attributes" MUST **** Printer
attribute
attributes from the "notify-attributes" MUST **** Job
attribute
attributes from the "notify-attributes" MUST **** Subscription
attribute
* As specified in [RFC3995] section 9, the value of the
"printer-up-time" attribute sent in each Event Notification
MUST be the time at which the Event occurred, not the time at
which the Event Notification was sent.
** The Printer MUST send the "printer-current-time" attribute
if and only if it supports the "printer-current-time" attribute
on the Printer object.
*** If the associated Subscription Object does not contain a
"notify-user-data" attribute, the Printer MUST send an
octet-string of length 0.
**** If the "notify-attributes" attribute is present on the
Subscription Object, the Printer MUST send all attributes
specified by the "notify-attributes" attribute. Note: If the
Printer doesn’t support the "notify-attributes" attribute, it
is not present on the associated Subscription Object.
For Event Notifications for Job Events, the Printer includes
the additional attributes shown in Table 4.
Table 4. Additional Attributes in Event Notification Content for
Job Events
Source Value Sends Source Object
job-id (integer(1:MAX)) MUST Job
job-state (type1 enum) MUST Job
job-state-reasons (1setOf type2 keyword) MUST Job
job-impressions-completed (integer(0:MAX)) MUST * Job
* The Printer MUST send the "job-impressions-completed" attribute
in an Event Notification only for the combinations of Events and
Subscribed Events shown in Table 5.
Table 5. Combinations of Events and Subscribed Events for
"job-impressions-completed"
Job Event Subscribed Job Event
’job-progress’ ’job-progress’
’job-completed’ ’job-completed’
’job-completed’ ’job-state-changed’
For Event Notification for Printer Events, the Printer includes
the additional attributes shown in Table 6.
Table 6. Additional Attributes in Event Notification Content for
Printer Events
Source Value Sends Source
Object
printer-state (type1 enum) MUST Printer
printer-state-reasons (1setOf type2 keyword) MUST Printer
printer-is-accepting-jobs (boolean) MUST Printer
6. Additional Information about Subscription Template Attributes
The ’ippget’ Delivery Method does not define any addition
Subscription Template attributes and has the conformance requirements
for Subscription Template attributes defined in [RFC3995]. This
section defines additional information about Subscription Template
attributes defined in [RFC3995].
6.1. notify-pull-method (type2 keyword)
This Subscription Template attribute identifies the Pull Delivery
Method to be used for the Subscription Object (see [RFC3995]). To
support the ’ippget’ Pull Delivery Method defined in this document,
the Printer MUST support this attribute with the following keyword
value:
’ippget’: Indicates that the ’ippget’ Pull Delivery Method is to
be used for this Subscription Object.
7. Subscription Description Attributes
The ’ippget’ Delivery Method has the conformance requirements for
Subscription Description attributes defined in [RFC3995]. The
’ippget’ Delivery Method does not define any addition Subscription
Description attributes.
8. Additional Printer Description Attributes
This section defines additional Printer Description attributes for
use with the ’ippget’ Delivery Method.
8.1. ippget-event-life (integer(15:MAX))
This Printer Description attribute specifies the Event Life value
that the Printer assigns to each Event; i.e., the number of seconds
after an Event occurs during which a Printer will return that Event
in an Event Notification in a Get-Notifications response. After the
Event Life expires for the Event, the Printer MAY no longer return an
Event Notification for that Event in a Get-Notifications response.
The Printer MUST support this attribute if it supports the ’ippget’
Delivery Method. The value MUST be 15 or more (at least 15 seconds),
and 60 (seconds) is the RECOMMENDED value to align with the PWG Job
Monitoring MIB [RFC2707] jmGeneralJobPersistence and
jmGeneralAttributePersistence objects.
For example, assume the following:
1. A client performs a Job Creation operation that creates a
Subscription Object associated with the ’ippget’ Delivery Method;
2. An Event associated with the new Job occurs immediately after the
Subscription Object is created;
3. the same client or some other client performs a Get-Notifications
operation so that the client is connected N seconds after the Job
Creation operation.
Then, if N is less than the value of this attribute, the client(s)
performing the Get-Notifications operations can expect not to miss
any Event-Notifications, barring some unforeseen lack of memory space
in the Printer. Note: The client MUST initiate the Get-
Notifications at a time that is sufficiently less that N seconds to
account for network latency so that it is connected to the Printer
before N seconds elapses.
If a Printer supports the ’ippget’ Delivery Method, it MUST keep
’completed’, ’canceled’, or ’aborted’ Job objects in the Job
Retention and/or Job History phases for at least as long as this
attribute’s value. The Printer MAY retain jobs longer that this
value. See [RFC2911], section 4.3.7.1, and the discussion in
[RFC3995] (regarding the ’job-completed’ event). The latter explains
that a Notification Recipient can query the Job after receiving a
’job-completed’ Event Notification in order to find out other
information about the job that is ’completed’, ’aborted’, or
’canceled’. However, this attribute has no effect on the Cancel-
Subscription operation, which deletes the Subscription object
immediately whether or not it contains the "notify-pull-method"
attribute with the ’ippget’ keyword value. Immediately thereafter,