Request for Comments: 3995 Global Workflow Solutions
Category: Standards Track T. Hastings
Updates: 2911, 2910 Xerox Corporation
March 2005
Internet Printing Protocol (IPP):
Event Notifications and Subscriptions
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This document describes an OPTIONAL extension to the Internet
Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910).
This extension allows a client to subscribe to printing related
Events. Subscriptions are modeled as Subscription Objects. The
Subscription Object specifies that when one of the specified Events
occurs, the Printer delivers an asynchronous Event Notification to
the specified Notification Recipient via the specified Push or Pull
Delivery Method (i.e., protocol).
A client associates Subscription Objects with a particular Job by
performing the Create-Job-Subscriptions operation or by submitting a
Job with subscription information. A client associates Subscription
Objects with the Printer by performing a Create-Printer-Subscriptions
operation. Four other operations are defined for Subscription
Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew-
Subscription, and Cancel-Subscription.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notification Overview. . . . . . . . . . . . . . . . . . 5
2. Models for Notification. . . . . . . . . . . . . . . . . . . . 8
2.1. Model for Simple Notification (Normative). . . . . . . . 8
2.2. Additional Models for Notification (Informative) . . . . 9
3. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1. Conformance Terminology. . . . . . . . . . . . . . . . . 9
3.2. Other Terminology. . . . . . . . . . . . . . . . . . . . 10
4. Object Relationships . . . . . . . . . . . . . . . . . . . . . 12
4.1. Printer and Per-Printer Subscription Objects . . . . . . 13
4.2. Printer, Job and Per-Job Subscription Objects. . . . . . 13
5. Subscription Object. . . . . . . . . . . . . . . . . . . . . . 13
5.1. Rules for Support of Subscription Template Attributes. . 14
5.2. Rules for Processing Subscription Template Attributes. . 15
5.3. Subscription Template Attributes . . . . . . . . . . . . 18
5.3.1. notify-recipient-uri (uri) . . . . . . . . . . . 20
5.3.2. notify-pull-method (type2 keyword) . . . . . . . 21
5.3.3. notify-events (1setOf type2 keyword) . . . . . . 22
5.3.4. notify-attributes (1setOf type2 keyword) . . . . 29
5.3.5. notify-user-data (octetString(63)) . . . . . . . 30
5.3.6. notify-charset (charset) . . . . . . . . . . . . 31
5.3.7. notify-natural-language (naturalLanguage). . . . 31
5.3.8. notify-lease-duration (integer(0:67108863)). . . 32
5.3.9. notify-time-interval (integer(0:MAX)). . . . . . 33
5.4. Subscription Description Attributes. . . . . . . . . . . 34
5.4.1. notify-subscription-id (integer (1:MAX)). . . . 35
5.4.2. notify-sequence-number (integer (0:MAX)) . . . . 35
5.4.3. notify-lease-expiration-time (integer(0:MAX)). . 36
5.4.4. notify-printer-up-time (integer(1:MAX)). . . . . 37
5.4.5. notify-printer-uri (uri) . . . . . . . . . . . . 37
5.4.6. notify-job-id (integer(1:MAX)) . . . . . . . . . 37
5.4.7. notify-subscriber-user-name (name(MAX)). . . . . 38
6. Printer Description Attributes Related to Notification . . . . 38
6.1. printer-state-change-time (integer(1:MAX)) . . . . . . . 39
6.2. printer-state-change-date-time (dateTime). . . . . . . . 39
7. New Values for Existing Printer Description Attributes . . . . 39
7.1. operations-supported (1setOf type2 enum) . . . . . . . . 40
8. Attributes Only in Event Notifications . . . . . . . . . . . . 40
8.1. notify-subscribed-event (type2 keyword). . . . . . . . . 40
8.2. notify-text (text(MAX)). . . . . . . . . . . . . . . . . 41
9. Event Notification Content . . . . . . . . . . . . . . . . . . 41
9.1. Content of Machine Consumable Event Notifications. . . . 44
9.1.1. Event Notification Content Common to All Events. 44
9.1.2. Additional Event Notification Content for Job
Events . . . . . . . . . . . . . . . . . . . . . 45
9.1.3. Additional Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . 46
9.2. Content of Human Consumable Event Notification . . . . . 46
9.2.1. Event Notification Content Common to All Events. 47
9.2.2. Additional Event Notification Content for Job
Events . . . . . . . . . . . . . . . . . . . . . 49
9.2.3. Additional Event Notification Content for
Printer Events . . . . . . . . . . . . . . . . . 49
10. Delivery Methods . . . . . . . . . . . . . . . . . . . . . . . 50
11. Operations for Notification. . . . . . . . . . . . . . . . . . 52
11.1. Subscription Creation Operations . . . . . . . . . . . . 52
11.1.1. Create-Job-Subscriptions Operation . . . . . . . 52
11.1.2. Create-Printer-Subscriptions operation . . . . . 55
11.1.3. Job Creation Operations - Extensions for
Notification . . . . . . . . . . . . . . . . . . 56
11.2 Other Operations. . . . . . . . . . . . . . . . . . . . . 58
11.2.1. Restart-Job Operation - Extensions for
Notification . . . . . . . . . . . . . . . . . . 58
11.2.2. Validate-Job Operation - Extensions for
Notification . . . . . . . . . . . . . . . . . . 59
11.2.3. Get-Printer-Attributes - Extensions for
Notification . . . . . . . . . . . . . . . . . . 59
11.2.4. Get-Subscription-Attributes operation. . . . . . 60
11.2.5. Get-Subscriptions operation. . . . . . . . . . . 63
11.2.6. Renew-Subscription operation . . . . . . . . . . 66
11.2.7. Cancel-Subscription operation. . . . . . . . . . 68
12. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . 70
12.1. successful-ok-ignored-subscriptions (0x0003) . . . . . . 70
12.2. client-error-ignored-all-subscriptions (0x0414). . . . . 71
13. Status Codes in Subscription Attributes Groups . . . . . . . . 71
13.1. client-error-uri-scheme-not-supported (0x040C) . . . . . 71
13.2. client-error-attributes-or-values-not-supported (0x040B) 71
13.3. client-error-too-many-subscriptions (0x0415) . . . . . . 72
13.4. successful-ok-too-many-events (0x0005) . . . . . . . . . 72
13.5. successful-ok-ignored-or-substituted-attributes (0x0001) 72
14. Encodings of Additional Attribute Tags . . . . . . . . . . . . 72
15. Conformance Requirements . . . . . . . . . . . . . . . . . . . 72
15.1. Conformance requirements for clients . . . . . . . . . . 73
15.2. Conformance requirements for Printers. . . . . . . . . . 73
16. Model for Notification with Cascading Printers (Informative) . 74
17. Distributed Model for Notification (Informative) . . . . . . . 75
18. Extended Notification Recipient (Informative). . . . . . . . . 76
19. Object Model for Notification (Normative). . . . . . . . . . . 77
19.1. Object relationships . . . . . . . . . . . . . . . . . . 78
19.2. Printer Object and Per-Printer Subscription Objects. . . 79
19.3. Job Object and Per-Job Subscription Objects. . . . . . . 79
20. Per-Job versus Per-Printer Subscription Objects (Normative). . 79
21. Normative References . . . . . . . . . . . . . . . . . . . . . 80
22. Informative References . . . . . . . . . . . . . . . . . . . . 80
23. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 81
23.1. Attribute Registrations. . . . . . . . . . . . . . . . . 82
23.2. Additional Enum Attribute Value Registrations within
the IPP registry . . . . . . . . . . . . . . . . . . . . 83
23.3. Operation Registrations. . . . . . . . . . . . . . . . . 83
23.4. Status code Registrations. . . . . . . . . . . . . . . . 83
23.5. Attribute Group tag Registrations. . . . . . . . . . . . 84
23.6. Registration of Events . . . . . . . . . . . . . . . . . 84
23.7. Registration of Event Notification Delivery Methods. . . 85
23.7.1. Requirements for Registration of Event
Notification Delivery Methods. . . . . . . . . . 85
23.7.2. Registration Procedure . . . . . . . . . . . . . 86
23.7.3. Delivery Method Document Registrations . . . . . 87
23.7.4. Registration Template. . . . . . . . . . . . . . 88
24. Internationalization Considerations. . . . . . . . . . . . . . 89
25. Security Considerations. . . . . . . . . . . . . . . . . . . . 89
25.1. Client access rights . . . . . . . . . . . . . . . . . . 89
25.2. Printer security threats . . . . . . . . . . . . . . . . 91
25.3. Notification Recipient security threats. . . . . . . . . 91
26. Description of the base IPP documents (Informative). . . . . . 92
27. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 93
Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . . . 94
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 95
Tables
Table 1 - Subscription Template Attributes. . . . . . . . . . . . 20
Table 2 - Subscription Description Attributes . . . . . . . . . . 35
Table 3 - Printer Description Attributes Associated with
Notification. . . . . . . . . . . . . . . . . . . . . . 39
Table 4 - Operation-id assignments. . . . . . . . . . . . . . . . 40
Table 5 - Attributes in Event Notification Content. . . . . . . . 45
Table 6 - Additional Event Notification Content for Job Events. . 46
Table 7 - Combinations of Events and Subscribed Events for
"job-impressions-completed" . . . . . . . . . . . . . . 46
Table 8 - Additional Event Notification Content for Printer
Events. . . . . . . . . . . . . . . . . . . . . . . . . 46
Table 9 - Printer Name in Event Notification Content. . . . . . . 48
Table 10 - Event Name in Event Notification Content. . . . . . . . 48
Table 11 - Event Time in Event Notification Content. . . . . . . . 48
Table 12 - Job Name in Event Notification Content. . . . . . . . . 49
Table 13 - Job State in Event Notification Content . . . . . . . . 49
Table 14 - Printer State in Event Notification Content . . . . . . 50
Table 15 - Information about the Delivery Method . . . . . . . . . 51
Table 16 - Printer Conformance Requirements for Operations . . . . 74
Figures
Figure 1 - Model for Notification. . . . . . . . . . . . . . . . . 9
Figure 2 - Model for Notification with Cascading Printers. . . . . 75
Figure 3 - Opaque Use of a Notification Server Transparent to the
Client. . . . . . . . . . . . . . . . . . . . . . . . . 76
Figure 4 - Use of an Extended Notification Recipient transparent
to the Printer. . . . . . . . . . . . . . . . . . . . . 77
Figure 5 - Object Model for Notification . . . . . . . . . . . . . 78
1. Introduction
This IPP notification specification is an OPTIONAL extension to
Internet Printing Protocol/1.1: Model and Semantics [RFC2911,
RFC2910]. See Appendix 29 for a description of the base IPP
documents. This document in combination with the following documents
is intended to meet the most important notification requirements
described in [RFC3997]:
Internet Printing Protocol (IPP): "Job Progress Attributes"
[RFC3381]
Internet Printing Protocol (IPP): "The ’ippget’ Delivery Method
for Event Notifications" [RFC3996]
This specification REQUIRES that clients and Printers support the
’ippget’ Pull Delivery Method [RFC3996]. Conforming client and
Printer implementations MAY support additional Push or Pull Delivery
Methods as well. Note: this document does not define any Delivery
Methods itself, but it does define the rules for conformance for
Delivery Method Documents and their registration with IANA (see
section 23.7.3).
Refer to the Table of Contents for the layout of this document.
1.1. Notification Overview
This document defines operations that a client can perform in order
to create Subscription Objects in a Printer and carry out other
operations on them. A Subscription Object represents a Subscription
abstraction. The Subscription Object specifies that when one of the
specified Events occurs, the Printer delivers an asynchronous Event
Notification to the specified Notification Recipient via the
specified Delivery Method (i.e., protocol).
When a client (called a Subscribing Client) performs an operation
that creates a Subscription Object, the operation contains one or
more Subscription Template Attributes Groups. Each such group holds
information used by the Printer to initialize a newly created
Subscription Object. The Printer creates one Subscription Object for
each Subscription Template Attributes Group in the operation. This
group is like the Job Template Attributes group defined in [RFC2911].
The following is an example of the information included in a
Subscription Template Attributes Group (see section 5 for details on
the Subscription Object attributes):
1. The names of Subscribed Events that are of interest to the
Notification Recipient.
2. The address (URL) of one Notification Recipient for a Push
Delivery Method or the method for a Pull Delivery Method.
3. The Delivery Method (i.e., the protocol) which the Printer uses to
deliver the Event Notification.
4. Some opaque data that the Printer delivers to the Notification
Recipient in the Event Notification. For example, the
Notification Recipient might use this opaque data as a forwarding
address for the Event Notification.
5. The charset to use in text fields within an Event Notification
6. The natural language to use in the text fields of the Event
Notification
7. The requested lease time in seconds for the Subscription Object
An operation that creates a Subscription Object is called a
Subscription Creation Operation. These operations include the
following operations (see section 11.1 for further details):
- Job Creation operation: When a client performs such an
operation (Print-Job, Print-URI, and Create-Job), a client can
include zero or more Subscription Template Attributes Groups in
the request. The Printer creates one Subscription Object for
each Subscription Template Attributes Group in the request, and
the Printer associates each such Subscription Object with the
newly created Job. This document extends these operations’
definitions in [RFC2911] by adding Subscription Template
Attributes Groups in the request and Subscription Attributes
Groups in the response.
- Create-Job-Subscriptions operation: A client can include one or
more Subscription Template Attributes Groups in the request.
The Printer creates one Subscription Object for each
Subscription Template Attributes Group and associates each with
the job that is the target of this operation.
- Create-Printer-Subscriptions operation: A client can include
one or more Subscription Template Attributes Groups in the
request. The Printer creates one Subscription Object for each
Subscription Template Attributes Group and associates each with
the Printer that is the target of this operation.
For each of the above operations:
- the Printer associates a Subscription Object with the Printer
or a specific Job. When a Subscription Object is associated
with a Job Object, it is called a Per-Job Subscription Object.
When a Subscription Object is associated with a Printer Object,
it is called a Per-Printer Subscription Object.
- the response contains one Subscription Attributes Group for
each Subscription Template Attributes Group in the request and
in the same order. When the Printer successfully creates a
Subscription Object, its corresponding Subscription Attributes
Group contains the "notify-subscription-id" attribute. This
attribute uniquely identifies the Subscription Object and is
analogous to a "job-id" for a Job object. Some operations
described below use the "notify-subscription-id" to identify
the target Subscription Object.
This document defines the following additional operations (see
section 11.2 for further details):
- Restart-Job operation: When a client performs the Restart-Job
operation [RFC2911], the Printer re-uses the same Job and its
Subscription Objects.
- Validate-Job operation: When a client performs this operation, a
client can include zero or more Subscription Template Attributes
Groups in the request. The Printer determines if it could create
one Subscription Object for each Subscription Template Attributes
Group in the request. This document extends this operation’s
definition in [RFC2911] by adding Subscription Template Attributes
Groups in the request and Subscription Attributes Groups in the
response.
- Get-Subscription-Attributes operation: This operation allows a
client to obtain the specified attributes of a target Subscription
Object.
- Get-Subscriptions operation: This operation allows a client to
obtain the specified attributes of all Subscription Objects
associated with the Printer or a specified Job.
- Renew-Subscription operation: This operation renews the lease on
the target Per-Printer Subscription Object before it expires. A
newly created Per-Printer Subscription Object receives an initial
lease. It is the duty of the client to use this operation
frequently enough to preserve a Per-Printer Subscription Object.
The Printer deletes a Per-Printer Subscription Object when its
lease expires. A Per-Job Subscription Object last exactly as long
as its associated Job Object and thus doesn’t have a lease.
- Cancel-Subscription operation: This operation (1) cancels the
lease on the specified Per-Printer Subscription Object and thereby
deletes the Per-Printer Subscription Object or (2) deletes the
Per-Job Subscription Object.
When an Event occurs, the Printer finds all Subscription Objects
listening for the Event (see section 9 for details on finding such
Subscription Objects). For each such Subscription Object, the
Printer:
a) generates an Event Notification with information specified in
section 9, AND
b) either:
i) If the Delivery Method is a Push Delivery Method as indicated
by the presence of the Subscription Object’s "notify-
recipient-uri" attribute, delivers the Event Notification
using the Delivery Method and target address identified in the
Subscription Object’s "notify-recipient-uri" attribute, OR
ii) If the Delivery Method is a Pull Delivery Method as indicated
by the presence of the Subscription Object’s "notify-pull-
method" attribute, saves Event Notification for a time period
called the Event Life defined by the Delivery Method, i.e.,
the Notification Recipient is expected to fetch the Event
Notifications.
2. Models for Notification
2.1. Model for Simple Notification (Normative)
As part of a Subscription Creation Operation, an IPP Printer (i.e.,
located in an output device or a server) creates one or more
Subscription Objects. In a Subscription Creation Operation, the
client specifies the Notification Recipient to which the Printer is
to deliver Event Notifications. A Notification Recipient can be the
Subscribing Client or a third party.
Figure 1 shows the Notification model for a simple Client-Printer