RFC 3995
Internet Printing Protocol (IPP): Event Notifications and Subscriptions
RFC 3995: Internet Printing Protocol (IPP) Event Notifications and Subscriptions 🖨️✨
okay bestie, this one is all about printers telling you stuff. 🖨️💅 It's RFC 3995, and it's Standards Track, which means it's an actual Internet standard and not just a vibe. 👑
It's written by R. Herriot (Global Workflow Solutions) and T. Hastings (Xerox Corporation). It's dated March 2005 and it's part of the "Network Working Group" crew. 🧚
It updates RFC 2911 and RFC 2910, so it's adding to those docs and not replacing them. The header doesn't list anything it obsoletes. 🎀
Status of This Memo 📜
this doc is an Internet standards track protocol spec for the Internet community, and it's literally asking for discussion and suggestions for improvements. 💬🫶 if you want to know where this protocol stands on the official standardization ladder, check the "Internet Official Protocol Standards" (STD 1) list. 📋 and distribution of this memo is unlimited, so share it with everyone 🌈
Copyright Notice ©️
Copyright (C) The Internet Society (2005). 💜
Abstract ✨
okay so the big idea 🦋 this doc describes an OPTIONAL extension to the Internet Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). so you don't have to implement it, but if you do, here's what you get 💅
the extension lets a client subscribe to printing related Events. 🔔 subscriptions are modeled as Subscription Objects, and the vibe is: when one of the Events you picked happens, the Printer sends an asynchronous Event Notification to the Notification Recipient you named, using the Push or Pull Delivery Method you chose (aka the protocol). 📨✨ it's giving "tell me when my print is done, please" energy 😭
a client can attach Subscription Objects to a particular Job in two ways. 🎯 one is by using the Create-Job-Subscriptions operation. the other is by submitting a Job with subscription info included. 🧃
to attach Subscription Objects to the Printer itself, the client uses the Create-Printer-Subscriptions operation. 🖨️💖
there are four more operations for Subscription Objects too: Get-Subscriptions-Attributes, Get-Subscriptions, Renew-Subscription, and Cancel-Subscription. 🧚 that's a whole lifecycle, bestie: make it, check it, renew it, cancel it. 💅
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notification Overview. . . . . . . . . . . . . . . . . . 5
2. Models for Notification. . . . . . . . . . . . . . . . . . . . 8
2.1. Model for Simple Notification (Normative). . . . . . . . 8
2.2. Additional Models for Notification (Informative) . . . . 9
3. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1. Conformance Terminology. . . . . . . . . . . . . . . . . 9
3.2. Other Terminology. . . . . . . . . . . . . . . . . . . . 10
4. Object Relationships . . . . . . . . . . . . . . . . . . . . . 12
4.1. Printer and Per-Printer Subscription Objects . . . . . . 13
4.2. Printer, Job and Per-Job Subscription Objects. . . . . . 13
5. Subscription Object. . . . . . . . . . . . . . . . . . . . . . 13
5.1. Rules for Support of Subscription Template Attributes. . 14
5.2. Rules for Processing Subscription Template Attributes. . 15
5.3. Subscription Template Attributes . . . . . . . . . . . . 18
5.3.1. notify-recipient-uri (uri) . . . . . . . . . . . 20
5.3.2. notify-pull-method (type2 keyword) . . . . . . . 21
5.3.3. notify-events (1setOf type2 keyword) . . . . . . 22
5.3.4. notify-attributes (1setOf type2 keyword) . . . . 29
5.3.5. notify-user-data (octetString(63)) . . . . . . . 30
5.3.6. notify-charset (charset) . . . . . . . . . . . . 31
5.3.7. notify-natural-language (naturalLanguage). . . . 31
5.3.8. notify-lease-duration (integer(0:67108863)). . . 32
5.3.9. notify-time-interval (integer(0:MAX)). . . . . . 33
5.4. Subscription Description Attributes. . . . . . . . . . . 34
5.4.1. notify-subscription-id (integer (1:MAX)). . . . 35
5.4.2. notify-sequence-number (integer (0:MAX)) . . . . 35
5.4.3. notify-lease-expiration-time (integer(0:MAX)). . 36
5.4.4. notify-printer-up-time (integer(1:MAX)). . . . . 37
5.4.5. notify-printer-uri (uri) . . . . . . . . . . . . 37
5.4.6. notify-job-id (integer(1:MAX)) . . . . . . . . . 37
5.4.7. notify-subscriber-user-name (name(MAX)). . . . . 38
6. Printer Description Attributes Related to Notification . . . . 38
6.1. printer-state-change-time (integer(1:MAX)) . . . . . . . 39
6.2. printer-state-change-date-time (dateTime). . . . . . . . 39
7. New Values for Existing Printer Description Attributes . . . . 39
7.1. operations-supported (1setOf type2 enum) . . . . . . . . 40
8. Attributes Only in Event Notifications . . . . . . . . . . . . 40
8.1. notify-subscribed-event (type2 keyword). . . . . . . . . 40
8.2. notify-text (text(MAX)). . . . . . . . . . . . . . . . . 41
9. Event Notification Content . . . . . . . . . . . . . . . . . . 41
9.1. Content of Machine Consumable Event Notifications. . . . 44
9.1.1. Event Notification Content Common to All Events. 44
9.1.2. Additional Event Notification Content for Job
Events . . . . . . . . . . . . . . . . . . . . . 45
9.1.3. Additional Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . 46
9.2. Content of Human Consumable Event Notification . . . . . 46
9.2.1. Event Notification Content Common to All Events. 47
9.2.2. Additional Event Notification Content for Job
Events . . . . . . . . . . . . . . . . . . . . . 49
9.2.3. Additional Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . 49
10. Delivery Methods . . . . . . . . . . . . . . . . . . . . . . . 50
11. Operations for Notification. . . . . . . . . . . . . . . . . . 52
11.1. Subscription Creation Operations . . . . . . . . . . . . 52
11.1.1. Create-Job-Subscriptions Operation . . . . . . . 52
11.1.2. Create-Printer-Subscriptions operation . . . . . 55
11.1.3. Job Creation Operations - Extensions for
Notification . . . . . . . . . . . . . . . . . . 56
11.2 Other Operations. . . . . . . . . . . . . . . . . . . . . 58
11.2.1. Restart-Job Operation - Extensions for
Notification . . . . . . . . . . . . . . . . . . 58
11.2.2. Validate-Job Operation - Extensions for
Notification . . . . . . . . . . . . . . . . . . 59
11.2.3. Get-Printer-Attributes - Extensions for
Notification . . . . . . . . . . . . . . . . . . 59
11.2.4. Get-Subscription-Attributes operation. . . . . . 60
11.2.5. Get-Subscriptions operation. . . . . . . . . . . 63
11.2.6. Renew-Subscription operation . . . . . . . . . . 66
11.2.7. Cancel-Subscription operation. . . . . . . . . . 68
12. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . 70
12.1. successful-ok-ignored-subscriptions (0x0003) . . . . . . 70
12.2. client-error-ignored-all-subscriptions (0x0414). . . . . 71
13. Status Codes in Subscription Attributes Groups . . . . . . . . 71
13.1. client-error-uri-scheme-not-supported (0x040C) . . . . . 71
13.2. client-error-attributes-or-values-not-supported (0x040B) 71
13.3. client-error-too-many-subscriptions (0x0415) . . . . . . 72
13.4. successful-ok-too-many-events (0x0005) . . . . . . . . . 72
13.5. successful-ok-ignored-or-substituted-attributes (0x0001) 72
14. Encodings of Additional Attribute Tags . . . . . . . . . . . . 72
15. Conformance Requirements . . . . . . . . . . . . . . . . . . . 72
15.1. Conformance requirements for clients . . . . . . . . . . 73
15.2. Conformance requirements for Printers. . . . . . . . . . 73
16. Model for Notification with Cascading Printers (Informative) . 74
17. Distributed Model for Notification (Informative) . . . . . . . 75
18. Extended Notification Recipient (Informative). . . . . . . . . 76
19. Object Model for Notification (Normative). . . . . . . . . . . 77
19.1. Object relationships . . . . . . . . . . . . . . . . . . 78
19.2. Printer Object and Per-Printer Subscription Objects. . . 79
19.3. Job Object and Per-Job Subscription Objects. . . . . . . 79
20. Per-Job versus Per-Printer Subscription Objects (Normative). . 79
21. Normative References . . . . . . . . . . . . . . . . . . . . . 80
22. Informative References . . . . . . . . . . . . . . . . . . . . 80
23. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 81
23.1. Attribute Registrations. . . . . . . . . . . . . . . . . 82
23.2. Additional Enum Attribute Value Registrations within
the IPP registry . . . . . . . . . . . . . . . . . . . . 83
23.3. Operation Registrations. . . . . . . . . . . . . . . . . 83
23.4. Status code Registrations. . . . . . . . . . . . . . . . 83
23.5. Attribute Group tag Registrations. . . . . . . . . . . . 84
23.6. Registration of Events . . . . . . . . . . . . . . . . . 84
23.7. Registration of Event Notification Delivery Methods. . . 85
23.7.1. Requirements for Registration of Event
Notification Delivery Methods. . . . . . . . . . 85
23.7.2. Registration Procedure . . . . . . . . . . . . . 86
23.7.3. Delivery Method Document Registrations . . . . . 87
23.7.4. Registration Template. . . . . . . . . . . . . . 88
24. Internationalization Considerations. . . . . . . . . . . . . . 89
25. Security Considerations. . . . . . . . . . . . . . . . . . . . 89
25.1. Client access rights . . . . . . . . . . . . . . . . . . 89
25.2. Printer security threats . . . . . . . . . . . . . . . . 91
25.3. Notification Recipient security threats. . . . . . . . . 91
26. Description of the base IPP documents (Informative). . . . . . 92
27. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 93
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 94
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 95Tables 📊
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 . . . . 74part 1 of 20 is done bestie 🌈✨ next up is the Introduction and Notification Overview 🦋
Figures
Figure 1 - Model for Notification. . . . . . . . . . . . . . . . . 9
Figure 2 - Model for Notification with Cascading Printers. . . . . 75
Figure 3 - Opaque Use of a Notification Server Transparent to the
Client. . . . . . . . . . . . . . . . . . . . . . . . . 76
Figure 4 - Use of an Extended Notification Recipient transparent
to the Printer. . . . . . . . . . . . . . . . . . . . . 77
Figure 5 - Object Model for Notification . . . . . . . . . . . . . 781. Introduction 🎀
okay so this IPP notification spec is an OPTIONAL extension to Internet Printing Protocol/1.1: Model and Semantics [RFC2911, RFC2910]. 🌸 Check Appendix 29 if you want the rundown on the base IPP docs. Together with the following documents, this one is meant to cover the most important notification requirements from [RFC3997]:
- Internet Printing Protocol (IPP): "Job Progress Attributes" [RFC3381]
- Internet Printing Protocol (IPP): "The 'ippget' Delivery Method for Event Notifications" [RFC3996]
Here's the part that's non-negotiable 💅: clients and Printers REQUIRE support for the 'ippget' Pull Delivery Method [RFC3996]. Conforming client and Printer implementations MAY also support additional Push or Pull Delivery Methods. ✨ Also, this document doesn't define any Delivery Methods itself. What it does define are the rules for conformance for Delivery Method Documents and how they get registered with IANA (see section 23.7.3).
Refer to the Table of Contents for the layout of this document. 🧚
1.1. Notification Overview
so this doc defines the operations a client can run to create Subscription Objects in a Printer, plus other stuff you can do with them. 🦋 A Subscription Object is the thing that represents a Subscription. It says: when one of the specified Events happens, the Printer delivers an asynchronous Event Notification to the specified Notification Recipient, using the specified Delivery Method (i.e., protocol).
When a client (called a Subscribing Client) runs an operation that creates a Subscription Object, that operation holds one or more Subscription Template Attributes Groups. Each group has info the Printer uses to set up a newly created Subscription Object, and the Printer makes one Subscription Object per group in the operation. This group is basically like the Job Template Attributes group from [RFC2911] 💜 Here's an example of what goes in a Subscription Template Attributes Group (see section 5 for the full details on Subscription Object attributes):
- The names of Subscribed Events that the Notification Recipient cares about.
- The address (URL) of one Notification Recipient for a Push Delivery Method, or the method for a Pull Delivery Method.
- The Delivery Method (i.e., the protocol) the Printer uses to deliver the Event Notification.
- Some opaque data that the Printer hands to the Notification Recipient inside the Event Notification. For example, the Notification Recipient could treat this opaque data as a forwarding address for the Event Notification.
- The charset to use in text fields within an Event Notification.
- The natural language to use in the text fields of the Event Notification.
- The requested lease time in seconds for the Subscription Object.
An operation that creates a Subscription Object is called a Subscription Creation Operation. These include the following (see section 11.1 for more detail) 🍓:
- Job Creation operation: When a client runs one of these (Print-Job, Print-URI, and Create-Job), it can include zero or more Subscription Template Attributes Groups in the request. The Printer makes one Subscription Object per group in the request and links each one to the newly created Job. This document extends these operations' definitions from [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 per group and associates each one 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 per group and associates each one with the Printer that is the target of this operation.
For each of the operations above:
- the Printer associates a Subscription Object with either the Printer or a specific Job. A Subscription Object tied to a Job Object is called a Per-Job Subscription Object. A Subscription Object tied to a Printer Object is called a Per-Printer Subscription Object.
- the response has one Subscription Attributes Group for each Subscription Template Attributes Group in the request, in the same order. When the Printer successfully creates a Subscription Object, its matching Subscription Attributes Group includes the
"notify-subscription-id"attribute. This attribute uniquely identifies the Subscription Object and is basically thejob-idequivalent for a Job object 🔥. Some operations below use"notify-subscription-id"to point at the target Subscription Object.
This document also defines these extra operations (see section 11.2 for more detail) 👑:
- Restart-Job operation: When a client runs the Restart-Job operation [RFC2911], the Printer reuses the same Job and its Subscription Objects.
- Validate-Job operation: When a client runs this, it can include zero or more Subscription Template Attributes Groups in the request. The Printer figures out whether it could create one Subscription Object for each group in the request. This document extends this operation's definition from [RFC2911] by adding Subscription Template Attributes Groups in the request and Subscription Attributes Groups in the response.
- Get-Subscription-Attributes operation: This lets a client get the specified attributes of a target Subscription Object.
- Get-Subscriptions operation: This lets a client get the specified attributes of all Subscription Objects tied to the Printer or to a specified Job.
- Renew-Subscription operation: This renews the lease on the target Per-Printer Subscription Object before it expires. A newly created Per-Printer Subscription Object gets an initial lease. It's the client's job to use this operation often enough to keep a Per-Printer Subscription Object alive. The Printer deletes a Per-Printer Subscription Object when its lease expires. A Per-Job Subscription Object lasts exactly as long as its associated Job Object, so it doesn't have a lease. 🥺
- Cancel-Subscription operation: This operation does one of two things: (1) it cancels the lease on the specified Per-Printer Subscription Object, which deletes that Per-Printer Subscription Object, or (2) it deletes the Per-Job Subscription Object.
When an Event happens, the Printer finds all the Subscription Objects listening for it (see section 9 for how those Subscription Objects get found). For each one, the Printer does the following:
a) generates an Event Notification with the information specified in section 9, AND
b) does one of these:
i) If the Delivery Method is a Push Delivery Method (indicated by the presence of the Subscription Object's "notify-recipient-uri" attribute), it delivers the Event Notification using the Delivery Method and target address identified in that "notify-recipient-uri" attribute, OR
ii) If the Delivery Method is a Pull Delivery Method (indicated by the presence of the Subscription Object's "notify-pull-method" attribute), it saves the Event Notification for a period of time called the Event Life, which is defined by the Delivery Method. In other words, the Notification Recipient is expected to fetch the Event Notifications. 🫶
2. Models for Notification ✨
2.1. Model for Simple Notification (Normative) 💖
So as part of a Subscription Creation Operation, an IPP Printer (i.e., one located in an output device or a server) creates one or more Subscription Objects. In that operation, the client names the Notification Recipient the Printer should deliver Event Notifications to. The Notification Recipient can be the Subscribing Client or a third party.
Figure 1 shows the Notification model for a simple Client-Printer relationship:
embedded printer:
output device or server
PDA, desktop, or server +---------------+
+--------+ | ########### |
| client |-----Subscription ---------># Printer # |
+--------+ Creation Operation | # Object # |
+------------+ | #####|##### |
|Notification| +-------|-------+
|Recipient |<----IPP Event Notifications----+
+------------+ (Job and/or Printer Events)
Figure 1 - Model for Notification2.2. Additional Models for Notification (Informative) 🌈
Additional models have been proposed (see Appendices 16, 17, and 18).
3. Terminology 🦋
This section defines the terminology used throughout this document. Any other terminology is defined in [RFC2911].
3.1. Conformance Terminology 💜
Capitalized terms, like MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY, NEED NOT, and OPTIONAL, have special meaning for conformance. That meaning is defined in RFC 2119 [RFC2119] and [RFC2911] section 12.1. If an implementation supports the extension defined in this document, these terms apply. If it doesn't, they don't. These terms only define conformance to this document. They don't affect conformance to other documents, unless that's explicitly stated 🙈
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 mean that an IPP Printer MUST NOT allow the attribute's value to be modified. 🔒
3.2. Other Terminology ✨
okay so this doc borrows its vocab from [RFC2911], which means words like "client", "Printer", "attribute", "attribute value", "keyword", "operation", "request", "response", "administrator", "operator", and "support" mean the same thing here 💅 on top of that, it defines its own terms for this doc 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-occurredandjam-clearedare 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-URIandCreate-Job. TheRestart-Joboperation [RFC2911] is not considered a Job Creation operation, since the Printer re-uses the existing Job object. TheValidate-Joboperation is not considered a Job Creation operation because no Job object is created. Therefore, when a statement also applies to either theRestart-Joband/or theValidate-Joboperation, they are mentioned explicitly. 🧚 - Job Event — an Event caused by some change in a particular job on the Printer, e.g.,
'job-completed'. - Machine Consumable Event Notification — bytes for program consumption. The bytes are formatted according to the Delivery Method document. 🤖
- Notification — when not in the phrases 'Event Notification' and 'Notification Recipient' — the concepts of this specification, i.e., Events, Subscription Objects, and Event Notifications.
- Notification Recipient — the entity to which the Printer delivers an Event Notification. For Push Delivery Methods, the IPP Printer sends the Notifications to a Notification Recipient. For Pull Delivery Methods, the Notification Recipient is acting in the role of an IPP client and requests Event Notifications and so the terms "client" and "Notification Recipient" are used interchangeably with such Delivery Methods. For example, see [RFC3996]. 💌
- Per-Job Subscription Object — A Subscription Object that is associated with a single Job. The Create-Job-Subscriptions operation and Job Creation operations create such an object.
- Per-Printer Subscription Object — A Subscription Object that is associated with the Printer as a whole. The Create-Printer-Subscriptions operation creates such an object.
- Printer Event — an Event caused by some change in the Printer that is not specific to a job, e.g.,
'printer-state-changed'. - Pull Delivery Method — The Printer saves Event Notifications for some event life time and expects the Notification Recipient to request Event Notifications. The Printer delivers the Event Notifications in a response to such a request.
- Push Delivery Method — The Printer delivers the Event Notification shortly after an Event occurs. 🚀
- Subscribed Event — an Event that the Subscribing Client expresses interest in by making it a value of the
"notify-events"attribute on a Subscription Object. - Subscribed Job Event — a Subscribed Event that is a Job Event.
- Subscribed Printer Event — a Subscribed Event that is a Printer Event.
- Subscribing Client — The client that creates the Subscription Object.
- Subscription Attributes Group — The attributes group in a response that contains Subscription Object attributes.
- Subscription Creation Operation — An operation that creates a Subscription Object: Job Creation operations, Create-Job-Subscriptions operation, Create-Printer-Subscriptions operation. In the context of a Job Creation operation, a Subscription Creation Operation is the part of the Job Creation operation that creates one or more Subscription objects. The Restart-Job operation [RFC2911] is not considered a Subscription Creation Operation, since the Printer re-uses the Job's existing Subscription Objects, rather than creating any new Subscription Objects.
- Subscription Creation Request — The request portion of a Subscription Creation Operation.
- Subscription Description Attributes — Subscription Object attributes that a Printer supplies during a Subscription Creation Operation.
- Subscription Object — An object containing a set of attributes that indicate: the Notification Recipient (for Push Delivery Method only), the Delivery Method, the Subscribed Events that cause the Printer to deliver an Event Notification, and the information to include in an Event Notification. 📦
- Subscription Template Attributes — Subscription Object attributes that a client can supply in a Subscription Creation Operation and associated Printer Object attributes that specify supported and default values for the Subscription Object attributes.
- Subscription Template Attributes Group — The attributes group in a request that contains Subscription Object attributes that are Subscription Template Attributes.
4. Object Relationships 🧩
this section is all about how the Printer, Job, and Subscription Objects relate to each other. It does not define the implementation, so no peeking at how it's built 🙅♀️ for a picture of these relationships, check out Appendix 19.
4.1. Printer and Per-Printer Subscription Objects
- A Printer object can be associated with zero or more Per-Printer Subscription Objects.
- Each Per-Printer Subscription Object is associated with exactly one Printer object.
4.2. Printer, Job and Per-Job Subscription Objects
- A Printer object is associated with zero or more Job objects.
- Each Job object is associated with exactly one Printer object.
- A Job object is associated with zero or more Per-Job Subscription Objects.
- Each Per-Job Subscription Object is associated with exactly one Job object.
5. Subscription Object 💖
a Subscribing Client makes a Subscription Object with a Subscription Creation Operation so it can show its interest in certain Events (see section 11 for the lowdown on these operations). When an Event happens, the Subscription Object tells the Printer where to deliver Event Notifications for Push Delivery Methods only, how to deliver them, and what to include in them. For the contents of an Event Notification, see section 9 ✨
using the IPP Job Template attributes as a model (see [RFC2911] section 4.2), the attributes of a Subscription Object get split into two categories: Subscription Template Attributes and Subscription Description Attributes. It's giving organized 🗂️
Subscription Template attributes are, in turn, like the Job Template attributes, divided into:
- Subscription Object attributes that a client can supply in a Subscription Creation Request and
- their associated Printer Object attributes that specify supported and default values for the Subscription Object attributes
the rest of this section lays out the general rules for Subscription Template Attributes and describes each attribute in a Subscription Object. Let's get into it 👑
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. This is literally the core of the whole thing 🫶
Subscription Objects attributes that are Subscription Template Attributes conform to the following rules:
- Each attribute's name starts with the prefix string
"notify-"and this document calls such attributes"notify-xxx". - 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. 🌸 - 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". 🔥 - 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. 🙅♀️ - 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". - Some
"notify-xxx"attributes have a corresponding"notify-xxx-default"attribute that specifies the value for"notify-xxx"if the client does not supply it. Column 2 of Table 1 specifies the name of each"notify-xxx-default"attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used.
if a client wants to show an end user a list of supported values to pick from, 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 ✨
okay bestie, this section is the rulebook 📜 for how a Printer handles Subscription Template Attributes when a Subscription Creation Request comes in. it's giving the same energy as the Operation attribute rules in [RFC2911] 💅. So the Printer might or might not support an attribute, and the client might or might not send it. Some combos are totally fine, and others bring back warnings or errors, maybe with a list of unsupported attributes 🙈
Here's what a Printer MUST do 🫶 when it processes Subscription Template Attributes in a Subscription Creation Request:
- If a client sends a
"notify-xxx"attribute from column 1 of Table 1, and the Printer supports both that attribute and its value ✨, the Printer MUST populate the attribute on the Subscription Object it creates. - If a client sends a
"notify-xxx"attribute from column 1 of Table 1, and the Printer doesn't support the attribute or its value, the Printer MUST NOT populate that attribute on the Subscription Object it creates. 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.
- a) If the value of the
Note: the rules of this step are the same as the Unsupported Attributes rules in [RFC2911] section 3.1.7, except the unsupported attributes go in the Subscription Attributes Group instead of the Unsupported Attributes Group, because Subscription Creation Operations can create more than one Subscription Object).
- 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. - If a client doesn't 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. In the response, the Printer MUST return:- a) the status code
'client-error-bad-request'AND - b) no Subscription Attribute Groups.
- a) the status code
- If a client doesn't 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. This is 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 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.
- a) specifies a
- A Printer MUST create a Subscription Object for each Subscription Template Attributes group in a request, unless the Printer:
- a) encounters some attributes in a Subscription Template Attributes Group that require the Printer not to create the Subscription Object, OR
- b) would create a Per-Job Subscription Object when it doesn't have space for another Per-Job Subscription Object, OR
- c) would create a Per-Printer Subscription Object when it doesn't have space for another Per-Printer Subscription Object.
- 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.
- The Printer MUST populate each Subscription Attributes Group of the response so 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 when creating a Per-Job Subscription Object, it MUST appear in this group with the out-of-band value'unsupported', to show that the Printer doesn't support it in this context. - c) all of the unsupported Subscription Template Attributes from step #2. Note that they are not returned in the Unsupported Attributes Group, so the unsupported attributes for each Subscription Object stay separate.
- 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 listed below (see section 13 for more details). The Printer returns the first value in the list below that describes the status.'client-error-uri-scheme-not-supported': the Subscription Object was not created because the scheme of the"notify-recipient-uri"attribute is not supported. See section 13.1 for more details about this status code. See step #3 in this section for the case that causes this error, and the resulting step #6a) that causes the Printer not to create the Subscription Object.'client-error-attributes-or-values-not-supported': the Subscription Object was not created because the method in 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 cause 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.
- a) the
- 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). In that case, 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 Attributes Groups.
5.3. Subscription Template Attributes 🎀
Okay bestie, this section is where we list every Subscription Template Attribute for the Subscription and Printer objects 💅✨
Table 1 has two columns:
- Attribute in Subscription Object: the name and attribute syntax of each Subscription Object Attribute that counts as a Subscription Template Attribute 🦋
- Default and Supported Printer Attributes: the default attribute and the supported Printer attributes that go with the attribute in column 1 💜
The notify-recipient-uri attribute is for Push Delivery Methods, and the notify-pull-method attribute is for Pull Delivery Methods 🌸
For Push Delivery Methods, a Printer MUST support all attributes in Table 1 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 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 🔥
For Pull Delivery Methods, a client MUST supply notify-recipient-uri in a Subscription Creation Request, and it MAY omit any of the other attributes in column 1 of Table 1. For Push Delivery Methods, a client MUST supply notify-pull-method in a Subscription Creation Request, and it MAY omit any of the other attributes in column 1 of Table 1. A client MUST NOT supply both notify-recipient-uri and notify-pull-method in the same Subscription Creation Request 🙈
Note: The Default and Supported Printer attributes in column 2 of Table 1 don't get their own sections in this spec. Instead, the section for the matching Subscription Object attribute in column 1 explains what these Printer attributes do 🧚 This follows the same pattern as the Job Template attributes in section 4.2 of [RFC2911], where the xxx-default and xxx-supported Printer attributes are defined in the same section as the xxx Job attribute 💖
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 kind of URI 🌈 It has a scheme and an address. The address points to the Notification Recipient, and the scheme tells us which Push Delivery Method gets used for each Event Notification tied to this Subscription Object 💅
If a Printer supports any Push Delivery Methods, a Printer MUST support this attribute and return the value exactly as the client supplied it (no case conversion or other canonicalization) in any operation response that includes this attribute 🫶
For a Push Delivery Method, a client MUST supply this attribute in a Subscription Creation Operation. That means there's no need for a default Printer attribute 👑
The URI scheme of this attribute's value 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 ":" ends the scheme, so it isn't part of the scheme. That's why values of the notify-schemes-supported Printer attribute don't include the ":" character 🤓
If the client supplies an unsupported scheme in this attribute's value, then the Printer MUST NOT create the Subscription Object and MUST return the notify-status-code attribute with the value client-error-uri-scheme-not-supported in the Subscription Attributes Group of the response 💀
5.3.1.1. notify-schemes-supported (1setOf uriScheme) 🌸
This attribute contains the URI schemes supported by the notify-recipient-uri Subscription Template attribute. For how xxx-supported Subscription Template Printer attributes behave, check sections 5.1 and 5.2 🧚
5.3.2. notify-pull-method (type2 keyword) 🍓
This attribute's value is a type2 keyword that says which Pull Delivery Method to use 💜
Since a Printer MUST support the ippget Pull Delivery Method [RFC3996] (see section 15), a Printer MUST support this attribute and return the value exactly as the client supplied it in any operation response that includes this attribute ✨
For a Pull Delivery Method, a client MUST supply this attribute in a Subscription Creation Operation. Again, 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 this attribute's value, then the Printer MUST NOT create the Subscription Object and MUST return the notify-status-code attribute with the value client-error-attributes-or-values-not-supported in the Subscription Attributes Group of the response 😭
5.3.2.1. notify-pull-method-supported (1setOf type2 keyword) 💅
For how xxx-supported Subscription Template Printer attributes behave, see sections 5.1 and 5.2 🎀
5.3.3. notify-events (1setOf type2 keyword) 🔥
This attribute holds a set of Subscribed Events. When an Event happens and it "matches" one of this attribute's values, the Printer delivers an Event Notification using the info in the Subscription Object 🌈 The details of "matching" are in 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 doesn't supply it in a Subscription Creation Operation, the Printer MUST fill 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 for 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 a client supplies in a Subscription Creation Operation goes over this attribute's limit, the Printer MUST treat the extra values as unsupported values and MUST use the value 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) 🍓
For how xxx-default Subscription Template Printer attributes behave, see sections 5.1 and 5.2 🧚
5.3.3.2. notify-events-supported (1setOf type2 keyword) 🌸
For how xxx-supported Subscription Template Printer attributes behave, see sections 5.1 and 5.2 💜
5.3.3.3. notify-max-events-supported (integer(2:MAX)) 👑
This attribute specifies the maximum number of events the Printer supports for the notify-events Subscription Template attribute. For how xxx-supported Subscription Template Printer attributes behave, see sections 5.1 and 5.2 ✨
5.3.3.4. Standard Values for Subscribed Events 🦋
Each value of this attribute is a keyword that names a Subscribed Event representing certain changes. Some keywords cover a subset of changes from another keyword. For example, job-completed is an Event value that's a sub-value of job-state-change 🌈 For the case where this attribute has both a value and a sub-value, see section 5.3.3.5 👀
The values in this section fall 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 only value ofnotify-events-supported, this value means the Printer does not support delivering Event Notifications. As the only value ofnotify-events-default, this value means a client MUST specify thenotify-eventsattribute for a Subscription Creation Operation to succeed. If the Printer receives this value as the only value in a Subscription Creation Operation, it does not create a Subscription Object. If the Printer receives this value along with other values in a Subscription Creation Operation, the Printer MUST treat this value as an unsupported value 💀🔥
5.3.3.4.2. Subscribed Printer Events ✨
okay so these are the standard keyword values for Subscribed Printer Events 🖨️💖
'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.- This Subscribed Event value has these 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'.
- This Subscribed Event value has these sub-values:
'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 these 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 "finishings-ready" Printer attribute separately to find out what changed.
- This Event value has these sub-values:
'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 🎟️
okay, 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 these 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 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'.
- This Event value has these sub-values:
'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 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:
- 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.
- 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.
- 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 ✨
Okay bestie, this section is all about the tricky "one Event, lots of notifications" situation 👀. There are two rules for when a single Event turns into multiple Event Notifications headed to the same Notification Recipient. They help decide whether a Printer sends several Event Notifications or squishes them into one 💅.
Rule one is about separate Subscription Objects. 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. So the Printer MUST NOT try to consolidate seemingly identical Event Notifications that come from separate Subscription objects 🙅♀️. Also, the Printer MUST NOT reject Subscription Creation Operations that would create this scenario 🫶.
Let's look at an example 🎀. When a Job completes, there are two Per-Printer Subscription Objects, A and B, both 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'. So the Printer delivers two Event Notifications to Notification Recipient R 📬. One has 'job-state-changed' for the "notify-subscribed-event" attribute, and the other has 'job-completed' for the "notify-subscribed-event" attribute.
Rule two is about one Subscription Object with overlapping values. If an Event matches two Subscribed Events in a single Subscription object (for example, 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. Sections 5.3.3.5.1 and 5.3.3.5.2 are purposefully flexible about how many Event Notifications get sent when Event E matches two or more values in a Subscription Object 🦋.
Here's the example for that one 🌸. When a Job completes, 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 the implementation. If it delivers two, one has 'job-state-changed' for the "notify-subscribed-event" attribute, and the other has 'job-completed' for the "notify-subscribed-event" attribute. If it delivers one, it has either 'job-state-changed' or 'job-completed' for the "notify-subscribed-event" attribute, depending on the implementation. The algorithm for choosing that value is implementation dependent 🧚.
5.3.4. notify-attributes (1setOf type2 keyword)
This attribute holds 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 named here 💜.
A Printer MAY support this attribute 🌈.
A client MAY supply this attribute in a Subscription Creation Operation. If the client doesn't supply it in the Subscription Creation Operation, or the Printer doesn't support it, 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" attribute 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, because it would be redundant 🙅♀️. If a client supplies an attribute from Section 9.1, the Printer MUST treat it as an unsupported attribute value of the "notify-attributes" attribute.
Here's how the rules work for 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.
- a Printer Event, the Printer MUST use the attribute N in the active Job.
If a Printer supports this attribute, a Subscription Object contains this attribute, and the Delivery Method generates a Machine Consumable Event Notification, the Printer MUST include the following 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 💀. That one's a hard no, bestie!
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 holds 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 doesn't supply it 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 ✨.
There is no "notify-user-data-supported" Printer attribute. Instead, any octetString whose length doesn't 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 used in the Event Notification content sent to the Notification Recipient, whether that 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 doesn't supply it in the 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. That one 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 used for any human consumable text in the Event Notification content sent to the Notification Recipient, whether that 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 doesn't supply it in the 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. That one 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 🦋.
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)) 🎀
okay so this one is the lease timer ⏰ It says how long (in seconds) the lease on a Per-Printer Subscription Object lasts, counted from the moment the Subscription Object got created or the lease got renewed. If the value is 0, the lease is infinite and never expires 🦋 For all the deets, check out section 5.4.3 on "notify-lease-expiration-time (integer(0:MAX))" 💜
This attribute is not on a Per-Job Subscription Object, because that one lasts exactly as long as its Job object 🫶 See the 'job-completed' event in section 5.3.3.4.3 for how the Job object sticks around after it finishes.
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 it anyway, 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 doesn't supply it, the Printer MUST fill it in with its notify-lease-duration-default value of 0:67108863 🌸 If the client asks for a value the Printer doesn't support, the Printer MUST swap in a supported value, and that value SHOULD be as close as possible to what the client asked for 💖 Also, a Printer won't hand out 0 (infinite) unless the client explicitly asks for it. Main character restraint 👑
Once the Printer has filled this attribute in with a supported value, that value is the "granted duration" of the lease in seconds. The Printer then updates the Subscription Object's "notify-lease-expiration-time" attribute the way section 5.4.3 describes 🧚
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 🔥
A Printer MAY require authentication before it returns 0 (the lease never expires) as one of the values of notify-lease-duration-supported, and before it lets a client set 0 as the value of the notify-lease-duration attribute 🔐
Note: The maximum value, 67,108,863, is 2 raised to the 26 power minus 1, which is about 2 years in seconds 🌈 It's way less than MAX on purpose, so there's basically zero chance of overflow when the Printer adds it to the Printer's printer-up-time attribute value (see [RFC2911] section 4.4.29) to make 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))
This is the same deal as the other "xxx-default" Subscription Template Printer attributes, so see sections 5.1 and 5.2 for how those behave 🍓
5.3.8.2. notify-lease-duration-supported (1setOf (integer(0: 67108863) | rangeOfInteger(0:67108863)))
Same vibe again: see sections 5.1 and 5.2 for how "xxx-supported" Subscription Template Printer attributes work 🦋
5.3.9. notify-time-interval (integer(0:MAX)) ⭐
So the 'job-progress' Event fires every time a Printer finishes a sheet 📄 But not every Notification Recipient wants a ping that often, you know? This attribute lets a Subscribing Client say how often it wants 'job-progress' Event Notifications 💜 The value MAY be any nonnegative integer (0,MAX), and it's 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 doesn't supply it, 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 either 🙅♀️
If the 'job-progress' Event happens and a Subscription Object lists 'job-progress' as a value of its 'notify-events' attribute, there are two cases to think about 👀
- This attribute isn't on the Subscription Object, or it's
0. The Printer MUST generate and deliver an Event Notification, same as with every other Event 💖 - This attribute is present with a nonzero value of N:
- a) If the Printer hasn't sent an Event Notification for the 'job-progress' Event for that Subscription Object within the past N seconds, the Printer MUST deliver an Event Notification for the Event that just happened. Also, when the Printer finishes the first page of a Job, this rule means 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 that Subscription Object. The Printer MUST NOT increase the value of the "notify-sequence-number" Subscription Object attribute either. So the sequence of "notify-sequence-number" values counts the Event Notifications actually sent, not the Events that didn't send one 🔢✨
It is RECOMMENDED that a Subscribing Client use this attribute when it subscribes to the 'job-progress' Event, and that the value be big enough to keep the Printer from delivering Event Notifications requests too often 🫶
This attribute MUST NOT effect any Events other than 'job-progress' 🚫
5.4. Subscription Description Attributes 🌈
Subscription Description Attributes are the attributes a Printer adds to a Subscription Object when it gets created 🧁
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. They don't have any matching default or supported attributes 🙈
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 gives each Subscription Object instance a number that's unique within the Printer 🆔 The Printer makes this value when it creates the Subscription Object 🦋
A Printer MUST support this attribute. 💅
The Printer MAY assign this value sequentially as it creates Subscription Objects. But if there's no security on Subscription objects, sequential numbering opens the system up to a passive traffic monitoring threat 👀🚨
The Printer SHOULD avoid re-using recent values of this attribute, both during continuous operation and across power cycles. That way a Subscribing Client is unlikely to end up with a stale reference that hits a brand-new Subscription Object 🫣
The 0 value isn't allowed, so it stays compatible 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))
This attribute counts how many times the Printer has generated and tried to deliver an Event Notification for this Subscription object 🔢 When an Event Notification includes it, the Notification Recipient can tell whether it missed some (numbers skipped) or got duplicates (same number twice) 🕵️♀️
A Printer MUST support this attribute. 💜
When the Printer creates a Subscription Object, it MUST set this attribute to 0. That means no Event Notifications have gone out for this Subscription Object yet 🌸
Every time the Printer delivers a newly generated Event Notification, it MUST increase 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 the increase. So the first Event Notification after the Subscription object is created MUST have 1, the second MUST have 2, and so on 🔥 If a Delivery Method is defined so the Notification Recipient sends back 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 doesn't send one back 🔁
If a Subscription Object lasts long enough to hit 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 says when the lease on the Per-Printer Subscription Object will expire, in the future. In other words, it's the "printer-up-time" value at which the lease runs out ⏳ 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. That Subscription Object lasts exactly as long as its Job object. Check the 'job-completed' event discussion in section 5.3.3.4.3 for why the Job object sticks around after completion, so a Notification Recipient can query it after getting the 'job-completed' Event Notification 🎀
When the Printer creates a Per-Printer Subscription Object, it fills this attribute with the sum of the Printer's "printer-up-time" attribute value and the Subscription Object's "notify-lease-duration" attribute value, with one exception. If the Subscription Object's "notify-lease-duration" is 0 (no expiration time), this attribute MUST be set to 0 too (no expiration time) 🧮
When the Printer powers up, it MUST refresh this attribute in each persistent Subscription Object using the algorithm in the paragraph above 🔋
When "printer-up-time" equals the value of this attribute, the Printer MUST delete the Subscription Object 🗑️ A client can extend the lease on a Per-Printer Subscription Object with the Renew-Subscription operation (see section 11.2.6) 🦋
Note: To figure out how many seconds are left on 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)) ✨
Okay so this one is an alias, bestie 🦋 It points at the Printer's printer-up-time attribute (see [RFC2911] section 4.4.29). When you query it with the Get-Subscriptions or Get-Subscription-Attributes operations (see sections 11.2.4 and 11.2.5), you get the Printer's current printer-up-time value, NOT the time the Subscription Object was created. Plot twist 😭
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 lives in a Per-Printer Subscription Object so that a client using the Get-Subscription-Attributes or Get-Subscription operations can turn the Per-Printer Subscription's notify-lease-expiration-time into wall clock time with just one request. 🧚 If the value of notify-lease-expiration-time is not 0 (meaning no expiration time), then the difference between notify-lease-expiration-time and notify-printer-up-time is the number of seconds left on the lease from the current time. Big brain math, iconic ✨
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, figure out what security scheme was used. 🔐 Main character energy from the URI, honestly 👑
5.4.6. notify-job-id (integer(1:MAX))
This attribute tells you whether the containing Subscription Object is a Per-Job or a Per-Printer Subscription Object, and for Per-Job Subscription Objects, it tells you which Job it's attached to. 💜
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 really useful to a Notification Recipient that gets 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, but it only gives access to the associated Job through this attribute. 🙈 See the discussion of the 'job-completed' event in section 5.3.3.4.3 about keeping the Job object around after completion, so a Notification Recipient can query the Job object after receiving the 'job-completed' Event Notification. Retention is the whole vibe 🫶
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 populate this attribute with the most authenticated printable name it can get from the authentication service over which the Subscription Creation Operation was received. The Printer uses the same mechanism to work out this attribute's value as it does for a Job's job-originating-user-name (see [RFC2911] section 4.3.6). Consistency is everything ✨
Note: to help with authentication, a Subscription Object may have additional private attributes about the user, e.g., a credential of a principal. Those private attributes are implementation-dependent and not defined in this document. 🔒 Shh, that's between the implementation and the user 🤫
6. Printer Description Attributes Related to Notification
This section defines the Printer Description attributes that are related to Notification. 🦋 Table 3 lists them, shows which Printer support is required for conformance, and says whether or not each attribute is READ-ONLY (see section 3.1):
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 Yes6.1. printer-state-change-time (integer(1:MAX))
This OPTIONAL attribute records the most recent time that the 'printer-state-changed' Printer Event occurred, whether or not any Subscription objects were listening for it. ⏰ It helps a client or operator figure out how long the Printer has been in its current state.
A Printer MAY support this attribute, and if it does, 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 that the 'printer-state-changed' Printer Event occurred, whether or not there were any Subscription Objects listening for it. 📅 It helps a client or operator work out how long the Printer has been in its current state.
A Printer MAY support this attribute, and if it does, 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 the attributes that get additional values added. 🍓
7.1. operations-supported (1setOf type2 enum)
The following operation-id values are added 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-Subscription8. Attributes Only in Event Notifications
This section contains the attributes that only exist in Event Notifications and don't exist in any objects. 📨 They're the exclusive club 💅
8.1. notify-subscribed-event (type2 keyword)
This attribute indicates the Subscribed Event that made the Printer deliver this Event Notification. It only exists 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 more examples. Matching is a whole thing, periodt 💀
The Delivery Method Document specifies whether the Printer includes the value of this attribute in an Event Notification. 📬
8.2. notify-text (text(MAX))
This attribute contains a Human Consumable text message (see section 9.2). It describes the Event and is encoded as plain text, i.e., 'text/plain', with the charset specified by the 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, so the charset has to be specified by an alternate mechanism, namely the notify-charset attribute. 🙃 Read the room, the charset is elsewhere 😭
The Delivery Method Document specifies whether the Printer includes this attribute in an Event Notification. 🎀
9. Event Notification Content ✨
This section is where we get into what the Printer actually sends when something happens 💌. It's the Event Notification content, aka the good stuff that gets delivered when an Event occurs.
When an Event happens, the Printer MUST look through every Subscription object whose "notify-events" attribute "matches" that Event. Check section 5.3.3.5 for the full scoop on "matching" 🔍. For each Subscription Object that matches, the Printer MUST create an Event Notification with the content and format the Delivery Method Document specifies. The content has the values of whatever attributes the Delivery Method Document calls for, and the Printer grabs those values right after the Event occurs 🫶. For example, say "printer-state" goes from 'idle' to 'processing'. That makes the Event 'printer-state-changed' happen, and the Printer packs a bunch of attributes into the Event Notification, like "printer-up-time" and "printer-state". Those values are whatever they are right after the Event, so "printer-state" is 'processing' ✨.
Event Notification Ordering:
Okay, ordering is a whole thing 💅. When a Printer delivers Event Notifications, the ones from any single Subscription Object MUST be in time stamp order, meaning the "printer-up-time" value goes up with each one (check Table 5) 🦋. Notifications from different Subscription Objects MAY be mixed together, as long as each of those other Subscription Objects is also in time stamp order. The Printer MUST keep these ordering rules no matter whether it sends multiple pending Events as separate Event Notifications or bundles them into one single Compound Event Notification 🎀.
If a Subscribing Client wants certain Event Notifications delivered in time stamp order, it should use one single Subscription Object 🍓. Even then, the transport can shuffle things, so the order a Notification Recipient actually gets separate Event Notifications might not match the order the Printer sent them. Email is the classic example 📧.
Example: Picture two Per-Printer Subscription Objects, SO1 and SO2. SO1 asks for 'job-state-changed' events and SO2 asks for 'printer-state-changed' events. The number in parens is the time stamp 🕒. These are the only Event Notification sequences that follow the ordering rules for the Printer:
(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) aren't interleaved, and they aren't a good fit for some Delivery Methods 🙈.
If two different Events happen at the same time, or almost at the same time (say "printer-up-time" is identical for both), the Printer MUST create a separate Event Notification for each Event, even when both belong to the same Subscription Object 💜. The Printer MAY bundle those separate Event Notifications into one Compound Event Notification, but only if the Delivery Method supports Compound Event Notifications 🧚. Here's a scenario: two nearly-simultaneous Events are two back-to-back 'printer-state-changed' Events, one going from 'idle' to 'processing' and the next from 'processing' to 'stopped'. They share a name, but they're different instances of the Event 👑. So the Printer MUST create a separate Event Notification for each one, and SHOULD accurately report the "printer-state" as 'processing' for the first Event and 'stopped' for the second ✨.
If a Subscription Object has more than one Subscribed Event, and a bunch of Events happen in quick succession, each matching a different Subscribed Event in that Subscription Object, the Printer MUST NOT squish several of those Events into one Event Notification 🙅♀️. It MAY combine distinct Event Notifications into a single Compound Event Notification, as long as the Delivery Method supports Compound Event Notifications 💅.
Once the Printer has made the Event Notification, it delivers it through either a:
Push Delivery Method: The Printer sends the Event Notification shortly after the Event occurs. For some Push Delivery Methods, the Notification Recipient MUST send back a response; for others it MUST NOT send back a response.
Pull Delivery Method: The Printer holds onto Event Notifications for some Event Life and waits for the Notification Recipient to ask for them. The Printer returns the Event Notifications in a response to that request.
🚨 Heads up, bestie: if an error meets all of the following conditions, the Printer MUST cancel the Subscription Object 💀. a) the error occurs while delivering an Event Notification generated from Subscription Object S AND b) the error would keep happening every time the Printer delivers an Event Notification generated from Subscription Object S in the future.
For example, if the address in the "notify-recipient-uri" of Subscription Object A points to a target that doesn't exist, and the Printer figures that out, it MUST delete Subscription Object A 🗑️. Bye bye, Subscription Object A 😭.
The next two sections cover the values that a Printer delivers in Machine Consumable Event Notifications and Human Consumable Event Notifications, respectively 🌸.
The tables in the subsections of this section have the following columns:
- a) Source Value: the attribute that supplies the value for the Event Notification. Asterisks in this field point 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: the Printer MUST deliver the value.
- SHOULD: either the Printer MUST deliver the value, or the value is incompatible with the Delivery Method.
- MAY: 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 the source value comes from. If the object is "Event Notification", the Printer makes up 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 it specifies the contents of the Machine Consumable Event Notification 🤖💖.
This document doesn't 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 any additional attributes (if there are any) that a Printer implementation delivers in a Machine Consumable Event Notification 🍓.
Notification Recipients MUST be able to accept Event Notifications that include attributes they don't recognize 🫶. What a Notification Recipient does with an unrecognized attribute is up to the implementation. Notification Recipients MAY try to display unrecognized attributes anyway, or MAY ignore them 🌈.
The next three sections define the attributes in Event Notification Content that are:
- for all Events
- for Job Events only
- 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 the potential values in each Event Notification 💅.
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 are extra 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 "notify-attributes" depends on the Printer supporting the attribute, or it MAY say that the 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 extra attributes that a Delivery Method Document MUST specify for Job Events. See Table 6 🖨️.
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 extra 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 Printer9.2. Content of Human Consumable Event Notification 💌
okay bestie, this part is all about the human readable notifications 🫶 Here, a Delivery Method MUST mention, in its Delivery Method Document, the info that goes into a Human Consumable Event Notification or the value of the notify-text attribute 💅
A Delivery Method MUST specify the following info, and a Printer SHOULD deliver it ✨
- a) the Printer name (see Table 9)
- 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 below list the attributes a Printer MUST use to grab this info 🔍
A Delivery Method Document MUST also spell out any extra info (if there is any) that a Printer delivers in a Human Consumable Event Notification or in notify-text 📝
A client MUST NOT ask for extra attributes through notify-attributes, because that attribute only works for Machine Consumable Event Notifications. Not it 🙅♀️
Notification Recipients MUST NOT expect to be able to parse the Human Consumable Event Notification contents or the value of notify-text. It's giving "just read it, don't parse it" 🙈
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 where the info comes from for everything a Delivery Method MUST specify for all Events 🧚
There's a separate table for each piece of info. Each row is a source value for that info, and the rows are in order of preference, with the first one being the fave 👑 An implementation SHOULD use the source value from the earliest row in each table. It MAY use a source value from another row instead, or it MAY combine source values from several rows. The implementation is free to pick the best way to present the info 💖
Every row in the tables of this section contains a "MAY", which just states that the Delivery Method specifies the conformance 🎀
Table 9 covers the Printer Name. The printer-name is more user-friendly, unless the Notification Recipient is somewhere the Printer name doesn't mean anything. For example, an implementation could be smart enough to send the value of printer-name to a Notification Recipient that can reach the Printer through that value, and otherwise send the value of notify-printer-uri ✨
Table 9 - Printer Name in Event Notification Content
Source Value Delivers Source Object
printer-name (name(127)) MAY Printer
notify-printer-uri (uri) MAY SubscriptionTable 10 covers the Event name. A Printer MAY combine this info with the state info 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 SubscriptionTable 11 covers the time the Event happened ⏰ A Printer can only deliver this value if it supports the Printer's printer-current-time attribute. If a Printer does NOT support printer-current-time, it MUST NOT deliver the printer-up-time value instead, since that's not an allowed option for human consumable info 🙅♀️
Table 11 - Event Time in Event Notification Content
Source Value Delivers Source Object
printer-current-time (dateTime) MAY Printer9.2.2. Additional Event Notification Content for Job Events 🎀
This section lists where the extra info comes from that a Delivery Method MUST specify for Job Events 🦋
Table 12 covers the job name. The job-name is probably more meaningful to a user than job-id, so it's the one to lead with 💅
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 JobTable 13 covers the job state ⚡ If a Printer supports the job-state-message and job-detailed-state-message attributes, it SHOULD use those for the job state info. Otherwise, it should make up that info from job-state and job-state-reasons. For some Events, a Printer MAY combine this info with the Event info 🫶
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 Job9.2.3. Additional Event Notification Content for Printer Events 🖨️
This section lists where the extra info comes from that a Delivery Method MUST specify for Printer Events 💜
Table 14 covers the printer state. If a Printer supports printer-state-message, it SHOULD use that attribute for the job state info (yes, the original says "job", it's a vibe). Otherwise, it SHOULD fabricate that info from printer-state and printer-state-reasons. For some Events, a Printer MAY combine this info with the Event info 🌈
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 Printer10. Delivery Methods 🚚
A Delivery Method is the mechanism (aka the protocol) that a Printer uses to send an Event Notification to a Notification Recipient 📬 There are a bunch of possible Delivery Methods for Event Notifications, both standardized and proprietary. This specification REQUIRES that the 'ippget' Pull Delivery Method [RFC3996] be supported 🫶 Conforming implementations MAY support additional Push or Pull Delivery Methods too. This document doesn't define any of these delivery mechanisms, so each Delivery Method MUST be defined in a Delivery Method Document that's separate from this one 📄 New Delivery Methods will be created as needed by extending the registration procedures defined in [RFC2911]. Those documents get 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 explains how to define a Delivery Method Document and what goes in it 🧠
A Delivery Method Document MUST contain an exact copy of the following paragraph, caption and table. On top of that, column 2 of the table in the Delivery Method Document MUST contain answers to the questions in column 1 for that Delivery Method. The Delivery Method document MUST also contain a reference to this document, and it has to call that reference [RFC3995] because the table contains an [RFC3995] reference 💖
Here's the exact paragraph that has to be copied over:
"If a Printer supports this Delivery Method, the following are its characteristics."
And here's Table 15 (copy this one exactly too 🎀):
Table 15 - Information about the Delivery Method
Document Method Conformance Requirement Delivery Method
Realization
1. What is the URL scheme name for the Push Delivery Method or the
keyword method name for the Pull Delivery Method?
2. Is the Delivery Method REQUIRED, RECOMMENDED, or OPTIONAL for an
IPP Printer to support?
3. What transport and delivery protocols does the Printer use to
deliver the Event Notification Content, i.e., what is the entire
network stack?
4. Can several Event Notifications be combined into a Compound Event
Notification?
5. Is the Delivery Method initiated by the Notification Recipient
(pull), or by the Printer (push)?
6. Is the Event Notification content Machine Consumable or Human
Consumable?
7. What section in this document answers the following question?
For a Machine Consumable Event Notification, what is the
representation and encoding of values defined in section 9.1 of
[RFC3995] and the conformance requirements thereof? For a Human
Consumable Event Notification, what is the representation and
encoding of pieces of information defined in section 9.2 of
[RFC3995] and the conformance requirements thereof?
8. What are the latency and reliability of the transport and
delivery protocol?
9. What are the security aspects of the transport and delivery
protocol, e.g., how it is handled in firewalls?
10. What are the content length restrictions?
11. What are the additional values or pieces of information that a
Printer delivers in an Event Notification content and the
conformance requirements thereof?
12. What are the additional Subscription Template and/or
Subscription Description attributes and the conformance
requirements thereof?
13. What are the additional Printer Description attributes and the
conformance requirements thereof?11. Operations for Notification 📣
This section defines all of the operations for Notification 💅 Section 7.1 assigns the "operation-id" for each operation. The two sub-sections that follow define the 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 info 📖 The other Subscription Creation Operations refer back to that section on Create-Job-Subscriptions, even though Create-Job-Subscriptions 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 💖
okay so this operation makes one or more Per-Job Subscription Objects 🎀 The client sends one or more Subscription Template Attributes Groups, and each group holds one or more Subscription Template Attributes (defined in section 5.3). ✨
Here's the big rule 👑: 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 new one would behave exactly like a Subscription Object that already exists 🙈 Each new Per-Job Subscription Object MUST be associated with the target Job, which is named by the notify-job-id operation attribute 🔥
Now the job state stuff 💅 The Printer MUST accept the request in any of the target job's not-completed states, which are pending, pending-held, processing, or processing-stopped. The Printer MUST NOT change the job's job-state attribute because of this operation, so it's not sneakily moving anything around 🫶 If the target job is in any of the completed states, which are completed, canceled, or aborted, the Printer MUST reject the request and return the client-error-not-possible status code. In that case the response MUST NOT contain any Subscription Attribute Groups 😭
Access Rights: to create Per-Job Subscription Objects, the authenticated user (see [RFC2911] section 8.3) doing this operation MUST be one of these three things 🦋
- the job owner,
- someone with Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or
- someone otherwise authorized by the Printer's administrator-configured security policy to create Per-Job Subscription Objects for the target job.
If none of that applies, the Printer MUST reject the operation and return the client-error-forbidden, client-error-not-authenticated, or client-error-not-authorized status code, whichever fits 🙅♀️
11.1.1.1. Create-Job-Subscriptions Request 🎀
the Create-Job-Subscriptions Request has these groups of attributes 🧚
- Group 1: Operation Attributes 🌸
- Natural Language and Character Set: the
attributes-charsetandattributes-natural-languageattributes, as described in [RFC2911] section 3.1.4.1. - Target: the
printer-uriattribute, which defines the target for this operation as described in [RFC2911] section 3.1.5. - Requesting User Name: the client SHOULD supply the
requesting-user-nameattribute, as described in [RFC2911] section 8.3.
- Natural Language and Character Set: the
11.1.1.1.1. notify-job-id (integer(1:MAX)) 🍓
the client MUST supply this one, and it MUST point at the Job object the Per-Job Subscription belongs to 💜 The value of notify-job-id MUST be the value of the associated Job object's job-id. If the client leaves it out, the Printer MUST reject the request with the 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. Check section 5.3 for what each attribute does, and section 5.2 for how to process them 🌈
11.1.1.2. Create-Job-Subscriptions Response 🦋
the Printer MUST send these sets of attributes back in a Create-Job-Subscriptions response 🫶
- Group 1: Operation Attributes 🌸
- Status Message: along with the REQUIRED status code that every response has, the response can optionally include a
status-message(text(255)) and/or adetailed-status-message(text(MAX)) operation attribute, as described in [RFC2911] sections 13 and 3.1.6 ✨ - The Printer can return any status codes defined in [RFC2911] and section 12. Here are the important ones 👑
successful-ok: the Printer made every Subscription Object that was requested (see [RFC2911]) 🎉successful-ok-ignored-subscriptions: the Printer made some of the Subscription Objects that were requested, but some failed. The Subscription Attributes Groups that have anotify-status-codeattribute are the failed ones (see section 12.1) 😭client-error-ignored-all-subscriptions: the Printer made none of the requested Subscription Objects because they all failed. The Subscription Attributes Groups that have anotify-status-codeattribute are the failed ones (see section 12.2) 💀client-error-not-possible: for this operation and other Per-Job Subscription operations, this error can happen because the specified Job has already completed (see [RFC2911]). It doesn't matter whether the Job is still kept in the Job Retention and/or Job History phases (see [RFC2911] section 4.3.7.1) 🙈
- Natural Language and Character Set: the
attributes-charsetandattributes-natural-languageattributes, as described in [RFC2911] section 3.1.4.2.
- Status Message: along with the REQUIRED status code that every response has, the response can optionally include a
- Group 2: Unsupported Attributes 🧚
- Check [RFC2911] section 3.1.7 for how to return Unsupported Attributes. This group doesn't hold any unsupported Subscription Template Attributes, because those come back in the Subscription Attributes Group instead (see below) 💅
- Group 3-N: Subscription Attributes 💖
- These groups MUST be returned unless the Printer can't interpret the entire request. For example, that happens when the
status-codeparameter in Group 1 isclient-error-bad-request😭 notify-status-code(type2 enum): shows the status of this subscription (see section 13 for the status code definitions). Section 5.2 says when this attribute MUST be present in this group 🔥- Check section 5.2 for the details of what goes in each occurrence of this group 🎀
- These groups MUST be returned unless the Printer can't interpret the entire request. For example, that happens when the
11.1.2. Create-Printer-Subscriptions operation 🌈
this one is basically the same as Create-Job-Subscriptions, with a few changes noted here 💅
It creates Per-Printer Subscription Objects instead of Per-Job Subscription Objects. It ties each new Per-Printer Subscription Object to the Printer named by the operation target, not to one specific Job 🦋
The Printer MUST accept the request in any of its states, which are idle, processing, or stopped. The Printer MUST NOT change its printer-state attribute because of this operation 🫶
Access Rights: to create Per-Printer Subscription Objects, the authenticated user (see [RFC2911] section 8.3) doing this operation MUST have either (1) Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (2) otherwise be authorized by the Printer's administrator-configured security policy to create Per-Printer Subscription Objects for this Printer. Otherwise, the Printer MUST reject the operation and return the client-error-forbidden, client-error-not-authenticated, or client-error-not-authorized status code, whichever fits 🙅♀️
11.1.2.1. Create-Printer-Subscriptions Request 🎀
the groups match Create-Job-Subscriptions (see section 11.1.1.1), with one twist 🙈 The Operation Attributes group MUST NOT contain the notify-job-id attribute. If the client does send notify-job-id anyway, the Printer MUST treat it like any other unsupported Operation attribute and MUST return it in the Unsupported Attributes group 🧚
11.1.2.2. Create-Printer-Subscriptions Response 🌸
the groups match Create-Job-Subscriptions too (see section 11.1.1.2) 💖
11.1.3. Job Creation Operations - Extensions for Notification 🍓
this document extends the Job Creation operations (see section 3.2) so they can create Subscription Objects as part of the operation ✨
The Job Creation operations are the same as the Create-Job-Subscriptions operation, with a few exceptions noted here 🦋
Here's the difference 👑 A Job Creation operation ties the new Subscription Objects to the Job object that this same operation creates. The operation succeeds if and only if the Job creation succeeds 🔥 If the Printer doesn't create some or all of the requested Subscription Objects, it MUST return the successful-ok-ignored-subscriptions status-code instead of successful-ok. But the Printer MUST NOT reject the operation just because it failed to create Subscription Objects 🫶
If the Job Creation operation includes a Job Template group, the client MUST supply it after the Operation Attributes group and before the first Subscription Template Attributes Group 🌈
If a Printer doesn't support this Notification specification, it MUST treat the Subscription Attributes Group like an unknown group and ignore it (see [RFC2911] section 5.2.2). Since the Printer ignores the Subscription Attributes Group, it doesn't return them in the response either. That's how the client can tell the Printer doesn't support Notification 🙈
After a successful Job Creation operation finishes, the Printer generates a job-created event (see section 5.3.3.4.3) 🎉
Access Rights: to create Per-Job Subscription Objects, the authenticated user (see [RFC2911] section 8.3) doing this operation MUST either have permission to create Jobs on the Printer or have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the operation and return the client-error-forbidden, client-error-not-authenticated, or client-error-not-authorized status code, whichever fits 💅
11.1.3.1. Job Creation Request 🧚
the groups here are different enough from Create-Job-Subscriptions that I'm listing them all out 💜 A Job Creation Request has these groups of attributes 🎀
- Group 1: Operation Attributes 🌸
- Same as defined in [RFC2911] for Print-Job, Print-URI, and Create-Job requests.
- Group 2: Job Template Attributes ✨
- The client optionally supplies a set of Job Template attributes, as defined in [RFC2911] section 4.2.
- Group 3 to N: Subscription Template Attributes 🦋
- Same as Group 2-N in Create-Job-Subscriptions. See section 11.1.1.1.
- Group N+1: Document Content (Print-Job only) 👑
- The client MUST supply the document data to be processed. 😭
11.1.3.2. Job Creation Response ✨
okay bestie, this is what the Printer sends back after a Print-Job, Print-URI, or Create-Job request 💌 The Printer MUST return these sets of attributes as part of the response, no skipping 🫶
Group 1: Operation Attributes 🎀
Status Message:
As defined in [RFC2911] for Print-Job, Print-URI, and Create-Job requests.
In this group, the Printer can return any status codes defined in [RFC2911] and section 12. Here are the important ones 👀
successful-ok: the Printer created the Job and all Subscription Objects requested (see [RFC2911]. 💖successful-ok-ignored-subscriptions: the Printer created the Job but not all of the Subscription Objects requested (see section 12.1). This status-code hidessuccessful-ok-xxxstatus-codes that could reveal problems in Job creation, so it's kinda sneaky 🙈 The Printer MUST NOT return theclient-error-ignored-all-subscriptionsstatus code for Job Creation operations, because the Printer only returns an error status-code when it fails to create a Job 💅
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.2 🌸
Group 2: Unsupported Attributes 🦋
See [RFC2911] section 3.1.7 for details on returning Unsupported Attributes. This group doesn't contain any unsupported Subscription Template Attributes, because those go in the Subscription Attributes Group (see below) ✨
Group 3: Job Object Attributes 🧚
The "job-id" of the Job Object just created, etc., as defined in [RFC2911] for Print-Job, Print-URI, and Create-Job requests.
Group 4 to N: Subscription Attributes 👑
These groups MUST be returned if and only if the client supplied Subscription Template Attributes and the operation was accepted. See section 5.2 for details on the contents of each occurrence of this group. It's giving organized 🍓
11.2. Other Operations ✨
This section defines other operations on Subscription objects 🌈
11.2.1. Restart-Job Operation - Extensions for Notification
The Restart-Job operation [RFC2911] is neither a Job Creation operation nor a Subscription Creation operation (see section 3.2) 💜
For the Restart-Job operation, the client MUST NOT supply any Job Subscription Attributes Groups. The Printer MUST treat any supplied Job Subscription Attributes as unsupported attributes 🙅♀️
For this operation, the Printer doesn't return a job-id or any Subscription Attributes groups, because it reuses the existing Job object with the same job-id and the existing Per-Job Subscription Objects with the same subscription-ids. However, after this operation completes successfully, the Printer generates a job-created event (see section 5.3.3.4.3) ⭐
11.2.2. Validate-Job Operation - Extensions for Notification
A client can test whether one or more Subscription Objects could be created using the Validate-Job operation 🔍 The client supplies one or more Subscription Template Attributes Groups (defined in section 5.3), just like in a Job Creation request.
A Printer MUST support this extension to this operation 💖
The Printer MUST accept requests that are identical to the Job Creation request defined in section 11.1.3.1, except that the request MUST NOT contain document data.
The Printer MUST return the same groups and attributes as the Print-Job operation (section 11.1.3.1), with the following exceptions. The Printer MUST NOT return a Job Object Attributes Group, because no Job is created. The Printer MUST NOT return the "notify-subscription-id" attribute in any Subscription Attribute Group, because no Subscription Object is created 🙈
If the Printer would succeed in creating a Subscription Object, the corresponding Subscription Attributes Group either has no status-code attribute, or has a status-code attribute with a value of successful-ok-too-many-events or successful-ok-ignored-or-substituted-attributes (see sections 5.2 and 13). The status-codes have the same meaning as in Job Creation, except the results state what "would happen" 🎀
The Printer MUST validate Subscription Template Attributes Groups in the same manner as the Job Creation operations 💅
11.2.3. Get-Printer-Attributes - Extensions for Notification
This operation is extended so that it returns Printer attributes defined in this document ✨
A Printer MUST support this extension to this operation 🫶
In addition to the requirements of [RFC2911] section 3.2.5, a Printer MUST support the following additional values for the "requested-attributes" Operation attribute in this operation, and return such attributes in the Printer Object Attributes group of its response.
- Subscription Template Attributes: Each supported attribute in column 2 of Table 1.
- New Printer Description Attributes: Each supported attribute in section 6.
- New Group Name: The 'subscription-template' group name, which names all supported Subscription Template Attributes in column 2 of Table 1. This group name is also used in the Get-Subscription-Attributes and Get-Subscriptions operations with an analogous meaning 🦋
- Extended Group Name: The 'all' group name, which names all Printer attributes according to [RFC2911] section 3.2.5. In this extension, 'all' names all attributes specified in [RFC2911] plus those named in items 1 and 2 of this list 👑
11.2.4. Get-Subscription-Attributes operation
This operation lets a client request the values of the attributes of a Subscription Object 🧚
A Printer MUST support this operation 💖
This operation is almost identical to the Get-Job-Attributes operation (see [RFC2911] section 3.3.4). The only differences are that the operation is aimed at a Subscription Object rather than a Job object, and the returned attribute group contains Subscription Object attributes rather than Job object attributes 🌸
Access Rights: The authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. Otherwise the Printer MUST reject the operation and return the 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' status code, as appropriate. Furthermore, the Printer's security policy MAY limit which attributes are returned, in a manner similar to the Get-Job-Attributes operation (see [RFC2911] end of section 3.3.4.2) 🔐
11.2.4.1. Get-Subscription-Attributes Request
The following groups of attributes are part of the Get-Subscription-Attributes request 📝
Group 1: Operation Attributes 🎀
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language" attributes as described in section [RFC2911] 3.1.4.1 🌷
Target:
The "printer-uri" attribute, which defines the target for this operation as described in [RFC2911] section 3.1.5 🎯
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the client as described in [RFC2911] section 8.3 🙏
11.2.4.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this attribute. This attribute specifies the Subscription Object from which the client is requesting attributes. If the client omits this attribute, the Printer MUST reject this request with the 'client-error-bad-request' status code 💀
11.2.4.1.2. "requested-attributes" (1setOf keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST support this attribute. This attribute specifies the attributes of the specified Subscription Object that the Printer MUST return in the response. Each value of this attribute is either an attribute name (defined in sections 5.3 and 5.4) or an attribute group name. The attribute group names are:
- 'subscription-template': all attributes that are both defined in section 5.3 and present on the specified Subscription Object (column 1 of Table 1) 🍓
- 'subscription-description': all attributes that are both defined in section 5.4 and present on the specified Subscription Object (Table 2) 🌈
- 'all': all attributes that are present on the specified Subscription Object ⭐
A Printer MUST support all these group names.
If the client omits this attribute, the Printer MUST respond as if this attribute had been supplied with a value of 'all' 🫶
11.2.4.2. Get-Subscription-Attributes Response
The Printer returns the following sets of attributes as part of the Get-Subscription-Attributes Response 💌
Group 1: Operation Attributes 🎀
Status Message:
Same as [RFC2911].
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.2. The "attributes-natural-language" MAY be the natural language of the Subscription Object, rather than the one requested 🌸
Group 2: Unsupported Attributes 🦋
See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on returning Unsupported Attributes.
The response NEED NOT contain the "requested-attributes" operation attribute with any supplied keyword values that were requested by the client but are not supported by the IPP object. If the Printer object does return unsupported attributes referenced in the "requested-attributes" operation attribute, the values of the "requested-attributes" attribute returned MUST include only the unsupported keywords that were requested by the client. If the client had requested a group name, such as 'all', the resulting unsupported attributes returned MUST NOT include attribute keyword names described in the standard but not supported by the implementation 🙈
Group 3: Subscription Attributes 👑
This group contains a set of attributes with their current values. Each attribute returned in this group:
a) MUST be specified by the "requested-attributes" attribute in the request, AND b) MUST be present on the specified Subscription Object, AND c) MUST NOT be restricted by the security policy in force. For example, a Printer MAY prohibit a client who is not the creator of a Subscription Object from seeing some or all of its attributes. See [RFC2911] end of section 3.3.4.2 and section 8 🔒
The Printer can return the attributes of the Subscription Object in any order. The client MUST accept the attributes in any order 🧚
11.2.5. Get-Subscriptions operation ✨
okay so this operation lets a client grab the attributes of all the Subscription Objects that belong to a Job or a Printer 🫶
A Printer MUST supported this operation 💅
it's giving Get-Subscription-Attributes, except this one can return attributes from more than one object 🎀
it's also kind of a sibling of Get-Jobs ([RFC2911] section 3.2.6), except it hands back Subscription Objects instead of Job objects 🦋
Access Rights: okay this part is kind of a lot, bestie 🙈 To query Per-Job Subscription Objects of a specific job (the client supplies the "notify-job-id" operation attribute, see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. To query Per-Printer Subscription Objects of the Printer (the client omits the "notify-job-id" operation attribute, see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise authorized by the Printer's administrator-configured security policy to query Per-Printer Subscription Objects for the target Printer. Otherwise the Printer MUST reject the operation and return the 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' status code, whichever fits 🔥 Furthermore, the Printer's security policy MAY limit which attributes are returned, similar to Get-Jobs and Get-Printer-Attributes (see [RFC2911] end of sections 3.2.6.2 and 3.2.5.2) 🌸
11.2.5.1. Get-Subscriptions Request 💖
here are the groups of attributes that are part of the Get-Subscriptions request:
Group 1: Operation Attributes
Natural Language and Character Set: the "attributes-charset" and "attributes-natural-language" attributes, as described in [RFC2911] section 3.1.4.1.
Target: the "printer-uri" attribute, which defines the target for this operation as described in [RFC2911] section 3.1.5.
Requesting User Name: the "requesting-user-name" attribute SHOULD be supplied by the client, as described in [RFC2911] section 8.3.
11.2.5.1.1. "notify-job-id" (integer(1:MAX))
if the client specifies this attribute, the Printer returns the specified attributes of all Per-Job Subscription Objects tied to the Job whose "job-id" attribute value equals this attribute's value 🧚 If the client doesn't specify it, the Printer returns the specified attributes of all Per-Printer Subscription Objects.
Note: there is no way to get every Per-Job Subscription known to the Printer in one single operation 😭 A Get-Jobs operation followed by a Get-Subscriptions operation for each Job will return all Per-Job Subscriptions.
11.2.5.1.2. "limit" (integer(1:MAX))
the client optionally supplies this attribute, and the Printer MUST support it 💅 It's an integer that sets the maximum number of Subscription Objects a client will receive from the Printer, even if the "my-subscriptions" attribute already limits which ones come back. It's a "stateless limit": if the client sends 'N', then only the first 'N' Subscription Objects get returned in the Get-Subscriptions Response. There is no mechanism for getting the next 'M' Subscription Objects after the first 'N' 🙈 If the client doesn't supply this attribute, the Printer responds with all applicable Subscription Objects.
11.2.5.1.3. "requested-attributes" (1setOf type2 keyword)
the client optionally supplies this one too, and the Printer MUST support it ✨ It specifies the attributes of the specified Subscription Objects that the Printer MUST return in the response. Each value is either an attribute name (defined in sections 5.3 and 5.4) or an attribute group name (defined in section 11.2.4.1). If the client leaves this attribute out, the Printer MUST respond as if the client had supplied it with the one value: 'notify-subscription-id' 🦋
11.2.5.1.4. "my-subscriptions" (boolean)
the client optionally supplies this attribute, and the Printer MUST support it 🫶 If the value is 'false', the Printer MUST consider the Subscription Objects from all users as candidates. If the value is 'true', the Printer MUST return the Subscription Objects created by the requesting user of this request 👑 If the client doesn't supply it, the Printer MUST respond as if the client had supplied 'false'. The way the requesting user gets authenticated and matched to their Subscription Objects is similar to how Jobs work, described in [RFC2911] section 8.
11.2.5.2. Get-Subscriptions Response 🎀
here's what the Printer sends back as part of the Get-Subscriptions Response:
Group 1: Operation Attributes
Status Message: same as [RFC2911].
Natural Language and Character Set: the "attributes-charset" and "attributes-natural-language" attributes, as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
same as for Get-Subscription-Attributes.
Groups 3 to N: Subscription Attributes
the Printer responds with one Subscription Attributes Group for each requested Subscription Object (see the "notify-job-id" attribute in the Operation Attributes Group of this operation) 🌈
the Printer returns Subscription Objects in any order 🍓
if the "limit" attribute is present in the Operation Attributes group of the request, the number of Subscription Attributes Groups in the response MUST NOT exceed the value of the "limit" attribute 💜
if there are no Subscription Objects associated with the specified Job or Printer, the Printer MUST return zero Subscription Attributes Groups, and it MUST NOT treat this case as an error. That means the status-code MUST be 'successful-ok', unless something else causes the status code to have some other value 🌸
see the Group 3 response (Subscription Attributes Group) of the Get-Subscription-Attributes operation (section 11.2.4.2) for the attributes the Printer returns in this group ⭐
11.2.6. Renew-Subscription operation 🦋
this operation lets a client ask the Printer to extend the lease on a Per-Printer Subscription Object 💖
the Printer MUST support this operation 🔥
the Printer MUST accept this request for a Per-Printer Subscription Object in any of the target Printer's states ('idle', 'processing', or 'stopped'), but it MUST NOT change the Printer's "printer-state" attribute 🧚
the Printer MUST reject this request for a Per-Job Subscription Object, because Per-Job Subscription Objects have no lease (see section 5.4.3). The status code returned MUST be 'client-error-not-possible' 🙈
Access Rights: the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the owner of the Per-Printer Subscription Object, (2) have Operator or Administrator access rights for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to renew Per-Printer Subscription Objects for the target Printer. Otherwise, the Printer MUST reject the operation and return the 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' status code, whichever fits 🌈
11.2.6.1. Renew-Subscription Request ✨
here are the groups of attributes that are part of the Renew-Subscription Request:
Group 1: Operation Attributes
Natural Language and Character Set: the "attributes-charset" and "attributes-natural-language" attributes, as described in [RFC2911] section 3.1.4.1.
Target: the "printer-uri" attribute, which defines the target for this operation as described in [RFC2911] section 3.1.5.
Requesting User Name: the "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client, as described in [RFC2911] section 8.3.
11.2.6.1.1. "notify-subscription-id" (integer (1:MAX))
the client MUST supply this attribute, and the Printer MUST support it 🫶 It specifies the Per-Printer Subscription Object whose lease the Printer MUST renew. If the client omits it, the Printer MUST reject this request with the 'client-error-bad-request' status code 😭
Group 2: Subscription Template Attributes 💅
11.2.6.1.2. "notify-lease-duration" (integer(0:MAX))
the client optionally supplies this attribute. It indicates the number of seconds to renew the lease for the specified Subscription Object. A value of 0 requests an infinite lease (which MAY require Operator access rights) ♾️ If the client omits this attribute, the Printer MUST use the value of the Printer's "notify-lease-duration-default" attribute. See section 5.3.8 for more details 🎀
11.2.6.2. Renew-Subscription Response 🦋
here's what the Printer returns as part of the Renew-Subscription Response:
Group 1: Operation Attributes
Status Message: same as [RFC2911].
the following are some of the status codes that get returned (see [RFC2911]:
'successful-ok': the operation successfully renewed the lease on the Subscription Object for the requested duration ✅'successful-ok-ignored-or-substituted-attributes': the operation successfully renewed the lease on the Subscription Object for some duration other than the amount requested 🌸'client-error-not-possible': the operation failed because the "notify-subscription-id" Operation attribute identified a Per-Job Subscription Object 🙈'client-error-not-found': the operation failed because the "notify-subscription-id" Operation attribute identified a non-existent Subscription Object 💀
Natural Language and Character Set: the "attributes-charset" and "attributes-natural-language" attributes, as described in [RFC2911] section 3.1.4.2. The "attributes-natural-language" MAY be the natural language of the Subscription Object, rather than the one requested 🌈
Group 2: Unsupported Attributes
see [RFC2911] section 3.1.7 for details on returning Unsupported Attributes 🧚
Group 3: Subscription Attributes
the Printer MUST return the following Subscription Attribute:
11.2.6.2.1. "notify-lease-duration" (integer(0:MAX))
the value of this attribute MUST be the number of seconds that the Printer has granted for the lease of the Subscription Object. See section 5.3.8 for details, such as what this attribute's value is when the Printer doesn't support the requested value 💜
11.2.7. Cancel-Subscription operation 🗑️✨
okay bestie, this one is giving "delete it and never look back" 💅 This operation lets a client delete a Subscription Object so the Printer stops sending more Event Notifications. Once it's done, there is literally no way to reference that Subscription Object again 💀
A Printer MUST supported this operation. 🫶
The Printer MUST accept this request in any of the target Printer's states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change the Printer's "printer-state" attribute. It's giving calm and respectful 🧚
If the specified Subscription Object is a Per-Job Subscription Object, the Printer MUST accept this request in any of the target Job's states, but MUST NOT change the Job's "job-state" attribute or affect the Job. Nobody's job gets messed with, periodt 🌸
Note: There is no way to change any attributes on a Subscription Object, except the "notify-lease-duration" attribute (using the Renew-Subscription operation). To change other attributes, a client performs a Subscription Creation Operation and Cancel-Subscription operation on the old Subscription Object. If the client wants to avoid missing Event Notifications, it performs the Subscription Creation Operation first. If this order would create too many Subscription Objects on the Printer, the client reverses the order. 🔄💖
Access Rights: The authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the owner of the Subscription Object, (2) have Operator or Administrator access rights for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to cancel the target Subscription Object. Otherwise, the Printer MUST reject the operation and return: the 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' status code as appropriate. Bouncers are gonna bounce 🚫🎀
11.2.7.1. Cancel-Subscription Request 📬
The following groups of attributes are part of the Cancel-Subscription Request:
Group 1: Operation Attributes
- Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.1.
- Target: The "printer-uri" attribute which defines the target for this operation as described in [RFC2911] section 3.1.5.
- Requesting User Name: The "requesting-user-name" attribute SHOULD be supplied by the client as described in [RFC2911] section 8.3.
11.2.7.1.1. "notify-subscription-id" (integer (1:MAX)) 🆔
The client MUST supply this attribute. The Printer MUST support this attribute. This attribute specifies the Subscription Object that the Printer MUST cancel. If the client omits this attribute, the Printer MUST reject this request with the 'client-error-bad-request' status code. No ID, no cancel, bestie 🙈
11.2.7.2. Cancel-Subscription Response 🌈
The Printer returns the following sets of attributes as part of the Cancel-Subscription Response:
Group 1: Operation Attributes
- Status Message: Same as [RFC2911].
- The following are some of the status codes returned (see [RFC2911]:
successful-ok: The operation successfully canceled (deleted) the Subscription Object. 🎉client-error-not-found: The operation failed because the "notify-subscription-id" Operation attribute identified a non-existent Subscription Object. 💀
- Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.2. The "attributes-natural-language" MAY be the natural language of the Subscription Object, rather than the one requested.
Group 2: Unsupported Attributes
- See [RFC2911] section 3.1.7 for details on returning Unsupported Attributes. 🧾
12. Status Codes 🚦
The following status codes are defined as extensions for Notification and are returned as the value of the "status-code" parameter in the Operation Attributes Group of a response (see [RFC2911] section 3.1.6.1). Operations in this document can also return the status codes defined in section 13 of [RFC2911]. The 'successful-ok' status code is an example of such a status code. ✨
12.1. successful-ok-ignored-subscriptions (0x0003) 💜
The Subscription Creation Operation was unable to create all requested Subscription Objects.
For a Create-Job-Subscriptions or Create-Printer-Subscriptions operation, this status code means that the Printer created one or more Subscription Objects, but not all requested Subscription Objects.
For a Job Creation operation, this status code means that the Printer created the Job along with zero or more Subscription Objects. The Printer returns this status code even if other job attributes are unsupported or in conflict. That is, if an IPP Printer finds a warning that would allow it to return 'successful-ok-ignored-subscriptions' and either 'successful-ok-ignored-or-substituted-attributes' and/or 'successful-ok-conflicting-attributes', it MUST return 'successful-ok-ignored-subscriptions'. Main character energy for this code, honestly 👑
12.2. client-error-ignored-all-subscriptions (0x0414) 🙃
This status code is the same as 'successful-ok-ignored-subscriptions' except that only the Create-Job-Subscriptions and Create-Printer-Subscriptions operation return it. They return this status code only when the Printer creates zero Subscription Objects.
13. Status Codes in Subscription Attributes Groups 🧩
This section contains values of the "notify-status-code" (type2 enum) attribute that the Printer returns in a Subscription Attributes Group in a response when the corresponding Subscription Object:
- is not created or
- is created and some of the client-supplied attributes are not supported.
The following sections are ordered in decreasing order of importance of the status-codes. 📊
13.1. client-error-uri-scheme-not-supported (0x040C) 🔗
This status code is defined in [RFC2911]. This document extends its meaning and allows it to be in a Subscription Attributes Group of a response.
The scheme of the client-supplied URI in a "notify-recipient-uri" Subscription Template Attribute in a Subscription Creation Operation is not supported. See section 5.3.1.
13.2. client-error-attributes-or-values-not-supported (0x040B) 🙅♀️
This status code is defined in [RFC2911]. This document extends its meaning and allows it to be in a Subscription Attributes Group of a response.
The method of the client-supplied keyword in a "notify-pull-method" Subscription Template Attribute in a Subscription Creation Operation is not supported. See section 5.3.2.
13.3. client-error-too-many-subscriptions (0x0415) 🫠
The number of Subscription Objects supported by the Printer would be exceeded if this Subscription Object were created (see section 5.2).
13.4. successful-ok-too-many-events (0x0005) 🎈
The client supplied more Events in the "notify-events" operation attribute of a Subscription Creation Operation than the Printer supports, as indicated in its "notify-max-events-supported" Printer attribute (see section 5.3.3).
13.5. successful-ok-ignored-or-substituted-attributes (0x0001) 🍓
This status code is defined in [RFC2911]. This document extends its meaning to include unsupported Subscription Template Attributes and it can appear in a Subscription Attributes Group.
14. Encodings of Additional Attribute Tags 🔖
This section assigns values to two attributes tags as extensions to the encoding defined in [RFC2910]).
The "subscription-attributes-tag" delimits Subscription Template Attributes Groups in requests and Subscription Attributes Groups in responses.
The "event-notification-attributes-tag" delimits Event Notifications in Delivery Methods that use an IPP-like encoding.
The following table specifies the values for the delimiter tags:
Tag Value (Hex) Meaning
0x06 "subscription-attributes-tag"
0x07 "event-notification-attributes-tag"15. Conformance Requirements 📋💖
It is OPTIONAL for IPP clients and Printers to implement this Event Notification specification. Totally your call, bestie 🌸
15.1. Conformance requirements for clients 🧑💻
If this Event Notification specification is implemented by a client, the client MUST support the 'ippget' Pull Delivery Method and meet the conformance requirements as defined in [RFC3996] for clients. A client MAY support additional Delivery Methods.
15.2. Conformance requirements for Printers 🖨️
If this Event Notification specification is implemented by a Printer, the Printer MUST:
- meet the Conformance Requirements detailed in section 5 of [RFC2911].
- support the Subscription Template Attributes Group in requests and the Subscription Attributes Group in responses.
- support all of the following attributes:
- a. REQUIRED Subscription Object attributes in section 5.
- b. REQUIRED Printer Description object attributes in section 6.
- c. REQUIRED attributes in Event Notification content in section 8.
- support the 'ippget' Pull Delivery Method and meet the conformance requirements as defined in [RFC3996] for Printers. The Printer MAY support additional Push and Pull Delivery Methods.
- deliver Event Notifications that conform to the requirements of section 9 and the requirements of the Delivery Method Document for each supported Delivery Method (the conformance requirements for Delivery Method Documents is specified in section 10).
- for all of the Job Creation Operations that the Printer supports, MUST support the REQUIRED extensions for notification defined in section 11.1.3.
- meet the conformance requirements for operations as described in Table 16 and meet the requirements for Printers as specified in the indicated sub-sections of section 11:
Table 16 - Printer Conformance Requirements for Operations
Operation Printer
Conformance
Requirements
Create-Printer-Subscriptions (section 11.1.2) REQUIRED
Create-Job-Subscriptions (section 11.1.1) OPTIONAL
Get-Subscription-Attributes (section 11.2.3) REQUIRED
Get-Subscriptions (section 11.2.5) REQUIRED
Renew-Subscription (section 11.2.6) REQUIRED
Cancel-Subscription (section 11.2.7) REQUIREDThat's the whole conformance checklist, bestie! 🌈✨
16. Model for Notification with Cascading Printers (Informative) 🧚
okay so bestie, picture this: there's an intervening Print server sitting between the human user and the output-device 🖨️ which means the system effectively has two Printer objects. 😭 There are two cases to consider, so let's go 💅
- When the Printer 1 (in the server) generates Events, the system behaves like the client and Printer in Figure 1. In this case, Printer 1 delivers Event Notifications that are shown as Event Notifications (A) of Figure 2.
- When the Printer 2 (in the output-device) generates Events, there are two possible system configurations:
- a) Printer 1 forwards the client-supplied Subscription Creation Operations to the downstream Printer 2 and lets Printer 2 deliver the Event Notifications directly to the Notification Recipients supplied by the Client (Event Notifications(C) in the diagram).
- b) Printer 1 performs the client-supplied Subscription Creation Operations and also forwards the Subscription Creation Operations to Printer 2 with the Notification Recipient changed to be the Printer 1. When an Event occurs in Printer 2, Printer 2 delivers the Event Notification (B) to Notification Recipient of Printer 1, which relays the received Event Notification (B) to the client-supplied Notification Recipient (as Event Notifications(A) in the diagram). Note, when a client performs a Subscription Creation Operation, Printer 1 need not forward the Subscription Creation Operation to Printer 2 if it would create a duplicate Subscription Object on Printer 2.
Note: when Printer 1 is forwarding Subscription Creation Operations to Printer 2, it may request Printer 2 to create additional Subscription Objects (called "piggy-backing"). Piggy-backing is useful when:
- Device A is configured to accept (IPP or non-IPP) requests from other servers.
- Server S wants to receive Job Events that the client didn't request and Server S wants these Events for jobs it submits and not for other jobs.
server S device A
+------------+ +------------+
| | | |
| ###########| | ###########|
| # Printer #| Subscription | # Printer #|
| # Object 1#|---Creation------|># Object 2#|
| ###|#######| Operation | ####|#|####|
+----|---^---+ +-----|-|----+
| | | |
+-- Event Notifications(B)------+ |Okay, that diagram is a messy mood, so here's Figure 2 exactly as it appears in the RFC 🎀
server S device A
+------------+ +------------+
| | | |
+--------+ Subscription | ###########| | ###########|
| client |--Creation ----># Printer #| Subscription | # Printer #|
+--------+ Operation | # Object 1#|---Creation------|># Object 2#|
| ###|#######| Operation | ####|#|####|
+----|---^---+ +-----|-|----+
+--------+ Event | | | |
|Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ |
|ation Re|<-------------Event Notifications(C)-----------------+
|cipient |
+--------+Figure 2 - Model for Notification with Cascading Printers
17. Distributed Model for Notification (Informative) 🌸
A Printer implementation could use some other remote notification server to provide some or most of the service. 🫶 For example, the remote notification server could deliver Event Notifications using Delivery Methods that are not directly supported by the output device or Printer object. Or, the remote notification server could store Subscription Objects (passed to it from the output device in response to Subscription Creation requests), accept Events, format the Event Notification in the natural language of the Notification Recipient, and deliver the Event Notifications to the Notification Recipient(s). The main character energy of a notification server is real 👑
Figure 3 shows this partitioning. The interface between the output device (or Printer object) and the remote notification server is outside the scope of this document and is intended to be transparent to the client and this document.
***********************
*
* Printer in combination
* with the distributed
* Notification Server)
*
* output device or server
* +---------------+
PDA, desktop, or server * + ########### +
+--------+ * | # # |
| client |---IPP Subscription--------># Printer # |
+--------+ Creation operation * | # Object # |
* | #####|##### |
* +-------|-------+
* | Subscriptions
* | OR Event
+------------+ * | Notifications
|Notification| IPP-defined * +------v--------+
|Recipient |<--Event Notifications---| Notification |
+------------+ * | Server |
* +---------------+
*
*************************
*** = Implementation configuration opaque boundaryFigure 3 - Opaque Use of a Notification Server Transparent to the Client
18. Extended Notification Recipient (Informative) 🦋
The model allows for an extended Notification Recipient that is itself a notification server that forwards each Event Notification to another recipient (called the Ultimate Notification Recipient in this section). The Delivery Method to the Ultimate Recipient is probably different from the Delivery Method used by the Printer to the extended Notification Recipient.
This extended Notification Recipient is transparent to the Printer but not to the client. 👀
When a client performs a Subscription Creation Operation, it specifies the extended Notification Recipient as it would any Notification Recipient. In addition, the client specifies the Ultimate Notification Recipient in the Subscription Creation Operation in a manner specified by the extended Notification Recipient. Typically, it is either some bytes in the value of notify-user-data or some additional parameter in the value of notify-recipient-uri. The client also subscribes directly with the extended Notification Recipient (by means outside this document), since it is a notification server in its own right.
The IPP Printer treats the extended Notification Recipient like any other Notification Recipient and the IPP Printer is not aware of the forwarding. The Delivery Method that the extended Notification Recipient uses for delivering the Event Notification to the Ultimate Notification Recipient is beyond the scope of this document and is transparent to the IPP Printer.
Examples of this extended Notification Recipient are paging, immediate messaging services, general notification services, and NOS vendors' infrastructure. Figure 4 shows this approach. 🍓
PDA, desktop, or server server or output device
+---------------+
+--------+ | ########### |
| client |---Subscription Creation -----------># Printer # |
+--------+ Operation | # Object # |
| #####|##### |
+------------+ +------------+ IPP-defined +-------|-------+
|Ultimate | any |Notification|<--Event Notifications----+
|Notification|<----|Recipient |
|Recipient | +------------+
+------------+ (Notification Server)Figure 4 - Use of an Extended Notification Recipient transparent to the Printer
19. Object Model for Notification (Normative) 💜
This section describes the Notification object model that adds a Subscription Object which together with the Job and Printer object provide the complete Notification semantics. Okay this is the part where the objects all start mingling, so pay attention bestie 🙈
The object relationships can be seen pictorially as:
Subscription Objects (Per-Printer Subscriptions) Printer object
+----+ +------------+
| s1 |<--------------------------------------------->| |
+----++ | |
| s2 |<-------------------------------------------->| p1 |
+----++ | |
| s3 |<------------------------------------------->| |
+----+ +------------+
Job objects
+---------+
| |
+----+ | j1 |
| s4 |<------->| |
+----+ | |
| | s4 is a Per-Job Subscription Object
++--------++
| |
+----+ | j2 |
| s5 |<------>| |
+----++ | |
| s6 |<----->| | s5 and s6 are Per-Job Subscription
+----+ ++--------++ Objects
| |
| j3 |
| |
| | <----> indicates association
+---------+Figure 5 - Object Model for Notification
s1, s2, and s3 are Per-Printer Subscription Objects and can identify Printer and/or Job Events. s4, s5, and s6 are Per-Job Subscription Objects and can identify Printer and/or Job Events.
19.1. Object relationships ✨
This sub-section defines the object relationships between the Printer, Job, and Subscription Objects by example. Whether Per-Printer Subscription Objects are actually contained in a Printer object or are just bi-directionally associated with them in some way is IMPLEMENTATION DEPENDENT and is transparent to the client. Similarly, whether Per-Job Subscription Objects are actually contained in a Job object or are just bi-directionally associated with them in some way is IMPLEMENTATION DEPENDENT and is transparent to the client. The object relationships are defined as follows:
19.2. Printer Object and Per-Printer Subscription Objects 🖨️
- The Printer object contains (is associated with) zero or more Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer Subscription Objects).
- Each Per-Printer Subscription Object (s1, s2, and s3) is contained in (or is associated with) exactly one Printer object (p1).
19.3. Job Object and Per-Job Subscription Objects 💅
- A Job object (j1, j2, j3) is associated with zero or more Per-Job Subscription Objects (s4-s6). Job j1 is associated with Per-Job Subscription Object s4, Job j2 is associated with Per-Job Subscription Objects s5 and s6, and Job j3 is not associated with any Per-Job Subscription Object.
- Each Per-Job Subscription Object is associated with exactly one Job object.
20. Per-Job versus Per-Printer Subscription Objects (Normative) ✨
Okay so Per-Job and Per-Printer Subscription Objects are lowkey twins 👯♀️. Either type can subscribe to Job Events, Printer Events, or both 🔔. Both can be queried with Get-Subscriptions and Get-Subscription-Attributes, and both can be canceled with Cancel-Subscription 💅. They also create Subscription Objects with the same attributes defined. BUT there are some semantic differences between them, and that's where it gets spicy 🌶️.
A Per-Job Subscription Object is set up by the client when it submits a job. You create the job first, then use Create-Job-Subscriptions and point at the job with the "job-id" through the "notify-job-id" attribute 🎀. A Per-Printer Subscription Object is set up between a client and a Printer using Create-Printer-Subscriptions 🖨️. Some specific differences are:
- A client usually creates one or more Per-Job Subscription Objects as part of the Job Creation operations (
Create-Job,Print-Job, andPrint-URI), instead of using the OPTIONALCreate-Job-Subscriptionsoperation 🙈. That's especially true since Printer implementations NEED NOT supportCreate-Job-Subscriptions, because it is OPTIONAL. Bestie, it's giving "don't rely on the optional one" 💀. - A Per-Job Subscription Object is only valid while the job is
"not-complete"(see sections 5.4.3) ⏳. A Per-Printer Subscription Object is valid until the time (in seconds) that the Printer returned in the"notify-lease-expiration-time"operation attribute 🕰️. Different clocks, different vibes 💜. - Job Events in a Per-Job Subscription Object apply only to "one job" 🎯. That's the Job created by the Job Creation operation, or the one referenced by the
Create-Job-Subscriptionsoperation. Job Events in a Per-Printer Subscription Object apply to ALL jobs contained in the IPP Printer 🌈. Main character energy for the whole Printer 👑.
21. Normative References
[RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 📚[RFC2396]Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 🔗[RFC2717]Petke, R. and I. King, "Registration Procedures for URL Scheme Names", RFC 2717, November 1999. 🧾[RFC2910]Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet Printing Protocol/1.1: Encoding and Transport", RFC 2910, September 2000. 🖨️[RFC2911]deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, September 2000. ✨[RFC3381]Hastings, T., Lewis, H., and R. Bergman, "IPP: Job Progress Attributes", RFC 3381, September 2002. 📈[RFC3996]Herriot, R., Hastings, T., and H. Lewis, "Internet Printing Protocol (IPP): The 'ippget' Delivery Method for Event Notifications", RFC 3996, March 2005. 🫶
22. Informative References
[IANA-CON]Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. 🌸[RFC2565]Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet Printing Protocol/1.0: Encoding and Transport", RFC 2565, April 1999. 🍓[RFC2566]deBry, R., Hastings, T., Herriot, R., Isaacson, S., and P. Powell, "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, April 1999. 🧚[RFC2567]Wright, D., "Design Goals for an Internet Printing Protocol", RFC 2567, April 1999. 🎀[RFC2568]Zilles, S., "Rationale for the Structure and Model and Protocol for the Internet Printing Protocol", RFC 2568, April 1999. 🦋[RFC2569]Herriot, R., Hastings, T., Jacobs, N., and J. Martin, "Mapping between LPD and IPP Protocols", RFC 2569, April 1999. 🔁[RFC2616]Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol - HTTP/1.1", RFC 2616, June 1999. 🌐[RFC3196]Hastings, T., Manros, C., Zehler, P., Kugler, C., and H. Holst, "Internet Printing Protocol/1.1: Implementer's Guide", RFC 3196, November 2001. 📖[RFC3997]Hastings, T., Editor, deBry, R., and H. Lewis, "Internet Printing Protocol (IPP): Requirements for IPP Notifications", RFC 3997, March 2005. 💜
23. IANA Considerations 🌟
This section has the registration info that IANA added to the IPP Registry, following the procedures defined in RFC 2911 [RFC2911] section 6 for the definitions in this document. It also explains how Events and Delivery Methods will be registered when other documents define them 📝. The resulting registrations have been published in the http://www.iana.org/assignments/ipp-registrations registry 🗂️.
23.1. Attribute Registrations
The table below lists all the attributes defined in this document. They were registered following the procedures in RFC 2911 [RFC2911] section 6.2 💅.
Subscription Template attributes: Reference Section
--------------------------------- --------- -------
notify-attributes (1setOf type2 keyword) [RFC3995] 5.3.4
notify-attributes-supported (1setOf type2 keyword)
[RFC3995] 5.3.4.1
notify-charset (charset) [RFC3995] 5.3.6
notify-events (1setOf type2 keyword) [RFC3995] 5.3.3
notify-events-default (1setOf type2 keyword) [RFC3995] 5.3.3.1
notify-events-supported (1setOf type2 keyword) [RFC3995] 5.3.3.2
notify-lease-duration (integer(0:67108863)) [RFC3995] 5.3.8
notify-lease-duration-default (integer(0:67108863))
[RFC3995] 5.3.8.1
notify-lease-duration-supported (1setOf (integer(0: 67108863) |
rangeOfInteger(0:67108863))) [RFC3995] 5.3.8.2
notify-max-events-supported (integer(2:MAX)) [RFC3995] 5.3.3.3
notify-natural-language (naturalLanguage) [RFC3995] 5.3.7
notify-pull-method (type2 keyword) [RFC3995] 5.3.2
notify-pull-method-supported (1setOf type2 keyword)
[RFC3995] 5.3.2.1
notify-recipient-uri (uri) [RFC3995] 5.3.1
notify-schemes-supported (1setOf uriScheme) [RFC3995] 5.3.1.1
notify-time-interval (integer(0:MAX)) [RFC3995] 5.3.9
notify-user-data (octetString(63)) [RFC3995] 5.3.5
Subscription Description Attributes:
notify-job-id (integer(1:MAX)) [RFC3995] 5.4.6
notify-lease-expiration-time (integer(0:MAX)) [RFC3995] 5.4.3
notify-printer-up-time (integer(1:MAX)) [RFC3995] 5.4.4
notify-printer-uri (uri) [RFC3995] 5.4.5
notify-sequence-number (integer (0:MAX)) [RFC3995] 5.4.2
notify-subscriber-user-name (name(MAX)) [RFC3995] 5.4.7
notify-subscription-id (integer (1:MAX)) [RFC3995] 5.4.1
Printer Description Attributes:
printer-state-change-date-time (dateTime) [RFC3995] 6.2
printer-state-change-time (integer(1:MAX)) [RFC3995] 6.1
Attributes Only in Event Notifications
notify-subscribed-event (type2 keyword) [RFC3995] 8.1
notify-text (text(MAX)) [RFC3995] 8.223.2. Additional Enum Attribute Value Registrations within the IPP registry
The table below lists all the new enum attribute values defined in this document. They were registered within the IPP registry following the procedures in RFC 2911 [RFC2911] section 6.1 🧁.
Attribute
Value Name Reference Section
------ ----------------------------- --------- -------
operations-supported (1setOf type2 enum) [RFC2911] 4.4.15
0x0016 Create-Printer-Subscriptions [RFC3995] 7.1
0x0017 Create-Job-Subscriptions [RFC3995] 7.1
0x0018 Get-Subscription-Attributes [RFC3995] 7.1
0x0019 Get-Subscriptions [RFC3995] 7.1
0x001A Renew-Subscription [RFC3995] 7.1
0x001B Cancel-Subscription [RFC3995] 7.123.3. Operation Registrations
The table below lists all of the operations defined in this document. They were registered following the procedures in RFC 2911 [RFC2911] section 6.4 🎟️.
Operation Name Reference Section
--------------------------------- --------- -------
Cancel-Subscription [RFC3995] 11.2.7
Create-Job - Extensions [RFC3995] 11.1.3
Create-Job-Subscriptions [RFC3995] 11.1.1
Create-Printer-Subscriptions [RFC3995] 11.1.2
Get-Printer-Attributes - Extensions [RFC3995] 11.2.3
Get-Subscription-Attributes [RFC3995] 11.2.4
Get-Subscriptions [RFC3995] 11.2.5
Print-Job - Extensions [RFC3995] 11.1.3
Print-URI - Extensions [RFC3995] 11.1.3
Renew-Subscription [RFC3995] 11.2.6
Validate-Job Operation - Extensions [RFC3995] 11.2.223.4. Status code Registrations
The table below lists all the status codes defined in this document. They were registered following the procedures in RFC 2911 [RFC2911] section 6.6 🚦.
Value Status Code Name Reference Section
----- ---------------------------- --------- -------
0x0000:0x00FF - Successful:
0x0003 successful-ok-ignored-subscriptions [RFC3995] 12.1
0x0005 successful-ok-too-many-events [RFC3995] 13.4
0x0400:0x04FF - Client Error:
0x0414 client-error-ignored-all-subscriptions [RFC3995] 12.2
0x0415 client-error-too-many-subscriptions [RFC3995] 13.323.5. Attribute Group tag Registrations
The table below lists all the attribute group tags defined in this document. They were registered following the procedures in RFC 2911 [RFC2911] section 6.5 🏷️.
Value Attribute Group Tag Name Reference Section
----- -------------------------------- -------- -------
0x06 subscription-attributes-tag [RFC3995] 14
0x07 event-notification-attributes-tag [RFC3995] 1423.6. Registration of Events 🦋
okay so this is the events table, and it's giving organized. These are all the Events this document defines, written as type2 keywords you can use with the "notify-events", "notify-events-default", and "notify-events-supported" Subscription Template attributes (see section 5.3.3)). Instead of making a whole new section in the IPP Registry just for Events, these keywords got registered under the procedures of [RFC2911] section 7.1 as extra keyword values for the "notify-events" Subscription Template attribute (see section 5.3.3). That means they're registered as keyword values for "notify-events", "notify-events-default", and "notify-events-supported" 💜
Attribute (attribute syntax)
Value Reference Section
--------------------- --------- -------
notify-events (1setOf type2 keyword) [RFC3995] 5.3.3
notify-events-default (1setOf type2 keyword) [RFC3995] 5.3.3.1
notify-events-supported (1setOf type2 keyword) [RFC3995] 5.3.3.2
notify-subscribed-event (type2 keyword) [RFC3995] 8.1
No Events:
none [RFC3995] 5.3.3.4.1
Printer Events:
printer-state-changed [RFC3995] 5.3.3.4.2
printer-restarted [RFC3995] 5.3.3.4.2
printer-shutdown [RFC3995] 5.3.3.4.2
printer-stopped [RFC3995] 5.3.3.4.2
printer-config-changed [RFC3995] 5.3.3.4.2
printer-media-changed [RFC3995] 5.3.3.4.2
printer-finishings-changed [RFC3995] 5.3.3.4.2
printer-queue-order-changed [RFC3995] 5.3.3.4.2
Job Events:
job-state-changed [RFC3995] 5.3.3.4.3
job-created [RFC3995] 5.3.3.4.3
job-completed [RFC3995] 5.3.3.4.3
job-stopped [RFC3995] 5.3.3.4.3
job-config-changed [RFC3995] 5.3.3.4.3
job-progress [RFC3995] 5.3.3.4.323.7. Registration of Event Notification Delivery Methods 🌸
this section is the rulebook for registering Event Notification Delivery Methods and for submitting proposals for them. read it like it's your group chat's rules, because it's literally that strict 💅
23.7.1. Requirements for Registration of Event Notification Delivery Methods
registered IPP Event Notification Delivery Methods are expected to follow a bunch of requirements, which we'll go through below ✨
23.7.1.1. Required Characteristics
okay the first big rule: a Delivery Method Document MUST either (1) contain all of the semantics of the Delivery Method, or (2) contain the IPP Delivery Method registration requirements and a profile of some other protocol that together make up the Delivery Method (for example, mailto). The Delivery Method Document (and any documents it requires) MUST define either (1) a URL for a Push Delivery Method that the meets the requirements of [RFC2717]. or (2) a keyword for a Pull Delivery Method.
IPP Event Notification Delivery Method Documents MUST meet the requirements of this document (see sections 9 and 10). no skipping sections, bestie 🫶
on top of that, a Delivery Method Document MUST contain the following info:
Type of registration: IPP Event Notification Delivery Method
Name of this delivery method:
Proposed URL scheme name of this Push Delivery Method or the
keyword name of this Pull Delivery Method:
Name of proposer:
Address of proposer:
Email address of proposer:
Is this delivery method REQUIRED or OPTIONAL for conformance to
the IPP Event Notification and Subscriptions document:
Is this delivery method defining Machine Consumable and/or Human
Consumable content:23.7.1.2. Naming Requirements
🎀 exactly one (URL scheme or keyword) name MUST be assigned to each Delivery Method. each assigned name MUST uniquely identify a single Delivery Method, no sharing allowed. all Push Delivery Method names MUST follow the URL scheme name rules from [RFC2396] and [RFC2717] (for schemes in the IETF tree), and all Pull Delivery Method names MUST follow the keyword rules from [RFC2911].
23.7.1.3. Functionality Requirements
Delivery Methods MUST function as a protocol that can deliver IPP Event Notifications to Notification Recipients, whether that's by push or by pull. main character energy 👑
23.7.1.4. Usage and Implementation Requirements
ngl this one is so relatable. using a huge number of Delivery Methods can hamper interoperability 🙈 but a pile of undocumented and/or unlabeled Delivery Methods hampers it even more, so it's a whole vibe-check situation.
so a Delivery Method should therefore be registered ONLY if it adds significant functionality that's valuable to a large community, OR if it documents existing practice in a large community. and if you register one for the second reason, it should be explicitly marked as limited or specialized use, and should only be used with prior bilateral agreement 🧚
23.7.1.5. Publication Requirements
Delivery Method Documents MUST be published in standards track, informational, or experimental RFCs. only the official RFC lanes, no random blog posts 💀
23.7.2. Registration Procedure
the IPP WG is building a small number of Delivery Methods that are meant to be published as standards track RFCs. some parties might want to register extra Delivery Methods later on, though, so this section covers how that works 🌈
23.7.2.1. Present the proposal to the Community
first things first, the Delivery Method Document MUST be an Internet-Draft with a target category of standards track, informational, or experimental. the same MUST be true for any documents it references.
then deliver the proposed Delivery Method Document to the "ipp@pwg.org" mailing list. this list was set up by [RFC2911] for reviewing proposed registrations and talking about other IPP stuff. proposed Delivery Method Documents aren't formally registered yet, so they MUST NOT be used until they're approved 🚫
the whole point of posting publicly is to collect comments and feedback on the definition, whether it's suitable, and the name picked for it, over a four week period 🦋
23.7.2.2. Delivery Method Reviewer
the Delivery Method Reviewer is the same person the IETF Application Area Director(s) appointed as the IPP Designated Expert, per [RFC2911] and [IANA-CON]. when the four week period is over and the IPP Designated Expert is convinced consensus has been reached, they either approve the registration request or reject it. rejection can happen because of big objections raised on the list or objections raised from outside it 💅
decisions made by the Reviewer must be posted to the ipp@pwg.org mailing list within 14 days. and yes, decisions made by the Reviewer can be appealed to the IESG 👑
23.7.2.3. IANA Registration
as long as the Delivery Method registration proposal has either passed review or been successfully appealed to the IESG, the IANA will be notified by the delivery method reviewer and asked to register the Delivery Method and make it available to the community ✨
23.7.3. Delivery Method Document Registrations
okay so every Push Delivery Method Document defines a URI scheme. that scheme gets used in a URI value of the "notification-recipient" (uri) Subscription Template attribute (see section 5.3.1), and in the uriScheme value of the "notify-schemes-supported" (1setOf uriScheme 5.3.1.1) Printer attribute (see section ). instead of making a separate IPP Registry section for Delivery Methods, Push Delivery Methods get registered as an extra value of the "notify-schemes-supported" Printer attribute. those uriScheme values are registered under the procedures of [RFC2911] section 7.1 for additional attribute values. so the IPP Registry entry for a Push Delivery Method looks like this:
Attribute
Value Ref. Section
--------------------- -------- -------
notify-schemes-supported (1setOf uriScheme) [RFC3995] 5.3.1.1
<scheme name> RFC xxxx m.neach Pull Delivery Method Document defines a keyword method, which gets registered as an extra value of the "notify-pull-method" and "notify-pull-method-supported" Printer attributes. those keyword values are registered under the procedures of [RFC2911] section 7.1 for additional attribute values too. so the IPP Registry entry for a Pull Delivery Method looks like this 🍓
Attribute
Value Ref. Section
--------------------- -------- -------
notify-pull-method (type2 keyword) [RFC3995] 5.3.2
notify-pull-method-supported (1setOf type2 keyword)
[RFC3995] 5.3.2.1
<method keyword name> RFC xxxx m.n23.7.4. Registration Template
this is the template you fill in when you send in a new Delivery Method request 📝
To: ipp@pwg.org
Subject: Registration of a new Delivery Method
Delivery Method name:
(All Push Delivery Method names must be suitable for use as the value
of a URL scheme in the IETF tree and all Pull Delivery Method names
must be suitable IPP keywords according to [RFC2911])
Published specification(s):
(A specification for the Delivery Method must be openly available
that accurately describes what is being registered.)
Person & email address to contact for further information:24. Internationalization Considerations 🌍
this IPP Notification spec keeps supporting the internationalization that [RFC2911] set up for attributes with text strings and names. letting a Subscribing Client pick a different natural language and charset for each Subscription Object makes the i18n support even stronger 🌈
the Printer MUST be able to localize the content of Human Consumable Event Notifications, and to localize the value of the "notify-text" attribute in Machine Consumable Event Notifications that it delivers to Notification Recipients. for localization, the Printer MUST use the value of the "notify-charset" attribute and the "notify-natural-language" attribute in the Subscription Object the Subscribing Client supplied 💖
25. Security Considerations 🔥
okay bestie, this part is serious, so buckle up 😭
clients that submit Notification requests to the IPP Printer have the same security issues as submitting an IPP/1.1 print job request (see [RFC2911] section 3.2.1 and section 8). so the same mechanisms IPP/1.1 uses can also be used for Notification submission. operations that need authentication can use HTTP authentication, and operations that need privacy can use HTTP/TLS privacy. and just like with IPP/1.1 Print Job Objects, if there's no security on Subscription Objects, sequential assignment of subscription-ids exposes the system to a passive traffic monitoring threat. 💀🔐
25.1. Client access rights 🔐
Okay bestie, the access control model for Subscription Objects is literally the same as the one for Job objects 💅, so there's less to memorise. The client MUST have the following access rights for the indicated Subscription operations:
Create-Job-Subscriptions(see section 11.1.1): A Per-Job Subscription object is attached to a Job 🎀. To create Per-Job Subscription Objects, the authenticated user (see [RFC2911] section 8.3) doing this 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.Create-Printer-Subscriptions(see section 11.1.2): A Per-Printer Subscription object is attached to the Printer 🖨️. To create Per-Printer Subscription Objects, the authenticated user (see [RFC2911] section 8.3) doing this MUST (1) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5) or (2) be otherwise authorized by the Printer's administrator-configured security policy to create Per-Printer Subscription Objects for this Printer.Get-Subscription-Attributes(see section 11.2.4): The access control model here is the same as the one for theGet-Job-Attributesoperation (see [RFC2911] section 3.3.4). The main difference is that aGet-Subscription-Attributesoperation targets a Subscription Object instead of a Job object, and the returned attribute group holds Subscription Object attributes instead of Job object attributes. To query the specified Subscription Object, the authenticated user (see [RFC2911] section 8.3) doing this MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. Furthermore, the Printer's security policy MAY limit which attributes are returned, in a manner similar to theGet-Job-Attributesoperation (see [RFC2911] end of section 3.3.4.2).Get-Subscriptions(see section 11.2.5): The access control model here is the same as the one for theGet-Jobsoperation (see [RFC2911] section 3.2.6). The main difference is that the operation targets Subscription Objects instead of Job objects, and the returned attribute groups contain Subscription Object attributes instead of Job object attributes. To query Per-Job Subscription Objects of the specified job (the client supplies thenotify-job-idoperation attribute - see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) doing this MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. To query Per-Printer Subscription Objects of the Printer (the client omits thenotify-job-idoperation attribute - see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) doing this MUST (1) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise authorized by the Printer's administrator-configured security policy to query Per-Printer Subscription Objects for the target Printer. Furthermore, the Printer's security policy MAY limit which attributes are returned, in a manner similar to theGet-Job-Attributesoperation (see [RFC2911] end of section 3.2.6.2).Renew-Subscriptions(see section 11.2.6): The authenticated user (see [RFC2911] section 8.3) doing this MUST (1) be the owner of the Per-Printer Subscription Object, (2) have Operator or Administrator access rights for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to renew Per-Printer Subscription Objects for the target PrinterCancel-Subscription(see section 11.2.7): The authenticated user (see [RFC2911] section 8.3) doing this MUST (1) be the owner of the Subscription Object, (2) have Operator or Administrator access rights for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to cancel the target Subscription Object.
The standard security concerns (delivery to the right user, privacy of content, tamper proof content) apply to each Delivery Method. Some Delivery Methods are more secure than others. Each Delivery Method Document MUST discuss its Security Considerations. 🫶
25.2. Printer security threats 🚨
Notification trap door: If a Printer supports the OPTIONAL notify-attributes Subscription Template attribute (see section 5.3.4), where the client can request that the Printer return any specified Job, Printer, and Subscription object attributes, the Printer MUST apply the same security policy to these requested attributes in the Get-Notifications request as it does for the Get-Jobs, Get-Job-Attributes, Get-Printer-Attributes, and Get-Subscription-Attributes requests. 👀
25.3. Notification Recipient security threats 📬
Unwanted Events Notifications (spam): For any Push Delivery Method, by far the biggest security concern is the abuse of notification: delivering unwanted Event Notifications to third parties (i.e., spam). 😭 The problem gets worse because notification addresses may be passed around to multiple parties. There are scenarios where third party notification is used (see Scenario #2 and #3 in [RFC3997]). Any fully secure solution would require active agreement of all recipients before delivering anything. 🙈
26. Description of the base IPP documents (Informative) 📚
Okay, so the base set of IPP documents includes:
- Design Goals for an Internet Printing Protocol [RFC2567]
- Rationale for the Structure and Model and Protocol for the Internet Printing Protocol [RFC2568]
- Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
- Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
- Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
- Mapping between LPD and IPP Protocols [RFC2569]
The "Design Goals for an Internet Printing Protocol" document takes a broad look at distributed printing functionality 🌸. It walks through real-life scenarios that show which features a printing protocol for the Internet needs to include. It identifies requirements for three types of users: end users, operators, and administrators. It calls out a subset of end user requirements that are satisfied in IPP/1.0 [RFC2566, RFC2565]. A few OPTIONAL operator operations have been added to IPP/1.1 [RFC2911, RFC2910].
The "Rationale for the Structure and Model and Protocol for the Internet Printing Protocol" document describes IPP from a high-level view ✨. It maps out the various documents that make up the IPP specification suite, and it gives background and rationale for the IETF IPP working group's major decisions. Iconic. 👑
The "Internet Printing Protocol/1.1: Model and Semantics" document describes a simplified model with abstract objects, their attributes, and their operations 🧚. The model introduces a Printer and a Job, and the Job supports multiple documents per Job. The model document also covers how security, internationalization, and directory issues are addressed.
The "Internet Printing Protocol/1.1: Encoding and Transport" document is a formal mapping of the abstract operations and attributes from the model document onto HTTP/1.1 [RFC2616] 🦋. It also defines the encoding rules for a new Internet MIME media type called "application/ipp". This document defines the rules for transporting over HTTP a message body whose Content-Type is "application/ipp", and it defines the 'ipp' scheme for identifying IPP printers and jobs.
The "Internet Printing Protocol/1.1: Implementer's Guide" document gives insight and advice to implementers of IPP clients and IPP objects 💖. It's meant to help them understand IPP/1.1 and some of the considerations that can help when designing their client and/or IPP object implementations. For example, a typical order of processing requests is given, including error checking. Motivation for some of the specification decisions is also included.
The "Mapping between LPD and IPP Protocols" document gives some advice to implementers of gateways between IPP and LPD (Line Printer Daemon) implementations 🍓.
27. Contributors 🫶
The following people made significant contributions to the design and review of this specification. Shoutout to all of them 💜:
Scott A. Isaacson
Novell, Inc.
122 E 1700 S
Provo, UT 84606
Phone: 801-861-7366
Fax: 801-861-2517
EMail: sisaacson@novell.comRoger deBry
Utah Valley State College
Orem, UT 84058
Phone: 801-863-8848
EMail: debryro@uvsc.eduJay Martin
Underscore Inc.
9 Jacqueline St.
Hudson, NH 03051-5308
Phone: 603-889-7000
Fax: 775-414-0245
EMail: jkm@underscore.comMichael Shepherd
Xerox Corporation
800 Phillips Road MS 128-51E
Webster, NY 14450
Phone: 716-422-2338
Fax: 716-265-8871
EMail: mshepherd@usa.xerox.comRon Bergman
Ricoh Printing Systems America
1757 Tapo Canyon Road
Simi Valley, CA 93063-3394
Phone: 805-578-4421
Fax: 805-578-4001
EMail: ron.bergman@rpsa.ricoh.comAuthors' Addresses ✍️
Robert Herriot
Global Workflow Solutions
706 Colorado Ave.
Palo Alto, CA 94303
Phone: 650-324-4000
EMail: bob@herriot.comTom Hastings
Xerox Corporation
701 S Aviation Blvd, ESAE 242
El Segundo, CA 90245
Phone: 310-333-6413
Fax: 310-333-6342
EMail: hastings@cp10.es.xerox.comFull Copyright Statement ⚖️
Copyright (C) The Internet Society (2005).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property ⚖️
Okay so, the IETF is not taking a side 💅 on whether any intellectual property rights or other rights that someone might claim over the implementation or use of the technology in this document are valid or in scope. It also doesn't say whether any license under those rights might or might not be available. And it's not claiming it went digging on its own to find any of them 🙈. If you want the procedures for rights in RFC documents, check out BCP 78 and BCP 79 ✨.
Copies of IPR disclosures sent to the IETF Secretariat 📬, any assurances of licenses that will be made available, and the results of any attempt to get a general license or permission for implementers or users to use those proprietary rights can all be found in the IETF on-line IPR repository at http://www.ietf.org/ipr 🌸.
The IETF also invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard 🦋. Send that info to the IETF at ietf-ipr@ietf.org 💌.
Acknowledgement 🫶
Funding for the RFC Editor function is currently provided by the Internet Society 💖.
📦 where this page comes from
- ietf: rfc3995 2005-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms