11.2.5.2 Get-Subscriptions Response
The Printer returns the following sets of attributes as part of the
Get-Subscriptions Response:
Group 1: Operation Attributes
Status Message:
Same as [RFC2911].
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
Same as for Get-Subscription-Attributes.
Groups 3 to N: Subscription Attributes
The Printer responds with one Subscription Attributes Group for
each requested Subscription Object (see the "notify-job-id"
attribute in the Operation Attributes Group of this operation).
The Printer returns Subscription Objects in any order.
If the "limit" attribute is present in the Operation Attributes
group of the request, the number of Subscription Attributes Groups
in the response MUST NOT exceed the value of the "limit"
attribute.
It there are no Subscription Objects associated with the specified
Job or Printer, the Printer MUST return zero Subscription
Attributes Groups and it MUST NOT treat this case as an error,
i.e., the status-code MUST be ’successful-ok’ unless something
else causes the status code to have some other value.
See the Group 3 response (Subscription Attributes Group) of the
Get-Subscription-Attributes operation (section 11.2.4.2) for the
attributes that a Printer returns in this group.
11.2.6. Renew-Subscription operation
This operation allows a client to request the Printer to extend the
lease on a Per-Printer Subscription Object.
The Printer MUST support this operation.
The Printer MUST accept this request for a Per-Printer Subscription
Object in any of the target Printer’s states, i.e., ’idle’,
’processing’, or ’stopped’, but MUST NOT change the Printer’s
"printer-state" attribute.
The Printer MUST reject this request for a Per-Job Subscription
Object because it has no lease (see section 5.4.3). The status code
returned MUST be ’client-error-not-possible’.
Access Rights: The authenticated user (see [RFC2911] section 8.3)
performing this operation MUST (1) be the owner of the Per-Printer
Subscription Object, (2) have Operator or Administrator access rights
for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be
otherwise authorized by the Printer’s administrator-configured
security policy to renew Per-Printer Subscription Objects for the
target Printer. Otherwise, the Printer MUST reject the operation and
return: the ’client-error-forbidden’, ’client-error-not-
authenticated’, or ’client-error-not-authorized’ status code as
appropriate.
11.2.6.1. Renew-Subscription Request
The following groups of attributes are part of the Renew-Subscription
Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Requesting User Name:
The "requesting-user-name" (name(MAX)) attribute SHOULD be
supplied by the client as described in [RFC2911] section 8.3.
11.2.6.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this
attribute. This attribute specifies the Per-Printer Subscription
Object whose lease the Printer MUST renew. If the client omits this
attribute, the Printer MUST reject this request with the ’client-
error-bad-request’ status code.
Group 2: Subscription Template Attributes
11.2.6.1.2. "notify-lease-duration" (integer(0:MAX))
The client MAY supply this attribute. It indicates the number of
seconds to renew the lease for the specified Subscription Object. A
value of 0 requests an infinite lease (which MAY require Operator
access rights). If the client omits this attribute, the Printer MUST
use the value of the Printer’s "notify-lease-duration-default"
attribute. See section 5.3.8 for more details.
11.2.6.2. Renew-Subscription Response
The Printer returns the following sets of attributes as part of the
Renew-Subscription Response:
Group 1: Operation Attributes
Status Message:
Same as [RFC2911].
The following are some of the status codes returned (see
[RFC2911]:
successful-ok: The operation successfully renewed the lease
on the Subscription Object for the requested duration.
successful-ok-ignored-or-substituted-attributes: The
operation successfully renewed the lease on the Subscription
Object for some duration other than the amount requested.
client-error-not-possible: The operation failed because the
"notify-subscription-id" Operation attribute identified a
Per-Job Subscription Object.
client-error-not-found: The operation failed because the
"notify-subscription-id" Operation attribute identified a
non-existent Subscription Object.
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2. The
"attributes-natural-language" MAY be the natural language of the
Subscription Object, rather than the one requested.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 for details on returning Unsupported
Attributes.
Group 3: Subscription Attributes
The Printer MUST return the following Subscription Attribute:
11.2.6.2.1. "notify-lease-duration" (integer(0:MAX))
The value of this attribute MUST be the number of seconds that the
Printer has granted for the lease of the Subscription Object (see
section 5.3.8 for details, such as the value of this attribute when
the Printer doesn’t support the requested value).
11.2.7. Cancel-Subscription operation
This operation allows a client to delete a Subscription Object and
stop the Printer from delivering more Event Notifications. Once
performed, there is no way to reference the Subscription Object.
A Printer MUST supported this operation.
The Printer MUST accept this request in any of the target Printer’s
states, i.e., ’idle’, ’processing’, or ’stopped’, but MUST NOT change
the Printer’s "printer-state" attribute.
If the specified Subscription Object is a Per-Job Subscription
Object, the Printer MUST accept this request in any of the target
Job’s states, but MUST NOT change the Job’s "job-state" attribute or
affect the Job.
Note: There is no way to change any attributes on a Subscription
Object, except the "notify-lease-duration" attribute (using the
Renew-Subscription operation). In order to change other attributes,
a client performs a Subscription Creation Operation and Cancel-
Subscription operation on the old Subscription Object. If the client
wants to avoid missing Event Notifications, it performs the
Subscription Creation Operation first. If this order would create
too many Subscription Objects on the Printer, the client reverses the
order.
Access Rights: The authenticated user (see [RFC2911] section 8.3)
performing this operation MUST (1) be the owner of the Subscription
Object, (2) have Operator or Administrator access rights for the
Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise
authorized by the Printer’s administrator-configured security policy
to cancel the target Subscription Object. Otherwise, the Printer
MUST reject the operation and return: the ’client-error-forbidden’,
’client-error-not-authenticated’, or ’client-error-not-authorized’
status code as appropriate.
11.2.7.1. Cancel-Subscription Request
The following groups of attributes are part of the Cancel-
Subscription Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
11.2.7.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this
attribute. This attribute specifies the Subscription Object that the
Printer MUST cancel. If the client omits this attribute, the Printer
MUST reject this request with the ’client-error-bad-request’ status
code.
11.2.7.2. Cancel-Subscription Response
The Printer returns the following sets of attributes as part of the
Cancel-Subscription Response:
Group 1: Operation Attributes
Status Message:
Same as [RFC2911].
The following are some of the status codes returned (see
[RFC2911]:
successful-ok: The operation successfully canceled
(deleted) the Subscription Object.
client-error-not-found: The operation failed because the
"notify-subscription-id" Operation attribute identified a
non-existent Subscription Object.
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2. The
"attributes-natural-language" MAY be the natural language of the
Subscription Object, rather than the one requested.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 for details on returning Unsupported
Attributes.
12. Status Codes
The following status codes are defined as extensions for Notification
and are returned as the value of the "status-code" parameter in the
Operation Attributes Group of a response (see [RFC2911] section
3.1.6.1). Operations in this document can also return the status
codes defined in section 13 of [RFC2911]. The ’successful-ok’ status
code is an example of such a status code.
12.1. successful-ok-ignored-subscriptions (0x0003)
The Subscription Creation Operation was unable to create all
requested Subscription Objects.
For a Create-Job-Subscriptions or Create-Printer-Subscriptions
operation, this status code means that the Printer created one or
more Subscription Objects, but not all requested Subscription
Objects.
For a Job Creation operation, this status code means that the Printer
created the Job along with zero or more Subscription Objects. The
Printer returns this status code even if other job attributes are
unsupported or in conflict. That is, if an IPP Printer finds a
warning that would allow it to return ’successful-ok-ignored-
subscriptions’ and either ’successful-ok-ignored-or-substituted-
attributes’ and/or ’successful-ok-conflicting-attributes’, it MUST
return ’successful-ok-ignored-subscriptions’.
12.2. client-error-ignored-all-subscriptions (0x0414)
This status code is the same as ’successful-ok-ignored-subscriptions’
except that only the Create-Job-Subscriptions and Create-Printer-
Subscriptions operation return it. They return this status code only
when the Printer creates zero Subscription Objects.
13. Status Codes in Subscription Attributes Groups
This section contains values of the "notify-status-code" (type2 enum)
attribute that the Printer returns in a Subscription Attributes Group
in a response when the corresponding Subscription Object:
1. is not created or
2. is created and some of the client-supplied attributes are not
supported.
The following sections are ordered in decreasing order of importance
of the status-codes.
13.1. client-error-uri-scheme-not-supported (0x040C)
This status code is defined in [RFC2911]. This document extends its
meaning and allows it to be in a Subscription Attributes Group of a
response.
The scheme of the client-supplied URI in a "notify-recipient-uri"
Subscription Template Attribute in a Subscription Creation Operation
is not supported. See section 5.3.1.
13.2. client-error-attributes-or-values-not-supported (0x040B)
This status code is defined in [RFC2911]. This document extends its
meaning and allows it to be in a Subscription Attributes Group of a
response.
The method of the client-supplied keyword in a "notify-pull-method"
Subscription Template Attribute in a Subscription Creation Operation
is not supported. See section 5.3.2.
13.3. client-error-too-many-subscriptions (0x0415)
The number of Subscription Objects supported by the Printer would be
exceeded if this Subscription Object were created (see section 5.2).
13.4. successful-ok-too-many-events (0x0005)
The client supplied more Events in the "notify-events" operation
attribute of a Subscription Creation Operation than the Printer
supports, as indicated in its "notify-max-events-supported" Printer
attribute (see section 5.3.3).
13.5. successful-ok-ignored-or-substituted-attributes (0x0001)
This status code is defined in [RFC2911]. This document extends its
meaning to include unsupported Subscription Template Attributes and
it can appear in a Subscription Attributes Group.
14. Encodings of Additional Attribute Tags
This section assigns values to two attributes tags as extensions to
the encoding defined in [RFC2910]).
The "subscription-attributes-tag" delimits Subscription Template
Attributes Groups in requests and Subscription Attributes Groups in
responses.
The "event-notification-attributes-tag" delimits Event Notifications
in Delivery Methods that use an IPP-like encoding.
The following table specifies the values for the delimiter tags:
Tag Value (Hex) Meaning
0x06 "subscription-attributes-tag"
0x07 "event-notification-attributes-tag"
15. Conformance Requirements
It is OPTIONAL for IPP clients and Printers to implement this Event
Notification specification.
15.1. Conformance requirements for clients
If this Event Notification specification is implemented by a client,
the client MUST support the ’ippget’ Pull Delivery Method and meet
the conformance requirements as defined in [RFC3996] for clients. A
client MAY support additional Delivery Methods.
15.2. Conformance requirements for Printers
If this Event Notification specification is implemented by a Printer,
the Printer MUST:
- meet the Conformance Requirements detailed in section 5 of
[RFC2911].
- support the Subscription Template Attributes Group in requests and
the Subscription Attributes Group in responses.
- support all of the following attributes:
a. REQUIRED Subscription Object attributes in section 5.
b. REQUIRED Printer Description object attributes in section 6.
c. REQUIRED attributes in Event Notification content in section 8.
- support the ’ippget’ Pull Delivery Method and meet the conformance
requirements as defined in [RFC3996] for Printers. The Printer
MAY support additional Push and Pull Delivery Methods.
- deliver Event Notifications that conform to the requirements of
section 9 and the requirements of the Delivery Method Document for
each supported Delivery Method (the conformance requirements for
Delivery Method Documents is specified in section 10).
- for all of the Job Creation Operations that the Printer supports,
MUST support the REQUIRED extensions for notification defined in
section 11.1.3.
- meet the conformance requirements for operations as described in
Table 16 and meet the requirements for Printers as specified in
the indicated sub-sections of section 11:
Table 16 - Printer Conformance Requirements for Operations
Operation Printer
Conformance
Requirements
Create-Printer-Subscriptions (section 11.1.2) REQUIRED
Create-Job-Subscriptions (section 11.1.1) OPTIONAL
Get-Subscription-Attributes (section 11.2.3) REQUIRED
Get-Subscriptions (section 11.2.5) REQUIRED
Renew-Subscription (section 11.2.6) REQUIRED
Cancel-Subscription (section 11.2.7) REQUIRED
16. Model for Notification with Cascading Printers (Informative)
With this model (see Figure 2 below), there is an intervening Print
server between the human user and the output-device. So the system
effectively has two Printer objects. There are two cases to
consider.
1. When the Printer 1 (in the server) generates Events, the system
behaves like the client and Printer in Figure 1. In this case,
Printer 1 delivers Event Notifications that are shown as Event
Notifications (A) of Figure 2.
2. When the Printer 2 (in the output-device) generates Events, there
are two possible system configurations:
a) Printer 1 forwards the client-supplied Subscription Creation
Operations to the downstream Printer 2 and lets Printer 2
deliver the Event Notifications directly to the Notification
Recipients supplied by the Client (Event Notifications(C) in
the diagram).
b) Printer 1 performs the client-supplied Subscription Creation
Operations and also forwards the Subscription Creation
Operations to Printer 2 with the Notification Recipient changed
to be the Printer 1. When an Event occurs in Printer 2,
Printer 2 delivers the Event Notification (B) to Notification
Recipient of Printer 1, which relays the received Event
Notification (B) to the client-supplied Notification Recipient
(as Event Notifications(A) in the diagram). Note, when a
client performs a Subscription Creation Operation, Printer 1
need not forward the Subscription Creation Operation to Printer
2 if it would create a duplicate Subscription Object on Printer
2.
Note: when Printer 1 is forwarding Subscription Creation Operations
to Printer 2, it may request Printer 2 to create additional
Subscription Objects (called "piggy-backing"). Piggy-backing is
useful when:
- Device A is configured to accept (IPP or non-IPP) requests from
other servers.
- Server S wants to receive Job Events that the client didn’t
request and Server S wants these Events for jobs it submits and
not for other jobs.
server S device A
+------------+ +------------+
| | | |
+--------+ Subscription | ###########| | ###########|
| client |--Creation ----># Printer #| Subscription | # Printer #|
+--------+ Operation | # Object 1#|---Creation------|># Object 2#|
| ###|#######| Operation | ####|#|####|
+----|---^---+ +-----|-|----+
+--------+ Event | | | |
|Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ |
|ation Re|<-------------Event Notifications(C)-----------------+
|cipient |
+--------+
Figure 2 - Model for Notification with Cascading Printers
17. Distributed Model for Notification (Informative)
A Printer implementation could use some other remote notification
server to provide some or most of the service. For example, the
remote notification server could deliver Event Notifications using
Delivery Methods that are not directly supported by the output device
or Printer object. Or, the remote notification server could store
Subscription Objects (passed to it from the output device in response
to Subscription Creation requests), accept Events, format the Event
Notification in the natural language of the Notification Recipient,
and deliver the Event Notifications to the Notification Recipient(s).
Figure 3 shows this partitioning. The interface between the output
device (or Printer object) and the remote notification server is
outside the scope of this document and is intended to be transparent
to the client and this document.
***********************
*
* Printer in combination
* with the distributed
* Notification Server)
*
* output device or server
* +---------------+
PDA, desktop, or server * + ########### +
+--------+ * | # # |
| client |---IPP Subscription--------># Printer # |
+--------+ Creation operation * | # Object # |
* | #####|##### |
* +-------|-------+
* | Subscriptions
* | OR Event
+------------+ * | Notifications
|Notification| IPP-defined * +------v--------+
|Recipient |<--Event Notifications---| Notification |
+------------+ * | Server |
* +---------------+
*
*************************
*** = Implementation configuration opaque boundary
Figure 3 - Opaque Use of a Notification Server Transparent to the
Client
18. Extended Notification Recipient (Informative)
The model allows for an extended Notification Recipient that is
itself a notification server that forwards each Event Notification to
another recipient (called the Ultimate Notification Recipient in this
section). The Delivery Method to the Ultimate Recipient is probably