RFC 3995
Internet Printing Protocol (IPP): Event Notifications and Subscriptions
Network Working Group R. Herriot Request for Comments: 3995 Global Workflow Solutions Category: Standards Track T. Hastings Updates: 2911, 2910 Xerox Corporation March 2005 Internet Printing Protocol (IPP): Event Notifications and Subscriptions Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2005).Abstract
This document describes an OPTIONAL extension to the Internet Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). This extension allows a client to subscribe to printing related Events. Subscriptions are modeled as Subscription Objects. The Subscription Object specifies that when one of the specified Events occurs, the Printer delivers an asynchronous Event Notification to the specified Notification Recipient via the specified Push or Pull Delivery Method (i.e., protocol). A client associates Subscription Objects with a particular Job by performing the Create-Job-Subscriptions operation or by submitting a Job with subscription information. A client associates Subscription Objects with the Printer by performing a Create-Printer-Subscriptions operation. Four other operations are defined for Subscription Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- Subscription, and Cancel-Subscription.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Notification Overview. . . . . . . . . . . . . . . . . . 5 2. Models for Notification. . . . . . . . . . . . . . . . . . . . 8 2.1. Model for Simple Notification (Normative). . . . . . . . 8 2.2. Additional Models for Notification (Informative) . . . . 9 3. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Conformance Terminology. . . . . . . . . . . . . . . . . 9 3.2. Other Terminology. . . . . . . . . . . . . . . . . . . . 10 4. Object Relationships . . . . . . . . . . . . . . . . . . . . . 12 4.1. Printer and Per-Printer Subscription Objects . . . . . . 13 4.2. Printer, Job and Per-Job Subscription Objects. . . . . . 13 5. Subscription Object. . . . . . . . . . . . . . . . . . . . . . 13 5.1. Rules for Support of Subscription Template Attributes. . 14 5.2. Rules for Processing Subscription Template Attributes. . 15 5.3. Subscription Template Attributes . . . . . . . . . . . . 18 5.3.1. notify-recipient-uri (uri) . . . . . . . . . . . 20 5.3.2. notify-pull-method (type2 keyword) . . . . . . . 21 5.3.3. notify-events (1setOf type2 keyword) . . . . . . 22 5.3.4. notify-attributes (1setOf type2 keyword) . . . . 29 5.3.5. notify-user-data (octetString(63)) . . . . . . . 30 5.3.6. notify-charset (charset) . . . . . . . . . . . . 31 5.3.7. notify-natural-language (naturalLanguage). . . . 31 5.3.8. notify-lease-duration (integer(0:67108863)). . . 32 5.3.9. notify-time-interval (integer(0:MAX)). . . . . . 33 5.4. Subscription Description Attributes. . . . . . . . . . . 34 5.4.1. notify-subscription-id (integer (1:MAX)). . . . 35 5.4.2. notify-sequence-number (integer (0:MAX)) . . . . 35 5.4.3. notify-lease-expiration-time (integer(0:MAX)). . 36 5.4.4. notify-printer-up-time (integer(1:MAX)). . . . . 37 5.4.5. notify-printer-uri (uri) . . . . . . . . . . . . 37 5.4.6. notify-job-id (integer(1:MAX)) . . . . . . . . . 37 5.4.7. notify-subscriber-user-name (name(MAX)). . . . . 38 6. Printer Description Attributes Related to Notification . . . . 38 6.1. printer-state-change-time (integer(1:MAX)) . . . . . . . 39 6.2. printer-state-change-date-time (dateTime). . . . . . . . 39 7. New Values for Existing Printer Description Attributes . . . . 39 7.1. operations-supported (1setOf type2 enum) . . . . . . . . 40 8. Attributes Only in Event Notifications . . . . . . . . . . . . 40 8.1. notify-subscribed-event (type2 keyword). . . . . . . . . 40 8.2. notify-text (text(MAX)). . . . . . . . . . . . . . . . . 41 9. Event Notification Content . . . . . . . . . . . . . . . . . . 41 9.1. Content of Machine Consumable Event Notifications. . . . 44 9.1.1. Event Notification Content Common to All Events. 44 9.1.2. Additional Event Notification Content for Job Events . . . . . . . . . . . . . . . . . . . . . 45
9.1.3. Additional Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . 46
9.2. Content of Human Consumable Event Notification . . . . . 46
9.2.1. Event Notification Content Common to All Events. 47
9.2.2. Additional Event Notification Content for Job
Events . . . . . . . . . . . . . . . . . . . . . 49
9.2.3. Additional Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . 49
10. Delivery Methods . . . . . . . . . . . . . . . . . . . . . . . 50
11. Operations for Notification. . . . . . . . . . . . . . . . . . 52
11.1. Subscription Creation Operations . . . . . . . . . . . . 52
11.1.1. Create-Job-Subscriptions Operation . . . . . . . 52
11.1.2. Create-Printer-Subscriptions operation . . . . . 55
11.1.3. Job Creation Operations - Extensions for
Notification . . . . . . . . . . . . . . . . . . 56
11.2. Other Operations . . . . . . . . . . . . . . . . . . . . 58
11.2.1. Restart-Job Operation - Extensions for
Notification . . . . . . . . . . . . . . . . . . 58
11.2.2. Validate-Job Operation - Extensions for
Notification . . . . . . . . . . . . . . . . . . 59
11.2.3. Get-Printer-Attributes - Extensions for
Notification . . . . . . . . . . . . . . . . . . 59
11.2.4. Get-Subscription-Attributes operation. . . . . . 60
11.2.5. Get-Subscriptions operation. . . . . . . . . . . 63
11.2.6. Renew-Subscription operation . . . . . . . . . . 66
11.2.7. Cancel-Subscription operation. . . . . . . . . . 68
12. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . 70
12.1. successful-ok-ignored-subscriptions (0x0003) . . . . . . 70
12.2. client-error-ignored-all-subscriptions (0x0414). . . . . 71
13. Status Codes in Subscription Attributes Groups . . . . . . . . 71
13.1. client-error-uri-scheme-not-supported (0x040C) . . . . . 71
13.2. client-error-attributes-or-values-not-supported (0x040B) 71
13.3. client-error-too-many-subscriptions (0x0415) . . . . . . 72
13.4. successful-ok-too-many-events (0x0005) . . . . . . . . . 72
13.5. successful-ok-ignored-or-substituted-attributes (0x0001) 72
14. Encodings of Additional Attribute Tags . . . . . . . . . . . . 72
15. Conformance Requirements . . . . . . . . . . . . . . . . . . . 72
15.1. Conformance requirements for clients . . . . . . . . . . 73
15.2. Conformance requirements for Printers. . . . . . . . . . 73
16. Model for Notification with Cascading Printers (Informative) . 74
17. Distributed Model for Notification (Informative) . . . . . . . 75
18. Extended Notification Recipient (Informative). . . . . . . . . 76
19. Object Model for Notification (Normative). . . . . . . . . . . 77
19.1. Object relationships . . . . . . . . . . . . . . . . . . 78
19.2. Printer Object and Per-Printer Subscription Objects. . . 79
19.3. Job Object and Per-Job Subscription Objects. . . . . . . 79
20. Per-Job versus Per-Printer Subscription Objects (Normative). . 79
21. Normative References . . . . . . . . . . . . . . . . . . . . . 80
22. Informative References . . . . . . . . . . . . . . . . . . . . 80 23. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 81 23.1. Attribute Registrations. . . . . . . . . . . . . . . . . 82 23.2. Additional Enum Attribute Value Registrations within the IPP registry . . . . . . . . . . . . . . . . . . . . 83 23.3. Operation Registrations. . . . . . . . . . . . . . . . . 83 23.4. Status code Registrations. . . . . . . . . . . . . . . . 83 23.5. Attribute Group tag Registrations. . . . . . . . . . . . 84 23.6. Registration of Events . . . . . . . . . . . . . . . . . 84 23.7. Registration of Event Notification Delivery Methods. . . 85 23.7.1. Requirements for Registration of Event Notification Delivery Methods. . . . . . . . . . 85 23.7.2. Registration Procedure . . . . . . . . . . . . . 86 23.7.3. Delivery Method Document Registrations . . . . . 87 23.7.4. Registration Template. . . . . . . . . . . . . . 88 24. Internationalization Considerations. . . . . . . . . . . . . . 89 25. Security Considerations. . . . . . . . . . . . . . . . . . . . 89 25.1. Client access rights . . . . . . . . . . . . . . . . . . 89 25.2. Printer security threats . . . . . . . . . . . . . . . . 91 25.3. Notification Recipient security threats. . . . . . . . . 91 26. Description of the base IPP documents (Informative). . . . . . 92 27. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 94 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 95 Tables Table 1 - Subscription Template Attributes. . . . . . . . . . . . 20 Table 2 - Subscription Description Attributes . . . . . . . . . . 35 Table 3 - Printer Description Attributes Associated with Notification. . . . . . . . . . . . . . . . . . . . . . 39 Table 4 - Operation-id assignments. . . . . . . . . . . . . . . . 40 Table 5 - Attributes in Event Notification Content. . . . . . . . 45 Table 6 - Additional Event Notification Content for Job Events. . 46 Table 7 - Combinations of Events and Subscribed Events for "job-impressions-completed" . . . . . . . . . . . . . . 46 Table 8 - Additional Event Notification Content for Printer Events. . . . . . . . . . . . . . . . . . . . . . . . . 46 Table 9 - Printer Name in Event Notification Content. . . . . . . 48 Table 10 - Event Name in Event Notification Content. . . . . . . . 48 Table 11 - Event Time in Event Notification Content. . . . . . . . 48 Table 12 - Job Name in Event Notification Content. . . . . . . . . 49 Table 13 - Job State in Event Notification Content . . . . . . . . 49 Table 14 - Printer State in Event Notification Content . . . . . . 50 Table 15 - Information about the Delivery Method . . . . . . . . . 51 Table 16 - Printer Conformance Requirements for Operations . . . . 74
Figures Figure 1 - Model for Notification. . . . . . . . . . . . . . . . . 9 Figure 2 - Model for Notification with Cascading Printers. . . . . 75 Figure 3 - Opaque Use of a Notification Server Transparent to the Client. . . . . . . . . . . . . . . . . . . . . . . . . 76 Figure 4 - Use of an Extended Notification Recipient transparent to the Printer. . . . . . . . . . . . . . . . . . . . . 77 Figure 5 - Object Model for Notification . . . . . . . . . . . . . 781. Introduction
This IPP notification specification is an OPTIONAL extension to Internet Printing Protocol/1.1: Model and Semantics [RFC2911, RFC2910]. See Appendix 29 for a description of the base IPP documents. This document in combination with the following documents is intended to meet the most important notification requirements described in [RFC3997]: Internet Printing Protocol (IPP): "Job Progress Attributes" [RFC3381] Internet Printing Protocol (IPP): "The 'ippget' Delivery Method for Event Notifications" [RFC3996] This specification REQUIRES that clients and Printers support the 'ippget' Pull Delivery Method [RFC3996]. Conforming client and Printer implementations MAY support additional Push or Pull Delivery Methods as well. Note: this document does not define any Delivery Methods itself, but it does define the rules for conformance for Delivery Method Documents and their registration with IANA (see section 23.7.3). Refer to the Table of Contents for the layout of this document.1.1. Notification Overview
This document defines operations that a client can perform in order to create Subscription Objects in a Printer and carry out other operations on them. A Subscription Object represents a Subscription abstraction. The Subscription Object specifies that when one of the specified Events occurs, the Printer delivers an asynchronous Event Notification to the specified Notification Recipient via the specified Delivery Method (i.e., protocol). When a client (called a Subscribing Client) performs an operation that creates a Subscription Object, the operation contains one or more Subscription Template Attributes Groups. Each such group holds
information used by the Printer to initialize a newly created Subscription Object. The Printer creates one Subscription Object for each Subscription Template Attributes Group in the operation. This group is like the Job Template Attributes group defined in [RFC2911]. The following is an example of the information included in a Subscription Template Attributes Group (see section 5 for details on the Subscription Object attributes): 1. The names of Subscribed Events that are of interest to the Notification Recipient. 2. The address (URL) of one Notification Recipient for a Push Delivery Method or the method for a Pull Delivery Method. 3. The Delivery Method (i.e., the protocol) which the Printer uses to deliver the Event Notification. 4. Some opaque data that the Printer delivers to the Notification Recipient in the Event Notification. For example, the Notification Recipient might use this opaque data as a forwarding address for the Event Notification. 5. The charset to use in text fields within an Event Notification 6. The natural language to use in the text fields of the Event Notification 7. The requested lease time in seconds for the Subscription Object An operation that creates a Subscription Object is called a Subscription Creation Operation. These operations include the following operations (see section 11.1 for further details): - Job Creation operation: When a client performs such an operation (Print-Job, Print-URI, and Create-Job), a client can include zero or more Subscription Template Attributes Groups in the request. The Printer creates one Subscription Object for each Subscription Template Attributes Group in the request, and the Printer associates each such Subscription Object with the newly created Job. This document extends these operations' definitions in [RFC2911] by adding Subscription Template Attributes Groups in the request and Subscription Attributes Groups in the response. - Create-Job-Subscriptions operation: A client can include one or more Subscription Template Attributes Groups in the request. The Printer creates one Subscription Object for each
Subscription Template Attributes Group and associates each with
the job that is the target of this operation.
- Create-Printer-Subscriptions operation: A client can include
one or more Subscription Template Attributes Groups in the
request. The Printer creates one Subscription Object for each
Subscription Template Attributes Group and associates each with
the Printer that is the target of this operation.
For each of the above operations:
- the Printer associates a Subscription Object with the Printer
or a specific Job. When a Subscription Object is associated
with a Job Object, it is called a Per-Job Subscription Object.
When a Subscription Object is associated with a Printer Object,
it is called a Per-Printer Subscription Object.
- the response contains one Subscription Attributes Group for
each Subscription Template Attributes Group in the request and
in the same order. When the Printer successfully creates a
Subscription Object, its corresponding Subscription Attributes
Group contains the "notify-subscription-id" attribute. This
attribute uniquely identifies the Subscription Object and is
analogous to a "job-id" for a Job object. Some operations
described below use the "notify-subscription-id" to identify
the target Subscription Object.
This document defines the following additional operations (see
section 11.2 for further details):
- Restart-Job operation: When a client performs the Restart-Job
operation [RFC2911], the Printer re-uses the same Job and its
Subscription Objects.
- Validate-Job operation: When a client performs this operation, a
client can include zero or more Subscription Template Attributes
Groups in the request. The Printer determines if it could create
one Subscription Object for each Subscription Template Attributes
Group in the request. This document extends this operation's
definition in [RFC2911] by adding Subscription Template Attributes
Groups in the request and Subscription Attributes Groups in the
response.
- Get-Subscription-Attributes operation: This operation allows a
client to obtain the specified attributes of a target Subscription
Object.
- Get-Subscriptions operation: This operation allows a client to
obtain the specified attributes of all Subscription Objects
associated with the Printer or a specified Job.
- Renew-Subscription operation: This operation renews the lease on
the target Per-Printer Subscription Object before it expires. A
newly created Per-Printer Subscription Object receives an initial
lease. It is the duty of the client to use this operation
frequently enough to preserve a Per-Printer Subscription Object.
The Printer deletes a Per-Printer Subscription Object when its
lease expires. A Per-Job Subscription Object last exactly as long
as its associated Job Object and thus doesn't have a lease.
- Cancel-Subscription operation: This operation (1) cancels the
lease on the specified Per-Printer Subscription Object and thereby
deletes the Per-Printer Subscription Object or (2) deletes the
Per-Job Subscription Object.
When an Event occurs, the Printer finds all Subscription Objects
listening for the Event (see section 9 for details on finding such
Subscription Objects). For each such Subscription Object, the
Printer:
a) generates an Event Notification with information specified in
section 9, AND
b) either:
i) If the Delivery Method is a Push Delivery Method as indicated
by the presence of the Subscription Object's "notify-
recipient-uri" attribute, delivers the Event Notification
using the Delivery Method and target address identified in the
Subscription Object's "notify-recipient-uri" attribute, OR
ii) If the Delivery Method is a Pull Delivery Method as indicated
by the presence of the Subscription Object's "notify-pull-
method" attribute, saves Event Notification for a time period
called the Event Life defined by the Delivery Method, i.e.,
the Notification Recipient is expected to fetch the Event
Notifications.
2. Models for Notification
2.1. Model for Simple Notification (Normative)
As part of a Subscription Creation Operation, an IPP Printer (i.e.,
located in an output device or a server) creates one or more
Subscription Objects. In a Subscription Creation Operation, the
client specifies the Notification Recipient to which the Printer is to deliver Event Notifications. A Notification Recipient can be the Subscribing Client or a third party. Figure 1 shows the Notification model for a simple Client-Printer relationship. embedded printer: output device or server PDA, desktop, or server +---------------+ +--------+ | ########### | | client |-----Subscription ---------># Printer # | +--------+ Creation Operation | # Object # | +------------+ | #####|##### | |Notification| +-------|-------+ |Recipient |<----IPP Event Notifications----+ +------------+ (Job and/or Printer Events) Figure 1 - Model for Notification2.2. Additional Models for Notification (Informative)
Additional models have been proposed (see Appendices 16, 17, and 18).3. Terminology
This section defines terminology used throughout this document. Other terminology is defined in [RFC2911].3.1. Conformance Terminology
Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 12.1. If an implementation supports the extension defined in this document, then these terms apply; otherwise, they do not. These terms define conformance to this document only; they do not affect conformance to other documents, unless explicitly stated otherwise. Note: a feature that is OPTIONAL in this document becomes REQUIRED if the Printer implements a Delivery Method that REQUIRES the feature. READ-ONLY - an adjective used in an attribute definition to indicate that an IPP Printer MUST NOT allow the attribute's value to be modified.
3.2. Other Terminology
This document uses the same terminology as [RFC2911], such as "client", "Printer", "attribute", "attribute value", "keyword", "operation", "request", "response", "administrator", "operator", and "support". In addition, the following terms are defined for use in this document and the Delivery Method Documents: Compound Event Notification - two or more Event Notifications that a Printer delivers together as a single request or response. The Delivery Method Document specifies whether the Delivery Method supports Compound Event Notifications. Delivery Method - the mechanism by which the Printer delivers an Event Notification. Delivery Method Document - a document, separate from this document, that defines a Delivery Method. Event - some occurrence (either expected or unexpected) within the printing system of a change of state, condition, or configuration of a Job or Printer object. An Event occurs only at one instant in time and does not span the time the physical Event takes place. For example, jam-occurred and jam-cleared are two distinct, instantaneous Events, even though the jam may last for a while. Event Life - For a Pull Delivery Method, the length of time in seconds after an Event occurs during which the Printer will retain that Event for delivery in an Event Notification. After the Event Life expires, the Printer will no longer deliver an Event Notification for that Event in such a response. Event Notification - the information about an Event that the Printer delivers when an Event occurs. Event Notification Attributes Group - The attributes group which is used to deliver an Event Notification in a request (Push Delivery Methods) or a response (Pull Delivery Methods). Human Consumable Event Notification - localized text for human consumption only. There is no standardized format and thus programs should not try to parse this text. Job Creation operation - One of the operations that creates a Job object: Print-Job, Print-URI and Create-Job. The Restart-Job operation [RFC2911] is not considered a Job Creation operation, since the Printer re-uses the existing Job object. The Validate-Job operation is not considered a Job Creation operation because no Job
object is created. Therefore, when a statement also applies to either the Restart-Job and/or the Validate-Job operation, they are mentioned explicitly. Job Event - an Event caused by some change in a particular job on the Printer, e.g., 'job-completed'. Machine Consumable Event Notification - bytes for program consumption. The bytes are formatted according to the Delivery Method document. Notification - when not in the phrases 'Event Notification' and 'Notification Recipient' - the concepts of this specification, i.e., Events, Subscription Objects, and Event Notifications. Notification Recipient - the entity to which the Printer delivers an Event Notification. For Push Delivery Methods, the IPP Printer sends the Notifications to a Notification Recipient. For Pull Delivery Methods, the Notification Recipient is acting in the role of an IPP client and requests Event Notifications and so the terms "client" and "Notification Recipient" are used interchangeably with such Delivery Methods. For example, see [RFC3996]. Per-Job Subscription Object - A Subscription Object that is associated with a single Job. The Create-Job-Subscriptions operation and Job Creation operations create such an object. Per-Printer Subscription Object - A Subscription Object that is associated with the Printer as a whole. The Create-Printer- Subscriptions operation creates such an object. Printer Event - an Event caused by some change in the Printer that is not specific to a job, e.g., 'printer-state-changed'. Pull Delivery Method - The Printer saves Event Notifications for some event life time and expects the Notification Recipient to request Event Notifications. The Printer delivers the Event Notifications in a response to such a request. Push Delivery Method -The Printer delivers the Event Notification shortly after an Event occurs. Subscribed Event - an Event that the Subscribing Client expresses interest in by making it a value of the "notify-events" attribute on a Subscription Object. Subscribed Job Event - a Subscribed Event that is a Job Event.
Subscribed Printer Event - a Subscribed Event that is a Printer Event. Subscribing Client - The client that creates the Subscription Object. Subscription Attributes Group - The attributes group in a response that contains Subscription Object attributes. Subscription Creation Operation - An operation that creates a Subscription Object: Job Creation operations, Create-Job- Subscriptions operation, Create-Printer-Subscriptions operation. In the context of a Job Creation operation, a Subscription Creation Operation is the part of the Job Creation operation that creates one or more Subscription objects. The Restart-Job operation [RFC2911] is not considered a Subscription Creation Operation, since the Printer re-uses the Job's existing Subscription Objects, rather than creating any new Subscription Objects. Subscription Creation Request - The request portion of a Subscription Creation Operation. Subscription Description Attributes - Subscription Object attributes that a Printer supplies during a Subscription Creation Operation. Subscription Object - An object containing a set of attributes that indicate: the Notification Recipient (for Push Delivery Method only), the Delivery Method, the Subscribed Events that cause the Printer to deliver an Event Notification, and the information to include in an Event Notification. Subscription Template Attributes - Subscription Object attributes that a client can supply in a Subscription Creation Operation and associated Printer Object attributes that specify supported and default values for the Subscription Object attributes. Subscription Template Attributes Group - The attributes group in a request that contains Subscription Object attributes that are Subscription Template Attributes.4. Object Relationships
This section defines the object relationships between the Printer, Job, and Subscription Objects. It does not define the implementation. For an illustration of these relationships, see Appendix 19.
4.1. Printer and Per-Printer Subscription Objects
1. A Printer object can be associated with zero or more Per-Printer Subscription Objects. 2. Each Per-Printer Subscription Object is associated with exactly one Printer object.4.2. Printer, Job and Per-Job Subscription Objects
1. A Printer object is associated with zero or more Job objects. 2. Each Job object is associated with exactly one Printer object. 3. A Job object is associated with zero or more Per-Job Subscription Objects. 4. Each Per-Job Subscription Object is associated with exactly one Job object.5. Subscription Object
A Subscribing Client creates a Subscription Object with a Subscription Creation Operation in order to indicate its interest in certain Events. See section 11 for a description of these operations. When an Event occurs, the Subscription Object specifies to the Printer where to deliver Event Notifications for Push Delivery Methods only, how to deliver them, and what to include in them. See section 9 for details on the contents of an Event Notification. Using the IPP Job Template attributes as a model (see [RFC2911] section 4.2), the attributes of a Subscription Object are divided into two categories: Subscription Template Attributes and Subscription Description Attributes. Subscription Template attributes are, in turn, like the Job Template attributes, divided into 1. Subscription Object attributes that a client can supply in a Subscription Creation Request and 2. their associated Printer Object attributes that specify supported and default values for the Subscription Object attributes The remainder of this section specifies general rules for Subscription Template Attributes and describes each attribute in a Subscription Object.
5.1. Rules for Support of Subscription Template Attributes
Subscription Template Attributes are fundamental to the Notification model described in this specification. The client supplies these attributes in Subscription Creation Operations and the Printer uses these attributes to populate a newly created Subscription Object. Subscription Objects attributes that are Subscription Template Attributes conform to the following rules: 1. Each attribute's name starts with the prefix string "notify-" and this document calls such attributes "notify-xxx". 2. For each "notify-xxx" Subscription Object attribute defined in column 1 of Table 1 in section 5.3, Table 1 specifies corresponding Printer attributes: "notify-xxx-default", "notify- xxx-supported", "yyy-supported" and "notify-max-xxx-supported" defined in column 2 of Table 1. Note "xxx" stands for the same string in each case and "yyy" stands for some other string. 3. If a Printer supports "notify-xxx" in column 1 of Table 1, then the Printer MUST support all associated attributes specified in column 2 of Table 1. For example, Table 1 shows that if the Printer supports "notify-events", it MUST support "notify-events- default", "notify-events-supported" and "notify-max-events- supported". 4. If a Printer does not support "notify-xxx" in column 1 of Table 1, then the Printer MUST NOT support any associated "notify-yyy" attributes specified in column 2 of Table 1. For example, Table 1 shows that if the Printer doesn't support "notify-events", it MUST NOT support "notify-events-default", "notify-events-supported" and "notify-max-events-supported". Note this rule does not apply to attributes whose names do not start with the string "notify-" and are thus defined in another object and used by other attributes. 5. Most "notify-xxx" attributes have a corresponding "yyy-supported" attribute that specifies the supported values for "notify-xxx". Column 2 of Table 1 specifies the name of each "yyy-supported" attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used when "yyy-supported" is "notify-xxx-supported". 6. Some "notify-xxx" attributes have a corresponding "notify-xxx- default" attribute that specifies the value for "notify-xxx" if the client does not supply it. Column 2 of Table 1 specifies the name of each "notify-xxx-default" attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used.
If a client wishes to present an end user with a list of supported values from which to choose, the client SHOULD query the Printer for its supported value attributes. The client SHOULD also query the default value attributes. If the client then limits selectable values to only those values that are supported, the client can guarantee that the values supplied by the client in the create request all fall within the set of supported values at the Printer. When querying the Printer, the client MAY enumerate each attribute by name in the Get-Printer-Attributes Request, or the client MAY just supply the 'subscription-template' group name in order to get the complete set of supported attributes (both supported and default attributes - see section 11.2.3).5.2. Rules for Processing Subscription Template Attributes
This section defines a detailed set of rules that a Printer follows when it processes Subscription Template Attributes in a Subscription Creation Request. These rules are similar to the rules for processing Operation attributes in [RFC2911]. That is, the Printer may or may not support an attribute and a client may or may not supply the attribute. Some combinations of these cases are OK. Others return warnings or errors, and perhaps a list of unsupported attributes. A Printer MUST implement the following behavior for processing Subscription Template Attributes in a Subscription Creation Request: 1. If a client supplies a "notify-xxx" attribute from column 1 of Table 1 and the Printer supports it and its value, the Printer MUST populate the attribute on the created Subscription Object. 2. If a client supplies a "notify-xxx" attribute from column 1 of Table 1 and the Printer doesn't support it or its value, the Printer MUST NOT populate the attribute on the created Subscription Object with it. The Printer MUST do one of the following: a) If the value of the "notify-xxx" attribute is unsupported, the Printer MUST return the attribute with its value in the Subscription Attributes Group of the response. b) If "notify-xxx" is an unsupported attribute, the Printer MUST return the attribute in the Subscription Attributes Group of the response with the 'unsupported' out-of-band value. Note: The rules of this step are the same as for Unsupported Attributes [RFC2911] section 3.1.7. except that the unsupported attributes are returned in the Subscription Attributes Group
rather than the Unsupported Attributes Group because Subscription
Creation Operations can create more than one Subscription Object).
3. If a client is REQUIRED to supply a "notify-xxx" attribute from
column 1 of Table 1 and the Printer doesn't support the supplied
value, the Printer MUST NOT create a Subscription Object. The
rules for Unsupported Attributes in step #2 still apply.
4. If a client does not supply a "notify-xxx" attribute from column 1
of Table 1 and the attribute is REQUIRED for the client to supply,
the Printer MUST reject the Subscription Creation Operation
(including Job Creation operations) without creating a
Subscription Object, and MUST return in the response:
a) the status code 'client-error-bad-request' AND
b) no Subscription Attribute Groups.
5. If a client does not supply a "notify-xxx" attribute from column 1
of Table 1 that is OPTIONAL for the client to supply, and column 2
of Table 1 either:
a) specifies a "notify-xxx-default" attribute, the Printer MUST
behave as if the client had supplied the "notify-xxx-default"
attribute (see step #1) and populate the Subscription object
with the value of the "notify-xxx-default" attribute as part of
the Subscription Creation operation (unlike Job Template
attributes where the Printer does not populate the Job object
with defaults - see [RFC2911]) OR
b) does not specify a "notify-xxx-default" attribute, the Printer
MUST populate the "notify-xxx" attribute on the Subscription
Object according to the definition of the "notify-xxx"
attribute in a section 5.3. For some attributes, the "notify-
xxx" is populated with the value of some other attribute, and
for others, the "notify-xxx" is NOT populated on the
Subscription object at all.
6. A Printer MUST create a Subscription Object for each Subscription
Template Attributes group in a request unless the Printer:
a) encounters some attributes in a Subscription Template
Attributes Group that require the Printer not to create the
Subscription Object OR
b) would create a Per-Job Subscription Object when it doesn't have
space for another Per-Job Subscription Object OR
c) would create a Per-Printer Subscription Object when it doesn't
have space for another Per-Printer Subscription Object.
7. A response MUST contain one Subscription Attributes Group for each
Subscription Template Attributes Group in the request (and in the
same order) whether the Printer creates a Subscription Object from
the Subscription Template Attributes Group or not. However, the
attributes in each Subscription Attributes Group can be in any
order.
8. The Printer MUST populate each Subscription Attributes Group of
the response such that each contains:
a) the "notify-subscription-id" attribute (see section 5.4.1), if
and only if the Printer creates a Subscription Object.
b) the "notify-lease-duration" attribute (see section 5.3.8), if
and only if the Printer creates a Per-Printer Subscription
Object. The value of this attribute is the value of the
Subscription Object's "notify-lease-duration" attribute. This
value MAY be different from the client-supplied value (see
section 5.3.8). If a client supplies this attribute in the
creation of a Per-Job Subscription Object, it MUST appear in
this group with the out-of-band value 'unsupported' to indicate
that the Printer doesn't support it in this context.
c) all of the unsupported Subscription Template Attributes from
step #2. Note, they are not returned in the Unsupported
Attributes Group in order to separate the unsupported
attributes for each Subscription Object.
d) the "notify-status-code" attribute if the Printer does not
create the Subscription Object or if there are unsupported
attributes from step #2. The possible values of the "notify-
status-code" attribute are shown below (see section 13 for more
details). The Printer returns the first value in the list
below that describes the status.
'client-error-uri-scheme-not-supported': the Subscription
Object was not created because the scheme of the "notify-
recipient-uri" attribute is not supported. See section 13.1
for more details about this status code. See step #3 in
this section for the case that causes this error, and the
resulting step #6a) that causes the Printer not to create
the Subscription Object.
'client-error-attributes-or-values-not-supported': the
Subscription Object was not created because the method of
the "notify-pull-method" attribute is not supported. See
section 13.1 for more details about this status code. See
step #3 in this section for the case that causes this error,
and the resulting step #6a) that causes the Printer not to
create the Subscription Object.
'client-error-too-many-subscriptions': the Subscription
Object was not created because the Printer has no space for
additional Subscription Objects. The client MAY try again
later. See section 13.3 for more details about this status
code. See steps #6b) and #6c) in this section for the cases
that causes this error.
'successful-ok-too-many-events': the Subscription Object was
created without the "notify-events" values included in this
Subscription Attributes Group because the "notify-events"
attribute contains too many values. See section 13.4 for
more details about this status code. See step #2 in this
section and section 5.3.3 for the cases that cause this
status code.
'successful-ok-ignored-or-substituted-attributes': the
Subscription Object was created but some supplied
Subscription Template Attributes are unsupported. These
unsupported attributes are also in the Subscription
Attributes Group. See section 13.5 for more details about
this status code. See step #2 in this section for the cases
that cause this status code.
9. The Printer MUST validate all Subscription Template Attributes and
MUST return all unsupported attributes and values in the
corresponding Subscription Attributes Group of the response (see
step #2) unless it determines that it could not create additional
Subscription Objects because of condition #6b) or condition #6c).
Then, the Printer NEED NOT validate these additional Subscription
Template Attributes and the client MUST NOT expect to find
unsupported attributes from step #2 in such additional
Subscription Attribute Groups.
(page 18 continued on part 2)
