RFC 3995
Internet Printing Protocol (IPP): Event Notifications and Subscriptions
10. Delivery Methods
A Delivery Method is the mechanism, i.e., protocol, by which the Printer delivers an Event Notification to a Notification Recipient. There are several potential Delivery Methods for Event Notifications, standardized, as well as proprietary. This specification REQUIRES that the 'ippget' Pull Delivery Method [RFC3996] be supported. Conforming implementations MAY support additional Push or Pull Delivery Methods as well. This document does not define any of these delivery mechanisms. Each Delivery Method MUST be defined in a Delivery Method Document that is separate from this document. New Delivery Methods will be created as needed using an extension to the registration procedures defined in [RFC2911]. Such documents are registered with IANA (see section 23.7.3). The following sorts of Delivery Methods are possible: - The Notification Recipient polls for Event Notifications at intervals directed by the Printer - The Printer delivers Event Notifications to the Notification Recipient using http as the transport. - The Printer delivers an email message. This section specifies how to define a Delivery Method Document and what to put in such a document. A Delivery Method Document MUST contain an exact copy of the following paragraph, caption and table. In addition, column 2 of the table in the Delivery Method Document MUST contain answers to questions in column 1 for the Delivery Method. Also, the Delivery Method document MUST contain a reference to this document and call that reference [RFC3995] because the table contains an [RFC3995] reference. If a Printer supports this Delivery Method, the following are its characteristics.
Table 15 - Information about the Delivery Method
Document Method Conformance Requirement Delivery Method
Realization
1. What is the URL scheme name for the Push Delivery Method or the
keyword method name for the Pull Delivery Method?
2. Is the Delivery Method REQUIRED, RECOMMENDED, or OPTIONAL for an
IPP Printer to support?
3. What transport and delivery protocols does the Printer use to
deliver the Event Notification Content, i.e., what is the entire
network stack?
4. Can several Event Notifications be combined into a Compound Event
Notification?
5. Is the Delivery Method initiated by the Notification Recipient
(pull), or by the Printer (push)?
6. Is the Event Notification content Machine Consumable or Human
Consumable?
7. What section in this document answers the following question?
For a Machine Consumable Event Notification, what is the
representation and encoding of values defined in section 9.1 of
[RFC3995] and the conformance requirements thereof? For a Human
Consumable Event Notification, what is the representation and
encoding of pieces of information defined in section 9.2 of
[RFC3995] and the conformance requirements thereof?
8. What are the latency and reliability of the transport and
delivery protocol?
9. What are the security aspects of the transport and delivery
protocol, e.g., how it is handled in firewalls?
10. What are the content length restrictions?
11. What are the additional values or pieces of information that a
Printer delivers in an Event Notification content and the
conformance requirements thereof?
12. What are the additional Subscription Template and/or
Subscription Description attributes and the conformance
requirements thereof?
13. What are the additional Printer Description attributes and the
conformance requirements thereof?
11. Operations for Notification
This section defines all of the operations for Notification. Section
7.1 assigns the "operation-id" for each operation. The following two
sub-sections define Subscription Creation Operations, and other
operations.
11.1. Subscription Creation Operations
This section defines the Subscription Creation Operations. The first
section on Create-Job-Subscriptions gives most of the information.
The other Subscription Creation Operations refer to the section on
Create-Job-Subscriptions, even though the Create-Job-Subscriptions
operation is the only OPTIONAL operation in this document (see
section 12).
A Printer MUST support Create-Printer-Subscriptions and the
Subscription Template Attributes Group in Job Creation operations.
It MAY support Create-Job-Subscriptions operations.
11.1.1. Create-Job-Subscriptions Operation
The operation creates one or more Per-Job Subscription Objects. The
client supplies one or more Subscription Template Attributes Groups
each containing one or more of Subscription Template Attributes
(defined in section 5.3).
Except for errors, the Printer MUST create exactly one Per-Job
Subscription Object from each Subscription Template Attributes Group
in the request, even if the newly created Subscription Object would
have identical behavior to some existing Subscription Object. The
Printer MUST associate each newly created Per-Job Subscription Object
with the target Job, which is specified by the "notify-job-id"
operation attribute.
The Printer MUST accept the request in any of the target job's 'not-
completed' states, i.e., 'pending', 'pending-held', 'processing', or
'processing-stopped'. The Printer MUST NOT change the job's "job-
state" attribute because of this operation. If the target job is in
any of the 'completed' states, i.e., 'completed', 'canceled', or
'aborted, then the Printer MUST reject the request and return the
'client-error-not-possible' status code; the response MUST NOT
contain any Subscription Attribute Groups.
Access Rights: To create Per-Job Subscription Objects, the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the job owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to create Per-Job Subscription Objects for the target job. 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.1.1.1. Create-Job-Subscriptions Request
The following groups of attributes are part of the Create-Job- Subscriptions 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.1.1.1.1. notify-job-id (integer(1:MAX))
The client MUST supply this attribute and it MUST specify the Job object to associate the Per-Job Subscription with. The value of "notify-job-id" MUST be the value of the "job-id" of the associated Job object. If the client does not supply this attribute, the Printer MUST reject this request with a 'client-error-bad-request' status code. Group 2-N: Subscription Template Attributes For each occurrence of this group: The client MUST supply one or more Subscription Template Attributes in any order. See section 5.3 for a description of each such attribute. See section 5.2 for details on processing these attributes.
11.1.1.2. Create-Job-Subscriptions Response
The Printer MUST return to the client the following sets of attributes as part of a Create-Job-Subscriptions 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. In this group, the Printer can return any status codes defined in [RFC2911] and section 12. The following is a description of the important status codes: successful-ok: the Printer created all Subscription Objects requested (see [RFC2911]). successful-ok-ignored-subscriptions: the Printer created some Subscription Objects requested but some failed. The Subscription Attributes Groups with a "notify-status-code" attribute are the ones that failed (see section 12.1). client-error-ignored-all-subscriptions: the Printer created no Subscription Objects requested and all failed. The Subscription Attributes Groups with a "notify-status-code" attribute are the ones that failed (see section 12.2). client-error-not-possible: For this operation and other Per-Job Subscription operations, this error can occur because the specified Job has already completed (see [RFC2911], whether or not the Job is retained in the Job Retention and/or Job History phases (see [RFC2911] section 4.3.7.1). 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 See [RFC2911] section 3.1.7 for details on returning Unsupported Attributes. This group does not contain any unsupported Subscription Template Attributes; they are returned in the Subscription Attributes Group (see below).
Group 3-N: Subscription Attributes
These groups MUST be returned unless the Printer is unable to
interpret the entire request, e.g., the "status-code" parameter
returned in Group 1 has the value: 'client-error-bad-request'.
"notify-status-code" (type2 enum):
Indicates the status of this subscription (see section 13 for
the status code definitions). Section 5.2 defines when this
attribute MUST be present in this group.
See section 5.2 for details on the contents of each occurrence of
this group.
11.1.2. Create-Printer-Subscriptions operation
The operation is identical to Create-Job-Subscriptions with
exceptions noted in this section.
The operation creates Per-Printer Subscription Objects instead of
Per-Job Subscription Objects, and associates each newly created Per-
Printer Subscription Object with the Printer specified by the
operation target rather than with a specific Job.
The Printer MUST accept the request in any of its states, i.e.,
'idle', 'processing', or 'stopped'. The Printer MUST NOT change its
"printer-state" attribute because of this operation.
Access Rights: To create Per-Printer Subscription Objects, the
authenticated user (see [RFC2911] section 8.3) performing this
operation MUST have (1) Operator or Administrator access rights for
this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise
authorized by the Printer's administrator-configured security policy
to create Per-Printer Subscription Objects for this 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.1.2.1. Create-Printer-Subscriptions Request
The groups are identical to the Create-Job-Subscriptions (see section
11.1.1.1) except that the Operation Attributes group MUST NOT contain
the "notify-job-id" attribute. If the client does supply the
"notify-job-id" attribute, then the Printer MUST treat it as any
other unsupported Operation attribute and MUST return it in the
Unsupported Attributes group.
11.1.2.2. Create-Printer-Subscriptions Response
The groups are identical to the Create-Job-Subscriptions (see section 11.1.1.2).11.1.3. Job Creation Operations - Extensions for Notification
This document extends the Job Creation operations (see section 3.2) to create Subscription Objects as a part of the operation. The Job Creation operations are identical to Create-Job-Subscriptions operation with exceptions noted in this section. Unlike the Create-Job-Subscriptions operation, a Job Creation operation associates the newly created Subscription Objects with the Job object created by this operation. The operation succeeds if and only if the Job creation succeeds. If the Printer does not create some or all of the requested Subscription Objects, the Printer MUST return a 'successful-ok-ignored-subscriptions' status-code instead of a 'successful-ok' status-code, but the Printer MUST NOT reject the operation because of a failure to create Subscription Objects. If the Job Creation operation includes a Job Template group, the client MUST supply it after the Operation Attributes group and before the first Subscription Template Attributes Group. If a Printer does not support this Notification specification, then it MUST treat the Subscription Attributes Group like an unknown group and ignore it (see [RFC2911] section 5.2.2). Because the Printer ignores the Subscription Attributes Group, it doesn't return them in the response either, thus indicating to the client that the Printer doesn't support Notification. After completion of a successful Job Creation operation, the Printer generates a 'job-created' event (see section 5.3.3.4.3). Access Rights: To create Per-Job Subscription Objects, the authenticated user (see [RFC2911] section 8.3) performing this operation MUST either have permission to create Jobs on the Printer or have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5). 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.1.3.1. Job Creation Request
The groups for this operation are sufficiently different from the Create-Job-Subscriptions operation that they are all presented here. The following groups of attributes are supplied as part of a Job Creation Request: Group 1: Operation Attributes Same as defined in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. Group 2: Job Template Attributes The client OPTIONALLY supplies a set of Job Template attributes as defined in [RFC2911] section 4.2. Group 3 to N: Subscription Template Attributes The same as Group 2-N in Create-Job-Subscriptions. See section 11.1.1.1. Group N+1: Document Content (Print-Job only) The client MUST supply the document data to be processed.11.1.3.2. Job Creation Response
The Printer MUST return to the client the following sets of attributes as part of a Print-Job, Print-URI, and Create-Job Response: Group 1: Operation Attributes Status Message: As defined in [RFC2911] for Print-Job, Print-URI, and Create- Job requests. In this group, the Printer can return any status codes defined in [RFC2911] and section 12. The following is a description of the important status codes: successful-ok: the Printer created the Job and all Subscription Objects requested (see [RFC2911]. successful-ok-ignored-subscriptions: the Printer created the Job and not all of the Subscription Objects requested
(see section 12.1). This status-code hides 'successful-ok-
xxx' status-codes that could reveal problems in Job
creation. The Printer MUST NOT return the 'client-error-
ignored-all-subscriptions' status code for Job Creation
operations because the Printer returns an error status-code
only when it fails to create a Job.
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
See [RFC2911] section 3.1.7 for details on returning Unsupported
Attributes. This group does not contain any unsupported
Subscription Template Attributes; they are returned in the
Subscription Attributes Group (see below).
Group 3: Job Object Attributes
The "job-id" of the Job Object just created, etc., as defined in
[RFC2911] for Print-Job, Print-URI, and Create-Job requests.
Group 4 to N: Subscription Attributes
These groups MUST be returned if and only if the client supplied
Subscription Template Attributes and the operation was accepted.
See section 5.2 for details on the contents of each occurrence of
this group.
11.2. Other Operations
This section defines other operations on Subscription objects.
11.2.1. Restart-Job Operation - Extensions for Notification
The Restart-Job operation [RFC2911] is neither a Job Creation
operation nor a Subscription Creation operation (see section 3.2).
For the Restart-Job operation, the client MUST NOT supply any Job
Subscription Attributes Groups. The Printer MUST treat any supplied
Job Subscription Attributes as unsupported attributes.
For this operation, the Printer does not return a job-id or any
Subscription Attributes groups because the Printer reuses the
existing Job object with the same job-id and the existing Per-Job
Subscription Objects with the same subscription-ids. However, after
successful completion of this operation, the Printer generates a 'job-created' event (see section 5.3.3.4.3).11.2.2. Validate-Job Operation - Extensions for Notification
A client can test whether one or more Subscription Objects could be created using the Validate-Job operation. The client supplies one or more Subscription Template Attributes Groups (defined in section 5.3), just as in a Job Creation request. A Printer MUST support this extension to this operation. The Printer MUST accept requests that are identical to the Job Creation request defined in section 11.1.3.1, except that the request MUST NOT contain document data. The Printer MUST return the same groups and attributes as the Print- Job operation (section 11.1.3.1) with the following exceptions. The Printer MUST NOT return a Job Object Attributes Group because no Job is created. The Printer MUST NOT return the "notify-subscription-id" attribute in any Subscription Attribute Group because no Subscription Object is created. If the Printer would succeed in creating a Subscription Object, the corresponding Subscription Attributes Group either has no 'status- code' attribute or a 'status-code' attribute with a value of 'successful-ok-too-many-events' or 'successful-ok-ignored-or- substituted-attributes' (see sections 5.2 and 13). The status-codes have the same meaning as in Job Creation except the results state what "would happen". The Printer MUST validate Subscription Template Attributes Groups in the same manner as the Job Creation operations.11.2.3. Get-Printer-Attributes - Extensions for Notification
This operation is extended so that it returns Printer attributes defined in this document. A Printer MUST support this extension to this operation. In addition to the requirements of [RFC2911] section 3.2.5, a Printer MUST support the following additional values for the "requested- attributes" Operation attribute in this operation and return such attributes in the Printer Object Attributes group of its response. 1. Subscription Template Attributes: Each supported attribute in column 2 of Table 1.
2. New Printer Description Attributes: Each supported attribute in
section 6.
3. New Group Name: The 'subscription-template' group name, which
names all supported Subscription Template Attribute in column 2 of
Table 1. This group name is also used in the Get-Subscription-
Attributes and Get-Subscriptions operation with an analogous
meaning.
4. Extended Group Name: The 'all' group name, which names all Printer
attributes according to [RFC2911] section 3.2.5. In this
extension 'all' names all attributes specified in [RFC2911] plus
those named in items 1 and 2 of this list.
11.2.4. Get-Subscription-Attributes operation
This operation allows a client to request the values of the
attributes of a Subscription Object.
A Printer MUST support this operation.
This operation is almost identical to the Get-Job-Attributes
operation (see [RFC2911] section 3.3.4). The only differences are
that the operation is directed at a Subscription Object rather than a
Job object, and the returned attribute group contains Subscription
Object attributes rather than Job object attributes.
Access Rights: The authenticated user (see [RFC2911] section 8.3)
performing this operation MUST (1) be the Subscription Object owner,
(2) have Operator or Administrator access rights for this Printer
(see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by
the Printer's administrator-configured security policy to query the
Subscription Object for the target job. 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. Furthermore, the Printer's security
policy MAY limit which attributes are returned, in a manner similar
to the Get-Job-Attributes operation (see [RFC2911] end of section
3.3.4.2).
11.2.4.1. Get-Subscription-Attributes Request
The following groups of attributes are part of the Get-Subscription-
Attributes request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in section [RFC2911] 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.4.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 from
which the client is requesting attributes. If the client omits this
attribute, the Printer MUST reject this request with the 'client-
error-bad-request' status code.
11.2.4.1.2. "requested-attributes" (1setOf keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. This attribute specifies the attributes of
the specified Subscription Object that the Printer MUST return in the
response. Each value of this attribute is either an attribute name
(defined in sections 5.3 and 5.4) or an attribute group name. The
attribute group names are:
- 'subscription-template': all attributes that are both defined in
section 5.3 and present on the specified Subscription Object
(column 1 of Table 1).
- 'subscription-description': all attributes that are both defined
in section 5.4 and present on the specified Subscription Object
(Table 2).
- 'all': all attributes that are present on the specified
Subscription Object.
A Printer MUST support all these group names.
If the client omits this attribute, the Printer MUST respond as if
this attribute had been supplied with a value of 'all'.
11.2.4.2. Get-Subscription-Attributes Response
The Printer returns the following sets of attributes as part of the
Get-Subscription-Attributes 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. 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 and section 3.2.5.2 for details on
returning Unsupported Attributes.
The response NEED NOT contain the "requested-attributes" operation
attribute with any supplied keyword values that were requested by
the client but are not supported by the IPP object. If the
Printer object does return unsupported attributes referenced in
the "requested-attributes" operation attribute, the values of the
"requested-attributes" attribute returned MUST include only the
unsupported keywords that were requested by the client. If the
client had requested a group name, such as 'all', the resulting
unsupported attributes returned MUST NOT include attribute keyword
names described in the standard but not supported by the
implementation.
Group 3: Subscription Attributes
This group contains a set of attributes with their current values.
Each attribute returned in this group:
a) MUST be specified by the "requested-attributes" attribute in the
request, AND
b) MUST be present on the specified Subscription Object AND
c) MUST NOT be restricted by the security policy in force. For
example, a Printer MAY prohibit a client who is not the creator of
a Subscription Object from seeing some or all of its attributes.
See [RFC2911] end of section 3.3.4.2 and section 8.
The Printer can return the attributes of the Subscription Object
in any order. The client MUST accept the attributes in any order.
11.2.5. Get-Subscriptions operation
This operation allows a client to retrieve the values of attributes of all Subscription Objects belonging to a Job or Printer. A Printer MUST supported this operation. This operation is similar to the Get-Subscription-Attributes operation, except that this Get-Subscriptions operation returns attributes from possibly more than one object. This operation is similar to the Get-Jobs operation (see [RFC2911] section 3.2.6), except that the operation returns Subscription Objects rather than Job objects. Access Rights: To query Per-Job Subscription Objects of the specified job (client supplied the "notify-job-id" operation attribute - see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. To query Per-Printer Subscription Objects of the Printer (client omits the "notify-job-id" operation attribute - see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise authorized by the Printer's administrator-configured security policy to query 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. Furthermore, the Printer's security policy MAY limit which attributes are returned, in a manner similar to the Get-Jobs and Get-Printer-Attributes operations (see [RFC2911] end of sections 3.2.6.2 and 3.2.5.2).11.2.5.1. Get-Subscriptions Request
The following groups of attributes are part of the Get-Subscriptions 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.5.1.1. "notify-job-id" (integer(1:MAX))
If the client specifies this attribute, the Printer returns the
specified attributes of all Per-Job Subscription Objects associated
with the Job whose "job-id" attribute value equals the value of this
attribute. If the client does not specify this attribute, the
Printer returns the specified attributes of all Per-Printer
Subscription Objects. Note: there is no way to get all Per-Job
Subscriptions known to the Printer in a single operation. A Get-Jobs
operation followed by a Get-Subscriptions operation for each Job will
return all Per-Job Subscriptions.
11.2.5.1.2. "limit" (integer(1:MAX))
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. It is an integer value that determines the
maximum number of Subscription Objects that a client will receive
from the Printer even if the "my-subscriptions" attribute constrains
which Subscription Objects are returned. The limit is a "stateless
limit" in that if the value supplied by the client is 'N', then only
the first 'N' Subscription Objects are returned in the Get-
Subscriptions Response. There is no mechanism to allow for the next
'M' Subscription Objects after the first 'N' Subscription Objects.
If the client does not supply this attribute, the Printer responds
with all applicable Subscription Objects.
11.2.5.1.3. "requested-attributes" (1setOf type2 keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST
support this attribute. This attribute specifies the attributes of
the specified Subscription Objects that the Printer MUST return in
the response. Each value of this attribute is either an attribute
name (defined in sections 5.3 and 5.4) or an attribute group name
(defined in section 11.2.4.1). If the client omits this attribute,
the Printer MUST respond as if the client had supplied this attribute
with the one value: 'notify-subscription-id'.
11.2.5.1.4. "my-subscriptions" (boolean)
The client OPTIONALLY supplies this attribute. The Printer MUST support this attribute. If the value is 'false', the Printer MUST consider the Subscription Objects from all users as candidates. If the value is 'true', the Printer MUST return the Subscription Objects created by the requesting user of this request. If the client does not supply this attribute, the Printer MUST respond as if the client had supplied the attribute with a value of 'false'. The means for authenticating the requesting user and matching the Subscription Objects is similar to that for Jobs which is described in [RFC2911] section 8.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
(page 75 continued on part 4)
