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. Herriot & Hastings Standards Track [Page 1] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 2] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 3] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 4] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 . . . . . . . . . . . . . 78 1. 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 Herriot & Hastings Standards Track [Page 5] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 6] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 7] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 - 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 Herriot & Hastings Standards Track [Page 8] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Notification 2.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. Herriot & Hastings Standards Track [Page 9] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 10] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 11] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 12] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 13] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 14] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 15] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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 Herriot & Hastings Standards Track [Page 16] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 17] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 '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. 5.3. Subscription Template Attributes This section contains the Subscription Template Attributes defined for the Subscription and Printer objects. Herriot & Hastings Standards Track [Page 18] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 1 below shows the Subscription Template Attributes and has two columns: - Attribute in Subscription Object: the name and attribute syntax of each Subscription Object Attribute that is a Subscription Template Attribute - Default and Supported Printer Attributes: the default attribute and supported Printer attributes that are associated with the attribute in column 1. The "notify-recipient-uri" attribute is for use with Push Delivery Methods. The "notify-pull-method" attribute is for use with Pull Delivery Methods. For Push Delivery Methods, a Printer MUST support all attributes in Table 1 below except for "notify-pull-method" and "notify-attributes" (and "notify-pull-method-supported" and "notify-attributes- supported"). For Pull Delivery Methods, a Printer MUST support all attributes in Table 1 below except for "notify-recipient-uri" and "notify-attributes" (and "notify-schemes-supported" and "notify- attributes-supported"). If a Printer supports both Push and Pull Delivery Methods, then it MUST support both "notify-recipient-uri" and "notify-pull-method" attributes. For Pull Delivery Methods, a client MUST supply "notify-recipient- uri" and MAY omit any of the rest of the attributes in column 1 of Table 1 in a Subscription Creation Request. For Push Delivery Methods, a client MUST supply "notify-pull-method" and MAY omit any of the rest of the attributes in column 1 of Table 1 in a Subscription Creation Request. A client MUST NOT supply both "notify-recipient-uri" and "notify-pull-method" attributes in the same Subscription Creation Request. Note: The Default and Supported Printer attributes listed in column 2 of Table 1 do not have separate sections in this specification defining their semantics. Instead, the section for the corresponding Subscription Object attribute (column 1 of Table 1) contains the semantics of these Printer attributes. This approach follows the precedence of the Job Template attributes in section 4.2 of [RFC2911] where the corresponding "xxx-default" and "xxx-supported" Printer attributes are defined in the same section as the "xxx" Job attribute. Herriot & Hastings Standards Track [Page 19] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 1 - Subscription Template Attributes Attribute in Subscription Default and Supported Printer Object Attributes notify-recipient-uri (uri) * notify-schemes-supported (1setOf uriScheme) notify-pull-method (type2 notify-pull-method-supported (1setOf keyword) ** type2 keyword) notify-events (1setOf type2 notify-events-default (1setOf type2 keyword) keyword) notify-events-supported (1setOf type2 keyword) notify-max-events-supported (integer(2:MAX)) notify-attributes (1setOf notify-attributes-supported (1setOf type2 keyword) type2 keyword) notify-user-data (octetString(63)) notify-charset (charset) charset-supported (1setOf charset) notify-natural-language generated-natural-language-supported (naturalLanguage) (1setOf naturalLanguage) notify-lease-duration notify-lease-duration-default (integer(0:MAX)) (integer(0:67108863)) notify-lease-duration-supported (1setOf (integer(0: 67108863) | rangeOfInteger(0:67108863))) notify-time-interval (integer(0:MAX)) * "notify-recipient-uri" is for Push Delivery Methods only. ** "notify-pull-method" is for Pull Delivery Methods only. 5.3.1. notify-recipient-uri (uri) This attribute's value is a URL, which is a special case of a URI. Its value consists of a scheme and an address. The address specifies the Notification Recipient and the scheme specifies the Push Delivery Method for each Event Notification associated with this Subscription Object. If a Printer supports any Push Delivery Methods, a Printer MUST support this attribute and return the value as supplied by the client (no case conversion or other canonicalization) in any operation response that includes this attribute. Herriot & Hastings Standards Track [Page 20] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 For a Push Delivery Method, a client MUST supply this attribute in a Subscription Creation Operation. Thus there is no need for a default Printer attribute. The URI scheme of the value of this attribute on a Subscription object MUST be a value of the "notify-schemes-supported (1setOf uriScheme)" Printer attribute (see section 5.3.1.1). Note: According to [RFC2396] the ":" terminates the scheme and so is not part of the scheme. Therefore, values of the "notify-schemes-supported" Printer attribute do not include the ":" character. If the client supplies an unsupported scheme in the value of this attribute, then the Printer MUST NOT create the Subscription Object and MUST return the "notify-status-code" attribute with the 'client- error-uri-scheme-not-supported' value in the Subscription Attributes Group in the response. 5.3.1.1. notify-schemes-supported (1setOf uriScheme) This attribute contains the URI schemes supported in the "notify- recipient-uri" Subscription Template attribute. See sections 5.1 and 5.2 for the behavior of "xxx-supported" Subscription Template Printer attributes. 5.3.2. notify-pull-method (type2 keyword) This attribute's value is a type2 keyword indicating which Pull Delivery Method is to be used. Since a Printer MUST support the 'ippget' Pull Delivery Method [RFC3996] (see section 15), a Printer MUST support this attribute and return the value as supplied by the client in any operation response that includes this attribute. For a Pull Delivery Method, a client MUST supply this attribute in a Subscription Creation Operation. Thus there is no need for a default Printer attribute. The keyword value of this attribute on a Subscription object MUST be a value of the "notify-pull-method-supported (1setOf type2 keyword)" Printer attribute. If the client supplies an unsupported method in the value of this attribute, then the Printer MUST NOT create the Subscription Object and MUST return the "notify-status-code" attribute with the 'client- error-attributes-or-values-not-supported' value in the Subscription Attributes Group in the response. Herriot & Hastings Standards Track [Page 21] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 5.3.2.1. notify-pull-method-supported (1setOf type2 keyword) See sections 5.1 and 5.2 for the behavior of "xxx-supported" Subscription Template Printer attributes. 5.3.3. notify-events (1setOf type2 keyword) This attribute contains a set of Subscribed Events. When an Event occurs and it "matches" a value of this attribute, the Printer delivers an Event Notification using information in the Subscription Object. The details of "matching" are described subsection 5.3.3.5. A Printer MUST support this attribute. A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute in Subscription Creation Operation, the Printer MUST populate this attribute on the Subscription Object with its "notify-events-default" attribute value. Each keyword value of this attribute on a Subscription Object MUST be a value of the "notify-events-supported (1setOf type2 keyword)" Printer attribute. The number of values of this attribute MUST NOT exceed the value of the "notify-max-events-supported" attribute. A Printer MUST support at least 2 values per Subscription Object. If the number of values supplied by a client in a Subscription Creation Operation exceeds the value of this attribute, the Printer MUST treat extra values as unsupported values and MUST use the value of 'successful-ok-too- many-events' for the "notify-status-code" attribute in the Subscription Attributes Group of the response. 5.3.3.1. notify-events-default (1setOf type2 keyword) See sections 5.1 and 5.2 for the behavior of "xxx-default" Subscription Template Printer attributes. 5.3.3.2. notify-events-supported (1setOf type2 keyword) See sections 5.1 and 5.2 for the behavior of "xxx-supported" Subscription Template Printer attributes. Herriot & Hastings Standards Track [Page 22] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 5.3.3.3. notify-max-events-supported (integer(2:MAX)) This attribute specified the maximum number of events that the Printer supports for the "notify-events" Subscription Template attribute. See sections 5.1 and 5.2 for the behavior of "xxx- supported" Subscription Template Printer attributes. 5.3.3.4. Standard Values for Subscribed Events Each value of this attribute is a keyword and it specifies a Subscribed Event that represents certain changes. Some keywords represent a subset of changes of another keyword, e.g., 'job- completed' is an Event value which is a sub-value of 'job-state- change'. See section 5.3.3.5 for the case where this attribute contains both a value and a sub-value. The values in this section are divided into three categories: No Events, Job Events and Printer Events. A Printer MUST support the Events indicated as "REQUIRED" and MAY support the Events indicated as "OPTIONAL". 5.3.3.4.1. No Events The standard and only keyword value for No Events is: 'none': REQUIRED - no Event Notifications for any Events. As the sole value of "notify-events-supported", this value means that the Printer does not support the delivery of Event Notifications. As the sole value of "notify-events-default", this value means that a client MUST specify the "notify-events" attribute in order for a Subscription Creation Operation to succeed. If the Printer receives this value as the sole value of a Subscription Creation Operation, it does not create a Subscription Object. If a Printer receives this value with other values of a Subscription Creation Operation, the Printer MUST treat this value as an unsupported value. 5.3.3.4.2. Subscribed Printer Events The standard keyword values for Subscribed Printer Events are: 'printer-state-changed': REQUIRED - the Printer changed state from any state to any other state. Specifically, the value of the Printer's "printer-state", "printer-state-reasons" or "printer- is-accepting-jobs" attributes changed. Herriot & Hastings Standards Track [Page 23] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 This Subscribed Event value has the following sub-values: 'printer-restarted' and 'printer-shutdown'. A client can listen for any of these sub-values if it doesn't want to listen to all printer-state changes: 'printer-restarted': OPTIONAL - when the printer is powered up. 'printer-shutdown': OPTIONAL - when the device is being powered down. 'printer-stopped: REQUIRED - when the printer stops printing, i.e., the value of the "printer-state" Printer attribute becomes 'stopped'. 'printer-config-changed': OPTIONAL - when the configuration of a Printer has changed, i.e., the value of the "printer-message- from-operator" or any "configuration" Printer attribute has changed. A "configuration" Printer attribute is an attribute which can change value because of some human interaction either direct or indirect, and which is not covered by one of the other Events in this section. Examples of "configuration" Printer attributes are any of the Job Template attributes, such as "xxx- supported", "xxx-ready" and "xxx-default". The client has to perform a Get-Printer-Attributes to find out the new values of these changed attributes. This Event is useful for GUI clients and drivers to update the available printer capabilities to the user. This Event value has the following sub-values: 'printer-media- changed' and 'printer-finishings-changed'. A client can listen for any of these sub-values if it doesn't want to listen to all printer-configuration changes: 'printer-media-changed': OPTIONAL - when the media loaded on a printer has been changed, i.e., the "media-ready" attribute has changed. This Event includes two cases: an input tray that goes empty and an input tray that receives additional media of the same type or of a different type. The client must check the "media-ready" Printer attribute (see [RFC2911] section 4.2.11) separately to find out what changed. 'printer-finishings-changed': OPTIONAL - when the finisher on a printer has been changed, i.e., the "finishings-ready" attribute has changed. This Event includes two cases: a finisher that goes empty and a finisher that is refilled (even if it is not full). The client must check the Herriot & Hastings Standards Track [Page 24] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 "finishings-ready" Printer attribute separately to find out what changed. 'printer-queue-order-changed': OPTIONAL - the order of jobs in the Printer's queue has changed, so that an application that is monitoring the queue can perform a Get-Jobs operation to determine the new order. This Event does not include when a job enters the queue (the 'job-created' Event covers that) and does not include when a job leaves the queue (the 'job-completed' Event covers that). 5.3.3.4.3. Subscribed Job Events The standard keyword values for Subscribed Job Events are: 'job-state-changed': REQUIRED - the job has changed from any state to any other state. Specifically, the Printer delivers this Event whenever the value of the "job-state" attribute or "job-state- reasons" attribute changes. When a Job is removed from the Job Retention or Job History phases (see [RFC2911] section 4.3.7.1), no Event is generated. This Event value has the following sub-values: 'job-created', 'job-completed' and 'job-stopped'. A client can listen for any of these sub-values if it doesn't want to listen to all 'job-state changes'. 'job-created': REQUIRED - the Printer has accepted a Job Creation operation, a Restart-Job operation [RFC2911], or any job operation that creates a Job object from an existing Job object. The Printer populates the job's "time-at-creation" attribute value (see [RFC2911] section 4.3.14.1). The Printer puts the job in the 'pending', 'pending-held' or 'processing' states. 'job-completed': REQUIRED - the job has reached one of the completed states, i.e., the value of the job's "job-state" attribute has changed to: 'completed', 'aborted', or 'canceled'. The Job's "time-at-completed" and "date-time-at- completed" (if supported) attributes are set (see [RFC2911] section 4.3.14). When a Job completes, a Notification Recipient MAY query the Job using the Get-Job-Attributes operation. To allow such a query, the Printer retains the Job in the Job Retention and/or the Job History phases (see [RFC2911] section 4.3.7.1) for a suitable amount of time that depends on implementation and the Delivery Methods supported. The Printer also delivers this Event when a Job is removed with the Purge-Job operation (see [RFC2911] section 3.2.9). In this Herriot & Hastings Standards Track [Page 25] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 case, the Event Notification MUST report the 'job-state' as 'canceled' and the Job object is no longer present for query. 'job-stopped: OPTIONAL - when the job stops printing, i.e., the value of the "job-state" Job attribute becomes 'processing-stopped'. 'job-config-changed': OPTIONAL - when the configuration of a job has changed, i.e., the value of the "job-message-from-operator" or any of the "configuration" Job attributes have changed. A "configuration" Job attribute is an attribute that can change value because of some human interaction either direct or indirect. Examples of "configuration" Job attributes are any of the job template attributes and the "job-name" attribute. The client performs a Get-Job-Attributes to find out the new values of the changed attributes. This Event is useful for GUI clients and drivers to update the job information to the user. 'job-progress': OPTIONAL - when the Printer has completed Printing a sheet. See the separate [RFC3381] specification for additional attributes that a Printer MAY deliver in an Event Notification caused by this Event. The "notify-time-interval" attribute affects this Event by causing the Printer NOT to deliver an Event Notification every time a 'job-progress' Events occurs. See section 5.3.9 for full details. 5.3.3.5. Rules for Matching of Subscribed Events When an Event occurs, the Printer MUST find each Subscription object whose "notify-events" attribute "matches" the Event. The rules for "matching" of Subscribed Events are described separately for Printer Events and for Job Events. This section also describes some special cases. 5.3.3.5.1. Rules for Matching of Printer Events Given that the Printer causes Printer Event E to occur, for each Per-Job or Per-Printer Subscription S in the Printer, if E equals a value of this attribute in S or E is a sub-value of a value of this attribute in S, the Printer MUST generate an Event Notification. Consider the example. There are three Subscription Objects each with the Subscribed Printer Event 'printer-state-changed'. Subscription Object A is a Per-Printer Subscription Object. Subscription Object B is a Per-Job Subscription Object for Job 1, and Subscription Object C is a Per-Job Subscription Object for Job 2. When the Printer enters the 'stopped' state, the Printer delivers an Event Notification to the Notification Recipients of Subscription Objects A, B, and C Herriot & Hastings Standards Track [Page 26] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 because this is a Printer Event. Note if Job 1 has already completed, the Printer would not deliver an Event Notification for its Subscription Object, even if Job 1 is retained in the Job Retention and/or the Job History phases (see [RFC2911] section 4.3.7.1). 5.3.3.5.2. Rules for Matching of Job Events Given that Job J causes Job Event E to occur: 1. For each Per-Printer Subscription S in the Printer, if E equals a value of this attribute in S or E is a sub-value of a value of this attribute in S, the Printer MUST generate an Event Notification. 2. For each Per-Job Subscription S associated with Job J, if E equals a value of this attribute in S or E is a sub-value of a value of this attribute in S, the Printer MUST generate an Event Notification. 3. For each Per-Job Subscription S that is NOT associated Job J, if E equals a value of this attribute in S or E is a sub-value of a value of this attribute in, the Printer MUST NOT generate an Event Notification from S. Consider the example: There are three Subscription Objects listening for the Job Event 'job-completed'. Subscription Object A is a Per- Printer Subscription Object. Subscription Object B is a Per-Job Subscription Object for Job 1, and Subscription Object C is a Per-Job Subscription Object for Job 2. In addition, Per-Printer Subscription Object D is listening for the Job Event 'job-state-changed'. When Job 1 completes, the Printer delivers an Event Notification to the Notification Recipient of Subscription Object A (because it is Per- Printer) and Subscription Object B because it is a Per-Job Subscription Object associated with the Job generating the Event. The Printer also delivers an Event Notification to the Notification Recipient of Subscription Object D because 'job-completed' is a sub- value of 'job-state-changed' - the value that Subscription Object D is listening for. The Printer does not deliver an Event Notification to the Notification Recipients of Subscription Object C because it is a Per-Job Subscription Object associated with some Job other than the Job generating the Event. 5.3.3.5.3. Special Cases for Matching Rules This section contains two rules for the special case where a single Event produces multiple Event Notifications destined for the same Notification Recipient. These two rules clarify whether a Printer Herriot & Hastings Standards Track [Page 27] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 should send multiple Event Notifications or consolidate them into a single Event Notification. If an Event matches Subscribed Events in two different Subscription Objects and the Printer would deliver two identical Event Notifications (except for the "notify-subscription-id" attribute) to the same Notification Recipient using the same Delivery Method, the Printer MUST deliver both Event Notifications. That is, the Printer MUST NOT try to consolidate seemingly identical Event Notifications that occur in separate Subscription objects. Incidentally, the Printer MUST NOT reject Subscription Creation Operations that would create this scenario. Consider the example: At the time a Job completes, there are two Per-Printer Subscription Objects A and B with the same Notification Recipient R. Subscription Object A has the Subscribed Job Event 'job-state-changed'. Subscription Object B has the Subscribed Job Event 'job-completed'. Both Subscription Objects match the Event 'job-completed'. The Printer delivers two Event Notifications to the Notification Recipient R. One with the value of 'job-state-changed' for the "notify-subscribed-event" attribute and the other with the value of 'job-completed' for the "notify-subscribed-event" attribute. If an Event matches two Subscribed Events in a single Subscription object (e.g., a value and its sub-value), a Printer MAY deliver one Event Notification for each matched value in the Subscription Object or it MAY deliver only a single Event Notification. The rules in sections 5.3.3.5.1 and 5.3.3.5.2 are purposefully flexible about the number of Event Notifications sent when Event E matches two or more values in a Subscription Object. Consider the example: At the time a Job completes, a Subscription Object A has two Subscribed Job Events 'job-state-changed' and 'job- completed'. Both Subscribed Job Events match the Event 'job- completed'. The Printer delivers either one or two Event Notifications to the Notification Recipient of Subscription Object A, depending on implementation. If it delivers two Event Notifications, one has the value of 'job-state-changed' for the "notify- subscribed-event" attribute, and the other has the value of 'job- completed' for the "notify-subscribed-event" attribute. If it delivers one Event Notification, it has the value of either 'job- state-changed' or 'job-completed' for the "notify-subscribed-event" attribute, depending on implementation. The algorithm for choosing such a value is implementation dependent. Herriot & Hastings Standards Track [Page 28] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 5.3.4. notify-attributes (1setOf type2 keyword) This attribute contains a set of attribute names. When a Printer delivers a Machine Consumable Event Notification, it includes a fixed set of attributes (see section 9.1). If this attribute is present and the Event Notification is Machine Consumable, the Printer also includes the attributes specified by this attribute. A Printer MAY support this attribute. A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute in Subscription Creation Operation or the Printer does not support this attribute, the Subscription Object either (1) MAY contain the "notify-attributes" attribute with a 'none' value or (2) NEED NOT contain the attribute at all. There is no "notify-attributes- default" Printer attribute. Each keyword value of this attribute on a Subscription Object MUST be a value of the "notify-attributes-supported (1setOf type2 keyword)" Printer attribute (see section 5.3.4.1). The "notify-attributes- supported" MAY contain any Printer attribute, Job attribute or Subscription Object attribute that the Printer supports in an Event Notification. It MUST NOT contain any of the attributes in Section 9.1 that a Printer automatically puts in an Event Notification; it would be redundant. If a client supplies an attribute in Section 9.1, the Printer MUST treat it as an unsupported attribute value of the "notify-attributes" attribute. The following rules apply to each keyword value N of the "notify- attributes" attribute: If the value N names: a) a Subscription attribute, the Printer MUST use the attribute N in the Subscription Object that is being used to generate the Event Notification. b) a Job attribute and the Printer is generating an Event Notification from a Per-Job Subscription Object S, the Printer MUST use the attribute N in the Job object associated with S. c) a Job attribute and the Printer is generating an Event Notification from a Per-Printer Subscription Object and the Event is: - a Job Event, the Printer MUST use the attribute N in the Job object that caused the Event. Herriot & Hastings Standards Track [Page 29] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 - a Printer Event, the Printer MUST use the attribute N in the active Job. If a Printer supports this attribute and a Subscription Object contains this attribute and the Delivery Method generates a Machine Consumable Event Notification, the Printer MUST include in each Event Notification: a) the attributes specified in section 9.1 and b) each attribute named by this attribute. The Printer MUST NOT use this attribute to generate a Human Consumable Event Notification. 5.3.4.1. notify-attributes-supported (1setOf type2 keyword) See sections 5.1 and 5.2 for the behavior of "xxx-supported" Subscription Template Printer attributes. 5.3.5. notify-user-data (octetString(63)) This attribute contains opaque data that some Delivery Methods include in each Machine Consumable Event Notification. The opaque data might contain, for example: - the identity of the Subscriber - a path or index to some Subscriber information - a key that identifies to the Notification Recipient the ultimate recipient of the Event Notification - the id for a Notification Recipient that had previously registered with an Instant Messaging Service A Printer MUST support this attribute. A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute in the Subscription Creation Operation, the Subscription Object either (1) MAY contain the "notify-user-data" attribute with a zero length value or (2) NEED NOT contain the attribute at all. There is no "notify- user-data-default" Printer attribute. Herriot & Hastings Standards Track [Page 30] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 There is no "notify-user-data-supported" Printer attribute. Rather, any octetString whose length does not exceed 63 octets is a supported value. If the length exceeds 63 octets, the Printer MUST treat it as an unsupported value. 5.3.6. notify-charset (charset) This attribute specifies the charset to be used in the Event Notification content sent to the Notification Recipient, whether the Event Notification content is Machine Consumable or Human Consumable. A Printer MUST support this attribute. A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute in Subscription Creation Operation or supplies an unsupported value, the Printer MUST populate this attribute in the Subscription Object with the value of the "attributes-charset" operation attribute, which is a REQUIRED attribute in all IPP requests (see [RFC2911]). If the value of the "attributes-charset" attribute is unsupported, the Printer MUST populate this attribute in the Subscription Object with the value of the Printer's "charset-configured" attribute. There is no "notify-charset-default" Printer attribute. The value of this attribute on a Subscription Object MUST be a value of the "charset-supported (1setOf charset)" Printer attribute. 5.3.7. notify-natural-language (naturalLanguage) This attribute specifies the natural language to be used in any human consumable text in the Event Notification content sent to the Notification Recipient, whether the Event Notification content is Machine Consumable or Human Consumable. A Printer MUST support this attribute. A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute in Subscription Creation Operation or supplies an unsupported value, the Printer MUST populate this attribute in the Subscription Object with the value of the "attributes-natural-language" operation attribute, which is a REQUIRED attribute in all IPP requests (see [RFC2911] section 3.1.4). If the value of the "attributes-natural-language" attribute is unsupported, the Printer MUST populate this attribute in the Subscription Object with the value of the Printer's "natural- language-configured" attribute (see [RFC2911] section 4.4.19). There is no "notify-natural-language-default" Printer attribute. Herriot & Hastings Standards Track [Page 31] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 The value of this attribute on a Subscription Object MUST be a value of the "generated-natural-language-supported (1setOf type2 naturalLanguage)" Printer attribute (see [RFC2911] section 4.4.20). 5.3.8. notify-lease-duration (integer(0:67108863)) This attribute specifies the duration of the lease (in seconds) associated with the Per-Printer Subscription Object at the time the Subscription Object was created or the lease was renewed. The duration of the lease is infinite if the value is 0, i.e., the lease never expires. See section 5.4.3 on "notify-lease-expiration-time (integer(0:MAX))" for more details. This attribute is not present on a Per-Job Subscription Object because the Subscription Object lasts exactly as long as the associated Job object. See discussion of the 'job-completed' event in section 5.3.3.4.3 about retention of the Job object after completion. A Printer MUST support this attribute. For a Subscription Object Creation operation of a Per-Job Subscription Object, the client MUST NOT supply this attribute. If the client does supply this attribute, the Printer MUST treat it as an unsupported attribute. For a Subscription Creation Operation of a Per-Printer Subscription Object or a Renew-Subscription operation, a client MAY supply this attribute. If the client does not supply this attribute, the Printer MUST populate this attribute with its "notify-lease-duration-default" (0:67108863) attribute value. If the client supplies this attribute with an unsupported value, the Printer MUST populate this attribute with a supported value, and this value SHOULD be as close as possible to the value requested by the client. Note: this rule implies that a Printer doesn't assign the value of 0 (infinite) unless the client requests it. After the Printer has populated this attribute with a supported value, the value represents the "granted duration" of the lease in seconds and the Printer updates the value of the Subscription Object's "notify-lease-expiration-time" attribute as specified in section 5.4.3. The value of this attribute on a Subscription Object MUST be a value of the "notify-lease-duration-supported" (1setOf (integer(0:67108863) | rangeOfInteger(0:67108863))) Printer attribute. Herriot & Hastings Standards Track [Page 32] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 A Printer MAY require authentication in order to return the value of 0 (the lease never expires) as one of the values of "notify-lease- duration-supported", and to allow 0 as a value of the "notify-lease- duration" attribute. Note: The maximum value 67,108,863 is 2 raised to the 26 power minus 1 and is about 2 years in seconds. The value is considerably less than MAX so that there is virtually no chance of an overflow when the Printer adds it to the Printer's "printer-up-time" attribute value (see [RFC2911] section 4.4.29) to produce the "notify-lease- expiration-time" Subscription Description attribute value (see section 5.4.3). 5.3.8.1. notify-lease-duration-default (integer(0:67108863)) See sections 5.1 and 5.2 for the behavior of "xxx-default" Subscription Template Printer attributes. 5.3.8.2. notify-lease-duration-supported (1setOf (integer(0: 67108863) | rangeOfInteger(0:67108863))) See sections 5.1 and 5.2 for the behavior of "xxx-supported" Subscription Template Printer attributes. 5.3.9. notify-time-interval (integer(0:MAX)) The 'job-progress' Event occurs each time that a Printer completes a sheet. Some Notification Recipients do not want to receive an Event Notification every time this Event occurs. This attribute allows a Subscribing Client to request how often it wants to receive Event Notifications for 'job-progress' Events. The value of this attribute MAY be any nonnegative integer (0,MAX) indicating the minimum number of seconds between 'job-progress' Event Notifications. The Printer MUST support this attribute if and only if the Printer supports the 'job-progress' Event. A client MAY supply this attribute in a Subscription Creation Operation. If the client does not supply this attribute in the Subscription Creation Operation, the Subscription Object either (1) MAY contain the "notify-time-interval" attribute with a '0' value or (2) NEED NOT contain this attribute at all. There is no "notify- time-interval-default" Printer attribute. There is no "notify-time-interval-supported" Printer attribute. Herriot & Hastings Standards Track [Page 33] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 If the 'job-progress' Event occurs and a Subscription Object contains the 'job-progress' Event as a value of the 'notify-events' attribute, there are two cases to consider: 1. This attribute is not present on the Subscription Object or has the value of 0. The Printer MUST generate and deliver an Event Notification (as is the case with other Events). 2. This attribute is present with a nonzero value of N: a) If the Printer has not sent an Event Notification for the 'job-progress' Event for the associated Subscription Object within the past N seconds, the Printer MUST deliver an Event Notification for the Event that just occurred. Note when the Printer completes the first page of a Job, this rule implies that the Printer delivers an Event Notification for a Per-Job Subscription Object. b) Otherwise, the Printer MUST NOT generate or deliver an Event Notification for the associated Subscription Object. The Printer MUST NOT increase the value of the "notify-sequence- number" Subscription Object attribute (i.e., the sequence of values of the "notify-sequence-number" attribute counts the Event Notifications that the Printer sent and not the Events that do not cause an Event Notification to be sent). It is RECOMMENDED that a Subscribing Client use this attribute when it subscribes to the 'job-progress' Event, and that the value be sufficiently large to limit the frequency with which the Printer delivers Event Notifications requests. This attribute MUST NOT effect any Events other than 'job-progress'. 5.4. Subscription Description Attributes Subscription Description Attributes are those attributes that a Printer adds to a Subscription Object at the time of its creation. A Printer MUST support all attributes in this Table 2. A client MUST NOT supply the attributes in Table 2 in a Subscription Template Attributes Group of a Subscription Creation Operation. There are no corresponding default or supported attributes. Herriot & Hastings Standards Track [Page 34] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 2 - Subscription Description Attributes Subscription Object attributes: notify-subscription-id (integer(1:MAX)) notify-sequence-number (integer(0:MAX)) notify-lease-expiration-time (integer(0:MAX)) notify-printer-up-time (integer(1:MAX)) notify-printer-uri (uri) notify-job-id (integer(1:MAX)) notify-subscriber-user-name (name(MAX)) 5.4.1. notify-subscription-id (integer (1:MAX)) This attribute identifies a Subscription Object instance with a number that is unique within the context of the Printer. The Printer generates this value at the time it creates the Subscription Object. A Printer MUST support this attribute. The Printer MAY assign the value of this attribute sequentially as it creates Subscription Objects. However, if there is no security on Subscription objects, sequential assignment exposes the system to a passive traffic monitoring threat. The Printer SHOULD avoid re-using recent values of this attribute during continuous operation of the Printer as well as across power cycles. Then a Subscribing Client is unlikely to find that a stale reference accesses a new Subscription Object. The 0 value is not permitted in order to allow for compatibility with "job-id" and with MIB table index values, which are recommended not to be 0. 5.4.2. notify-sequence-number (integer (0:MAX)) The value of this attribute indicates the number of times that the Printer has generated and attempted to deliver an Event Notification for this Subscription object. When an Event Notification contains this attribute, the Notification Recipient can determine whether it missed some Event Notifications (i.e., numbers skipped) or received duplicates (i.e., same number twice). A Printer MUST support this attribute. When the Printer creates a Subscription Object, it MUST populate this attribute with a value of 0. This value indicates that the Printer has not sent any Event Notifications for this Subscription Object. Herriot & Hastings Standards Track [Page 35] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Each time the Printer delivers a newly generated Event Notification, it MUST increase the value of this attribute by 1. For some Delivery Methods, the Printer MUST include this attribute in each Event Notification, and the value MUST be the value after it is increased by 1. That is, the value of this attribute in the first Event Notification after Subscription object creation MUST be 1, the second MUST be 2, etc. If a Delivery Method is defined such that the Notification Recipient returns a response, the Printer can re-try delivering an Event Notification a certain number of times with the same sequence number when the Notification Recipient fails to return a response. If a Subscription Object lasts long enough to reach the value of MAX, its next value MUST be 0, i.e., it wraps. 5.4.3. notify-lease-expiration-time (integer(0:MAX)) This attribute specifies the time in the future when the lease on the Per-Printer Subscription Object will expire, i.e., the "printer-up- time" value at which the lease will expire. If the value is 0, the lease never expires. A Printer MUST support this attribute. When the Printer creates a Per-Job Subscription Object, this attribute MUST NOT be present - the Subscription Object lasts exactly as long as the associated Job object. See also the discussion of the 'job-completed' event in section 5.3.3.4.3 about retention of the Job object after completion so that a Notification Recipient can query the Job object after receiving the 'job-completed' Event Notification. When the Printer creates a Per-Printer Subscription Object, it populates this attribute with a value that is the sum of the values of the Printer's "printer-up-time" attribute and the Subscription Object's "notify-lease-duration" attribute with the following exception. If the value of the Subscription Object's "notify-lease- duration" attribute is 0 (i.e., no expiration time), then the value of this attribute MUST be set to 0 (i.e., no expiration time). When the Printer powers up, it MUST populate this attribute in each persistent Subscription Object with a value using the algorithm in the previous paragraph. When the "printer-up-time" equals the value of this attribute, the Printer MUST delete the Subscription Object. A client can extend a lease of a Per-Printer Subscription Object with the Renew- Subscription operation (see section 11.2.6). Herriot & Hastings Standards Track [Page 36] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Note: In order to compute the number of seconds remaining in a lease for a Per-Printer Subscription Object, a client can subtract the Subscription's "notify-printer-up-time" attribute (see section 5.4.4) from the Subscription's "notify-lease-expiration-time" attribute. 5.4.4. notify-printer-up-time (integer(1:MAX)) This attribute is an alias for the Printer's "printer-up-time" attribute " (see [RFC2911] section 4.4.29). In other words, when this attribute is queried with the Get-Subscriptions or Get- Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), the value returned is the current value of the Printer's "printer- up-time" attribute, rather than the time at which the Subscription Object was created. A Printer MUST support this attribute. When the Printer creates a Per-Job Subscription Object, this attribute MUST NOT be present. When the Printer creates a Per- Printer Subscription Object, this attribute MUST be present. Note: this attribute exists in a Per-Printer Subscription Object so that a client using the Get-Subscription-Attributes or Get- Subscription operations can convert the Per-Printer Subscription's "notify-lease-expiration-time" attribute to wall clock time with one request. If the value of the "notify-lease-expiration-time" attribute is not 0 (i.e., no expiration time), then the difference between the "notify-lease-expiration-time" attribute and the "notify-printer-up-time" is the remaining number of seconds on the lease from the current time. 5.4.5. notify-printer-uri (uri) This attribute identifies the Printer object that created this Subscription Object. A Printer MUST support this attribute. During a Subscription Creation Operation, the Printer MUST populate this attribute with the value of the "printer-uri" operation attribute in the request. From the Printer URI, the client can, for example, determine what security scheme was used. 5.4.6. notify-job-id (integer(1:MAX)) This attribute specifies whether the containing Subscription Object is a Per-Job or Per-Printer Subscription Object, and for Per-Job Subscription Objects, it specifies the associated Job. Herriot & Hastings Standards Track [Page 37] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 A Printer MUST support this attribute. If this attribute is not present, the Subscription Object MUST be a Per-Printer Subscription. If this attribute is present, the Subscription Object MUST be a Per-Job Subscription Object and this attribute MUST identify the Job with which the Subscription Object is associated. Note: This attribute could be useful to a Notification Recipient that receives an Event Notification generated from a Per-Job Subscription Object and caused by a Printer Event. The Event Notification gives access to the Printer and the Subscription Object. The Event Notification gives access to the associated Job only via this attribute. See discussion of the 'job-completed' event in section 5.3.3.4.3 about retention of the Job object after completion so that a Notification Recipient can query the Job object after receiving the 'job-completed' Event Notification. 5.4.7. notify-subscriber-user-name (name(MAX)) This attribute contains the name of the user who performed the Subscription Creation Operation. A Printer MUST support this attribute. The Printer MUST populates this attribute with the most authenticated printable name that it can obtain from the authentication service over which the Subscription Creation Operation was received. The Printer uses the same mechanism for determining the value of this attribute as it does for a Job's "job-originating-user-name" (see [RFC2911] section 4.3.6). Note: To help with authentication, a Subscription Object may have additional private attributes about the user, e.g., a credential of a principal. Such private attributes are implementation-dependent and not defined in this document. 6. Printer Description Attributes Related to Notification This section defines the Printer Description attributes that are related to Notification. Table 3 lists the Printer Description attributes, indicates the Printer support required for conformance, and whether or not the attribute is READ-ONLY (see section 3.1): Herriot & Hastings Standards Track [Page 38] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 3 - Printer Description Attributes Associated with Notification Printer object attributes: REQUIRED READ-ONLY printer-state-change-time (integer(1:MAX)) No Yes printer-state-change-date-time (dateTime) No Yes 6.1. printer-state-change-time (integer(1:MAX)) This OPTIONAL attribute records the most recent time at which the 'printer-state-changed' Printer Event occurred whether or not any Subscription objects were listening for this event. This attribute helps a client or operator to determine how long the Printer has been in its current state. A Printer MAY support this attribute and if so, the attribute MUST be READ-ONLY. On power-up, the Printer MUST populate this attribute with the value of its "printer-up-time" attribute, so that it always has a value. Whenever the 'printer-state-changed' Printer Event occurs, the Printer MUST update this attribute with the value of the Printer's "printer-up-time" attribute. 6.2. printer-state-change-date-time (dateTime) This OPTIONAL attribute records the most recent time at which the 'printer-state-changed' Printer Event occurred whether or not there were any Subscription Objects listening for this event. This attribute helps a client or operator to determine how long the Printer has been in its current state. A Printer MAY support this attribute and if so, the attribute MUST be READ-ONLY. On power-up, the Printer MUST populate this attribute with the value of its "printer-current-time" attribute, so that it always has a value (see [RFC2911] section 4.4.30 on "printer-current-time"). Whenever the 'printer-state-changed' Printer Event occurs, the Printer MUST update this attribute with the value of the Printer's "printer-current-time" attribute. 7. New Values for Existing Printer Description Attributes This section contains those attributes for which additional values are added. Herriot & Hastings Standards Track [Page 39] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 7.1. operations-supported (1setOf type2 enum) The following "operation-id" values are added in order to support the new operations defined in this document: Table 4 - Operation-id assignments Value Operation Name 0x0016 Create-Printer-Subscriptions 0x0017 Create-Job-Subscriptions 0x0018 Get-Subscription-Attributes 0x0019 Get-Subscriptions 0x001A Renew-Subscription 0x001B Cancel-Subscription 8. Attributes Only in Event Notifications This section contains those attributes that exist only in Event Notifications and do not exist in any objects. 8.1. notify-subscribed-event (type2 keyword) This attribute indicates the Subscribed Event that caused the Printer to deliver this Event Notification. This attribute exists only in Event Notifications. This attribute MUST contain one of the values of the "notify-events" attribute in the Subscription Object, i.e., one of the Subscribed Event values. Its value is the Subscribed Event that "matches" the Event that caused the Printer to deliver this Event Notification. This Subscribed Event value may be identical to the Event or the Event may be a sub-value of the Subscribed Event. For example, the 'job-completed' Event (which is a sub-event of the 'job-state- changed' event) would cause the Printer to deliver an Event Notification for either the 'job-completed' or 'job-state-changed' Subscribed Events and to deliver the 'job-completed' or 'job-state- changed' value for this attribute, respectively. See section 5.3.3.5 for the "matching" rules of Subscribed Events and for additional examples. The Delivery Method Document specifies whether the Printer includes the value of this attribute in an Event Notification. Herriot & Hastings Standards Track [Page 40] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 8.2. notify-text (text(MAX)) This attribute contains a Human Consumable text message (see section 9.2). This message describes the Event and is encoded as plain text, i.e., 'text/plain' with the charset specified by Subscription Object's "notify-charset" attribute. Note: this attribute contains a text message only and must not contain any encoding information, such as 'text/plain'. The 'text/plain' encoding is implicit and thus the charset must be specified by an alternate mechanism, namely the "notify-charset" attribute. The Delivery Method Document specifies whether the Printer includes this attribute in an Event Notification. 9. Event Notification Content This section defines the Event Notification content that the Printer delivers when an Event occurs. When an Event occurs, the Printer MUST find each Subscription object whose "notify-events" attribute "matches" the Event. See section 5.3.3.5 for details on "matching". For each matched Subscription Object, the Printer MUST create an Event Notification with the content and format that the Delivery Method Document specifies. The content contains the value of attributes specified by the Delivery Method Document. The Printer obtains the values immediately after the Event occurs. For example, if the "printer-state" attribute changes from 'idle' to 'processing', the Event 'printer-state- changed' occurs and the Printer puts various attributes into the Event Notification, including "printer-up-time" and "printer-state" with the values that they have immediately after the Event occurs, i.e., the value of "printer-state" is 'processing'. Event Notification Ordering: When a Printer delivers Event Notifications, the Event Notifications from any given Subscription Object MUST be in time stamp order, i.e., in order of increasing "printer-up-time" attribute value in the Event Notification (see Table 5). These Event Notifications MAY be interleaved with those from other Subscription Objects, as long as those others are also in time stamp order. The Printer MUST observe these ordering requirements whether delivering multiple pending Events as multiple separate Event Notifications or together in a single Compound Event Notification. Herriot & Hastings Standards Track [Page 41] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 If a Subscribing Client wants the Printer to deliver certain Event Notifications in time stamp order, the Subscribing Client uses a single Subscription Object. Even so, depending on the underlying transport, the actual order that a Notification Recipient receives separate Event Notifications may differ from the order sent by the Printer (e.g., email). Example: Consider two Per-Printer Subscription Objects: SO1 and SO2. SO1 requests 'job-state-changed' events and SO2 requests 'printer- state-changed' events. The number in parens is the time stamp. The following Event Notification sequences are the only ones that conform to the ordering requirements for the Printer to deliver the Event Notifications: (a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 'job-completed' (1009), SO2: 'printer-stopped' (1005) (b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2: 'printer-stopped' (1005), SO1: 'job-completed' (1009) (c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1: 'job-stopped' (1005), SO1: 'job-completed' (1009) (d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 'job-completed' (1009) Examples (b) and (c) are interleaved; examples (a) and (d) are not interleaved and are not appropriate for some Delivery Methods. If two different Events occur simultaneously, or nearly so (e.g., "printer-up-time" has the same value for both), the Printer MUST create a separate Event Notification for each Event, even if the associated Subscription Object is the same for both Events. However, the Printer MAY combine these distinct Event Notifications into a single Compound Event Notification if the Delivery Method supports Compound Event Notifications. For example, suppose that two nearly- simultaneously Events represent two successive 'printer-state- changed' Events, one from 'idle' to 'processing' and another from 'processing' to 'stopped'. These two Events have the same name but are different instances of the Event. Then the Printer MUST create a separate Event Notification for each Event and SHOULD accurately report the "printer-state" of the first Event as 'processing' and the second Event as 'stopped'. If a Subscription Object contains more than one Subscribed Event, and several Events occur in quick succession each matching a different Subscribed Event in the Subscription Object, the Printer MUST NOT generate a single Event Notification from several of these Events, Herriot & Hastings Standards Track [Page 42] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 but MAY combine distinct Event Notifications into a single Compound Event Notification if the Delivery Method supports Compound Event Notifications. After the Printer has created the Event Notification, the Printer delivers it via either a: Push Delivery Method: The Printer delivers the Event Notification shortly after an Event occurs. For some Push Delivery Methods, the Notification Recipient MUST deliver a response; for others it MUST NOT deliver a response. Pull Delivery Method: The Printer saves Event Notifications for some Event Life and expects the Notification Recipient to request Event Notifications. The Printer returns the Event Notifications in a response to such a request. If an error that meets the following conditions occurs, the Printer MUST cancel the Subscription Object. a) the error occurs during the delivering of an Event Notification generated from Subscription Object S AND b) the error would continue to occur every time the Printer delivers an Event Notification generated from Subscription Object S in the future. For example, if the address of the "notify-recipient-uri" of Subscription Object A references a non-existent target and the Printer determines this fact, it MUST delete Subscription Object A. The next two sections describe the values that a Printer delivers in the content of Machine Consumable and Human Consumable Event Notifications, respectively. The tables in the sub-sections of this section contain the following columns: a) Source Value: the name of the attribute that supplies the value for the Event Notification. Asterisks in this field refer to a note below the table. b) Delivers: if the Printer supports the value (column 1) on the Source Object (column 3) the Delivery Method MUST specify: MUST: that the Printer MUST deliver the value. Herriot & Hastings Standards Track [Page 43] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 SHOULD: either that the Printer MUST deliver the value or that the value is incompatible with the Delivery Method. MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED NOT deliver the value. The Delivery Method specifies the level of conformance for the Printer. c) Source Object: the object from which the source value comes. If the object is "Event Notification", the Printer fabricates the value when it delivers the Event Notification. See section 8. 9.1. Content of Machine Consumable Event Notifications This section defines the attributes that a Delivery Method MUST mention in a Delivery Method Document when specifying the Machine Consumable Event Notification's contents. This document does not define the order of attributes in Event Notifications. However, Delivery Method Documents MAY define the order of some or all of the attributes. A Delivery Method Document MUST specify additional attributes (if any) that a Printer implementation delivers in a Machine Consumable Event Notification. Notification Recipients MUST be able to accept Event Notifications containing attributes they do not recognize. What a Notification Recipient does with an unrecognized attribute is implementation- dependent. Notification Recipients MAY attempt to display unrecognized attributes anyway or MAY ignore them. The next three sections define the attributes in Event Notification Contents that are: 1. for all Events 2. for Job Events only 3. for Printer Events only 9.1.1. Event Notification Content Common to All Events This section lists the attributes that a Delivery Method Document MUST specify for all Events. Table 5 lists potential values in each Event Notification. Herriot & Hastings Standards Track [Page 44] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 5 - Attributes in Event Notification Content Source Value Delivers Source Object notify-subscription-id (integer(1:MAX)) MUST Subscription notify-printer-uri (uri) MUST Subscription notify-subscribed-event (type2 keyword) MUST Event Notification printer-up-time (integer(MIN:MAX)) MUST Printer printer-current-time (dateTime) * MUST Printer notify-sequence-number (integer (0:MAX)) SHOULD Subscription notify-charset (charset) SHOULD Subscription notify-natural-language (naturalLanguage) SHOULD Subscription notify-user-data (octetString(63)) ** SHOULD Subscription notify-text (text) SHOULD Event Notification attributes from the "notify-attributes" MAY Printer attribute *** attributes from the "notify-attributes" MAY Job attribute *** attributes from the "notify-attributes" MAY Subscription attribute *** *A Printer MUST deliver this value only if and only if it supports the Printer's "printer-current-time" attribute. ** If the Subscription Object does not contain a "notify-user-data" attribute and the Delivery Method Document REQUIRES the Printer to deliver the "notify-user-data" source value in the Event Notification, the Printer MUST deliver an octet-string of length 0. *** The last three rows represent additional attributes that a client MAY request via the "notify-attributes" attribute. A Printer MAY support the "notify-attributes" attribute. The Delivery Method MUST say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED NOT support the "notify-attributes" attribute and specific values of this attribute. The Delivery Method MAY say that support for the "notify-attributes" is conditioned on support of the attribute by the Printer or it MAY say that Printer MUST support the "notify- attributes" attribute if the Printer supports the Delivery Method. 9.1.2. Additional Event Notification Content for Job Events This section lists the additional attributes that a Delivery Method Document MUST specify for Job Events. See Table 6. Herriot & Hastings Standards Track [Page 45] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 6 - Additional Event Notification Content for Job Events Source Value Delivers Source Object job-id (integer(1:MAX)) MUST Job job-state (type1 enum) MUST Job job-state-reasons (1setOf type2 keyword) MUST Job job-impressions-completed (integer(0:MAX)) * MUST Job * The Printer MUST deliver the "job-impressions-completed" attribute in an Event Notification only for the combinations of Events and Subscribed Events shown in Table 7. Table 7 - Combinations of Events and Subscribed Events for "job- impressions-completed" Job Event Subscribed Job Event 'job-progress' 'job-progress' 'job-completed' 'job-completed' 'job-completed' 'job-state-changed' 9.1.3. Additional Event Notification Content for Printer Events This section lists the additional attributes that a Delivery Method Document MUST specify for Printer Events. See Table 8. Table 8 - Additional Event Notification Content for Printer Events Source Value Delivers Source Object printer-state (type1 enum) MUST Printer printer-state-reasons (1setOf type2 MUST Printer keyword) printer-is-accepting-jobs (boolean) MUST Printer 9.2. Content of Human Consumable Event Notification This section defines the information that a Delivery Method MUST mention in a Delivery Method Document when specifying the Human Consumable Event Notifications contents or the value of the "notify- text" attribute. Such a Delivery Method MUST specify the following information and a Printer SHOULD deliver it: a) the Printer name (see Table 9) Herriot & Hastings Standards Track [Page 46] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 b) the time of the Event (see Table 11) c) for Printer Events only: i) the Event (see Table 10) and/or Printer state information (see Table 14) d) for Job Events only: i) the job identity (see Table 12) ii) the Event (see Table 10) and/or Job state information (see Table 13) The subsections of this section specify the attributes that a Printer MUST use to obtain this information. A Delivery Method Document MUST specify additional information (if any) that a Printer implementation delivers in a Human Consumable Event Notification or in the "notify-text" attribute. A client MUST NOT request additional attributes via the "notify- attributes" attribute because this attribute works only for Machine Consumable Event Notifications. Notification Recipients MUST NOT expect to be able to parse the Human Consumable Event Notification contents or the value of the "notify- text" attribute. The next three sections define the attributes in Event Notification Contents that are: a) for all Events b) for Job Events only c) for Printer Events only 9.2.1. Event Notification Content Common to All Events This section lists the source of the information that a Delivery Method MUST specify for all Events. There is a separate table for each piece of information. Each row in the table represents a source value for the information and the values are listed in order of preference, with the first one being the preferred one. An implementation SHOULD use the source value from the earliest row in each table. It MAY use the source value Herriot & Hastings Standards Track [Page 47] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 from another row instead, or it MAY combine the source values from several rows. An implementation is free to determine the best way to present this information. In all tables of this section, all rows contain a "MAY" in order to state that the Delivery Method specifies the conformance. Table 9 lists the source of the information for the Printer Name. The "printer-name" is more user-friendly unless the Notification Recipient is in a place where the Printer name is not meaningful. For example, an implementation could have the intelligence to deliver the value of the "printer-name" attribute to a Notification Recipient that can access the Printer via value of the "printer-name" attribute and otherwise deliver the value of the "notify-printer-uri" attribute. Table 9 - Printer Name in Event Notification Content Source Value Delivers Source Object printer-name (name(127)) MAY Printer notify-printer-uri (uri) MAY Subscription Table 10 lists the source of the information for the Event name. A Printer MAY combine this information with state information described for Jobs in Table 13 or for Printers in Table 14. Table 10 - Event Name in Event Notification Content Source Value Delivers Source Object notify-subscribed-event (type2 keyword) MAY Subscription Table 11 lists the source of the information for the time that the Event occurred. A Printer can deliver this value only if it supports the Printer's "printer-current-time" attribute. If a Printer does not support the "printer-current-time" attribute, it MUST NOT deliver the "printer-up-time" value instead, since it is not an allowed option for human consumable information. Table 11 - Event Time in Event Notification Content Source Value Delivers Source Object printer-current-time (dateTime) MAY Printer Herriot & Hastings Standards Track [Page 48] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 9.2.2. Additional Event Notification Content for Job Events This section lists the source of the additional information that a Delivery Method MUST specify for Job Events. Table 12 lists the source of the information for the job name. The "job-name" is likely more meaningful to a user than "job-id". Table 12 - Job Name in Event Notification Content Source Value Delivers Source Object job-name (name(MAX)) MAY Job job-id (integer(1:MAX)) MAY Job Table 13 lists the source of the information for the job state. If a Printer supports the "job-state-message" and "job-detailed-state- message" attributes, it SHOULD use those attributes for the job state information, otherwise, it should fabricate such information from the "job-state" and "job-state-reasons". For some Events, a Printer MAY combine this information with Event information. Table 13 - Job State in Event Notification Content Source Value Delivers Source Object job-state-message (text(MAX)) MAY Job job-detailed-status-messages (1setOf text(MAX)) MAY Job job-state (type1 enum) MAY Job job-state-reasons (1setOf type2 keyword) MAY Job 9.2.3. Additional Event Notification Content for Printer Events This section lists the source of the additional information that a Delivery Method MUST specify for Printer Events. Table 14 lists the source of the information for the printer state. If a Printer supports the "printer-state-message", it SHOULD use that attribute for the job state information, otherwise it SHOULD fabricate such information from the "printer-state" and "printer- state-reasons". For some Events, a Printer MAY combine this information with Event information. Herriot & Hastings Standards Track [Page 49] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 Table 14 - Printer State in Event Notification Content Source Value Delivers Source Object printer-state-message (text(MAX)) MAY Printer printer-state (type1 enum) MAY Printer printer-state-reasons (1setOf type2 keyword) MAY Printer printer-is-accepting-jobs (boolean) MAY Printer 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. Herriot & Hastings Standards Track [Page 50] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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? Herriot & Hastings Standards Track [Page 51] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 52] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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. Herriot & Hastings Standards Track [Page 53] RFC 3995 IPP: Event Notifications and Subscriptions March 2005 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