Internet Printing Protocol WG R. Herriot (editor)
INTERNET-DRAFT T. Hastings
<draft-ietf-ipp-not-spec-08.txt> M. Shepherd
Updates RFC 2910 and 2911 Xerox Corporation
[Target Category: standards track] R. deBry
Expires: May 19, 2002 Utah Valley State College
S. Isaacson
Novell, Inc.
J. Martin
Underscore
R. Bergman
Hitachi Koki Imaging Solutions
November 19, 2001
Internet Printing Protocol (IPP):
Event Notifications and Subscriptions
Copyright (C) The Internet Society (2001). All Rights Reserved.
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of [RFC2026]. Internet-Drafts are
working documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups. Note that other groups may also
distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress".
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed as
http://www.ietf.org/shadow.html.
Abstract
This document describes an OPTIONAL extension to the Internet
Printing Protocol/1.0 (IPP) [RFC2566, RFC2565] and IPP/1.1 [RFC2911,
RFC2910]. 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 sends an asynchronous Event Notification
to the specified Notification Recipient via the specified 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
Herriot, et al. Expires May 19, 2002 [page 1]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
client associates Subscription Objects with the Printer by performing
a Create-Printer-Subscriptions operation. Four other operations are
defined for Subscription Objects: Get-Subscriptions-Attributes, Get-
Subscriptions, Renew-Subscription, and Cancel-Subscription.
Herriot, et al. Expires May 19, 2002 [page 2]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table of Contents
1 Introduction.....................................................7
1.1 Notification Overview..........................................7
2 Models for Notification.........................................10
2.1 Model for Notification (Simple Case)..........................10
2.2 Model for Notification with Cascading Printers................11
2.3 Distributed Model for Notification............................11
2.4 Extended Notification Recipient...............................12
3 Terminology.....................................................12
3.1 Conformance Terminology.......................................12
3.2 Other Terminology.............................................13
4 Object Relationships............................................16
4.1 Printer and Per-Printer Subscription Objects..................16
4.2 Printer, Job and Per-Job Subscription Objects.................16
5 Subscription Object.............................................16
5.1 Rules for Support of Subscription Template Attributes.........17
5.2 Rules for Processing Subscription Template Attributes.........18
5.3 Subscription Template Attributes..............................22
5.3.1 notify-recipient-uri (uri) OR notify-pull-method (type2
keyword)...............................................25
5.3.1.1 notify-recipient-uri (uri)................................25
5.3.1.2 notify-pull-method (type2 keyword)........................25
5.3.2 notify-events (1setOf type2 keyword)........................26
5.3.2.1 Standard Values for Subscribed Events.....................26
5.3.2.1.1 No Events...............................................27
5.3.2.1.2 Subscribed Printer Events...............................27
5.3.2.1.3 Subscribed Job Events...................................29
5.3.2.2 Rules for Matching of Subscribed Events...................30
5.3.2.2.1 Rules for Matching of Printer Events....................30
5.3.2.2.2 Rules for Matching of Job Events........................31
5.3.2.2.3 Special Cases for Matching Rules........................31
5.3.3 notify-attributes (1setOf type2 keyword)....................32
5.3.4 notify-user-data (octetString(63))..........................34
5.3.5 notify-charset (charset)....................................34
5.3.6 notify-natural-language (naturalLanguage)...................35
5.3.7 notify-lease-duration (integer(0:67108863)).................35
5.3.8 notify-time-interval (integer(0:MAX)).......................36
5.4 Subscription Description Attributes...........................38
5.4.1 notify-subscription-id (integer (1:MAX))...................38
5.4.2 notify-sequence-number (integer (0:MAX))....................39
5.4.3 notify-lease-expiration-time (integer(0:MAX))...............39
5.4.4 notify-printer-up-time (integer(1:MAX)).....................40
Herriot, et al. Expires May 19, 2002 [page 3]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.4.5 notify-printer-uri (uri)....................................41
5.4.6 notify-job-id (integer(1:MAX))..............................41
5.4.7 notify-subscriber-user-name (name(MAX)).....................42
6 Printer Description Attributes Related to Notification..........42
6.1 printer-state-change-time (integer(1:MAX))....................43
6.2 printer-state-change-date-time (dateTime).....................43
7 New Values for Existing Printer Description Attributes..........43
7.1 operations-supported (1setOf type2 enum)......................43
8 Attributes Only in Event Notifications..........................44
8.1 notify-subscribed-event (type2 keyword).......................44
8.2 notify-text (text(MAX)).......................................45
9 Event Notification Content......................................45
9.1 Content of Machine Consumable Event Notifications.............48
9.1.1 Event Notification Content Common to All Events.............48
9.1.2 Additional Event Notification Content for Job Events........50
9.1.3 Additional Event Notification Content for Printer Events....51
9.2 Content of Human Consumable Event Notification................51
9.2.1 Event Notification Content Common to All Events.............52
9.2.2 Additional Event Notification Content for Job Events........54
9.2.3 Additional Event Notification Content for Printer Events....55
10 Delivery Methods...............................................56
11 Operations for Notification....................................58
11.1 Subscription Creation Operations.............................58
11.1.1 Create-Job-Subscriptions Operation.........................59
11.1.1.1 Create-Job-Subscriptions Request.........................59
11.1.1.2 Create-Job-Subscriptions Response........................60
11.1.2 Create-Printer-Subscriptions operation.....................61
11.1.2.1 Create-Printer-Subscriptions Request.....................62
11.1.2.2 Create-Printer-Subscriptions Response....................62
11.1.3 Job Creation Operations - Extensions for Notification......62
11.1.3.1 Job Creation Request.....................................63
11.1.3.2 Job Creation Response....................................64
11.2 Other Operations.............................................65
11.2.1 Restart-Job Operation - Extensions for Notification........65
11.2.2 Validate-Job Operation - Extensions for Notification.......65
11.2.3 Get-Printer-Attributes - Extensions for Notification.......66
11.2.4 Get-Subscription-Attributes operation......................66
11.2.4.1 Get-Subscription-Attributes Request......................67
11.2.4.2 Get-Subscription-Attributes Response.....................68
11.2.5 Get-Subscriptions operation................................69
11.2.5.1 Get-Subscriptions Request................................69
11.2.5.2 Get-Subscriptions Response...............................71
Herriot, et al. Expires May 19, 2002 [page 4]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
11.2.6 Renew-Subscription operation...............................72
11.2.6.1 Renew-Subscription Request...............................72
11.2.6.2 Renew-Subscription Response..............................73
11.2.7 Cancel-Subscription operation..............................74
11.2.7.1 Cancel-Subscription Request..............................75
11.2.7.2 Cancel-Subscription Response.............................75
12 Conformance Requirements.......................................76
13 IANA Considerations............................................77
13.1 Attribute Registrations......................................78
13.2 Additional Enum Attribute Value Registrations for the
"operations-supported" Printer Attribute..........................79
13.3 Operation Registrations......................................79
13.4 Status code Registrations....................................80
13.5 Attribute Group tag Registrations............................80
13.6 Registration of Events.......................................80
13.7 Registration of Event Notification Delivery Methods..........81
13.7.1 Requirements for Registration of Event Notification Delivery
Methods................................................81
13.7.1.1 Required Characteristics.................................81
13.7.1.2 Naming Requirements......................................82
13.7.1.3 Functionality Requirements...............................82
13.7.1.4 Usage and Implementation Requirements....................82
13.7.1.5 Publication Requirements.................................83
13.7.2 Registration Procedure.....................................83
13.7.2.1 Present the proposal to the Community....................83
13.7.2.2 Delivery Method Reviewer.................................83
13.7.2.3 IANA Registration........................................84
13.7.3 Delivery Method Document Registrations.....................84
13.7.4 Registration Template......................................84
14 Internationalization Considerations............................85
15 Security Considerations........................................85
16 Status Codes...................................................86
16.1 successful-ok-ignored-subscriptions (0x0003).................86
16.2 client-error-ignored-all-subscriptions (0x0414)..............87
17 Status Codes in Subscription Attributes Groups.................87
17.1 client-error-uri-scheme-not-supported (0x040C)...............87
17.2 client-error-attributes-or-values-not-supported (0x040B).....87
17.3 client-error-too-many-subscriptions (0x0415).................88
17.4 successful-ok-too-many-events (0x0005).......................88
17.5 successful-ok-ignored-or-substituted-attributes (0x0001).....88
18 Encodings of Additional Attribute Tags.........................88
Herriot, et al. Expires May 19, 2002 [page 5]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
19 References.....................................................89
20 Author's Addresses.............................................90
A. Appendix - Model for Notification with Cascading Printers......92
B. Appendix - Distributed Model for Notification..................93
C. Appendix - Extended Notification Recipient.....................94
D. Appendix - Details about Conformance Terminology...............95
E. Appendix - Object Model for Notification.......................96
E.1 Appendix - Object relationships..............................97
E.2 Printer Object and Per-Printer Subscription Objects..........98
E.3 Job Object and Per-Job Subscription Objects..................98
F. Appendix - Per-Job versus Per-Printer Subscription Objects.....98
G. Appendix - Description of the base IPP documents...............99
H. Appendix - Full Copyright Statement...........................100
Tables
Table 1 - Subscription Template Attributes........................24
Table 2 - Subscription Description Attributes.....................38
Table 3 - Printer Description Attributes Associated with Notification
..............................................................42
Table 4 - Operation-id assignments................................44
Table 5 - Attributes in Event Notification Content................49
Table 6 - Additional Event Notification Content for Job Events....50
Table 7 - Combinations of Events and Subscribed Events for "job-
impressions-completed" ........................................51
Table 8 - Additional Event Notification Content for Printer Events51
Table 9 - Printer Name in Event Notification Content..............53
Table 10 - Event Name in Event Notification Content...............53
Table 11 - Event Time in Event Notification Content...............54
Table 12 - Job Name in Event Notification Content.................54
Table 13 - Job State in Event Notification Content................55
Table 14 - Printer State in Event Notification Content............56
Table 15 - Information about the Delivery Method..................57
Table 16 - Printer Conformance Requirements for Operations........77
Figures
Figure 1 - Model for Notification.................................11
Figure 2 - Model for Notification with Cascading Printers.........93
Figure 3 - Opaque Use of a Notification Service Transparent to the
Client ........................................................94
Herriot, et al. Expires May 19, 2002 [page 6]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Figure 4 - Use of an Extended Notification Recipient transparent to
the Printer ...................................................95
Figure 5 - Object Model for Notification..........................97
1 Introduction
This IPP notification specification is an OPTIONAL extension to
Internet Printing Protocol/1.0 (IPP) [RFC2566, RFC2565] and IPP/1.1
[RFC2911, RFC2910]. See Appendix G for a description of the base IPP
documents. This document in combination with the following documents
is intended to meet the notification requirements described in [ipp-
not-req]:
Internet Printing Protocol (IPP): "Job Progress Attributes"
[ipp-prog]
One or more Delivery Method Documents registered with IANA (see
section 10).
Note: this document does not define any Delivery Methods, but it does
define the rules for conformance for Delivery Method Documents.
Delivery Method Documents are in preparation (see section 10) and
will be registered with IANA (see section 13.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 sends 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):
Herriot, et al. Expires May 19, 2002 [page 7]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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 send the Event Notification.
4.Some opaque data that the Printer sends to the Notification
Recipient in the Event Notification. 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.
Herriot, et al. Expires May 19, 2002 [page 8]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
- 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.
Herriot, et al. Expires May 19, 2002 [page 9]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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 Notification (Simple Case)
As part of a Subscription Creation Operation, an IPP Printer (i.e.,
located in an output device or a server) creates one or more
Subscription Objects. In a Subscription Creation Operation, the
client specifies the Notification Recipient to which the Printer is
to deliver Event Notifications. A Notification Recipient can be the
Subscribing Client or a third party.
Figure 1 shows the Notification model for a simple Client-Printer
relationship.
Herriot, et al. Expires May 19, 2002 [page 10]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
embedded printer:
output device or server
PDA, desktop, or server +---------------+
+--------+ | ########### |
| client |-----Subscription ---------># Printer # |
+--------+ Creation Operation | # Object # |
+------------+ | #####|##### |
|Notification| +-------|-------+
|Recipient |<----IPP Event Notifications----+
+------------+ (Job and/or Printer Events)
Figure 1 - Model for Notification
2.2 Model for Notification with Cascading Printers
With this model, there is an intervening Print server between the
human user and the Printer in the output device. If the Printer in
the output device generates an Event, the system can be configured to
send Event Notification either
- directly to the Notification Recipient specified by the
Subscribing Client or
- via the Print Server to the Notification Recipient specified by
the Subscribing Client.
See Appendix A for more details.
2.3 Distributed Model for Notification
The preceding sections (2.1 and 2.2) assume that the Notification
software resides in the same device or Server box as the rest of the
Printer software. In many implementations, the assumption is correct.
However, the Notification model also permits a distributed
implementation.
For example, the software that supports both Subscription Creation
Operations and sending of Event Notifications could be on hardware
that is separate from the output device. To make this work, there
must be a symbiotic relationship between the output device software
and the remote Notification software. Without the remote Notification
software, the output device software is not a complete Printer.
Herriot, et al. Expires May 19, 2002 [page 11]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
The term "Printer" in this document includes the software on the
output device or server box as well as Notification software that is
local to or remote from the output device.
Appendix B describes this example in detail.
2.4 Extended Notification Recipient
The model allows for an extended Notification Recipient that is
itself a Notification service that forwards each Event Notification
to another recipient. The client contacts this Notification Recipient
to arrange for forwarding by means outside the scope of this
document. The Printer need not be aware that the Notification
Recipient forwards Event Notifications.
Appendix C describes this example in detail.
3 Terminology
This section defines terminology used throughout this document. Other
terminology is defined in [RFC2911].
3.1 Conformance Terminology
Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to
conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section
12.1. If an implementation supports the extension defined in this
document, then these terms apply; otherwise, they do not. These
terms define conformance to this document only; they do not affect
conformance to other documents, unless explicitly stated otherwise.
See Appendix D for complete details.
Note: a feature that is OPTIONAL in this document becomes REQUIRED if
the Printer implements a Delivery Method that REQUIRES the feature.
READ-ONLY - an adjective used in an attribute definition to indicate
that an IPP Printer MUST NOT allow the attribute's value to be
modified with the Set-Job-Attributes or Set-Printer-Attributes
operations (see [ipp-set]). Note: there is no Set-Subscription
operation so this term is not used for Subscription object
attributes.
Herriot, et al. Expires May 19, 2002 [page 12]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
3.2 Other Terminology
This document uses the same terminology as [RFC2911], such as
"client", "Printer", "attribute", "attribute value", "keyword",
"operation", "request", "response", and "support". In addition, the
following terms are defined for use in this document and the Delivery
Method Documents:
Administrator - A human user who establishes policy for and
configures the print system.
Operator - A human user who carries out the policy established by the
Administrator and controls the day to day running of the print
system.
IPP Client (or client) - The software component (PDA, desktop, or
server) that performs an IPP operation directed at an IPP Printer
(located in a server or output device).
Job Creation operation - One of the operations that creates a Job
object: Print-Job, Print-URI and Create-Job. The Restart-Job
operation [RFC2911] is not considered a Job Creation operation,
since the Printer re-uses the existing Job object. The Validate-
Job operation is not considered a Job Creation operation because
no Job object is created. Therefore, when a statement also
applies to either the Restart-Job and/or the Validate-Job
operation, they are mentioned explicitly.
Event - some occurrence (either expected or unexpected) within the
printing system of a change of state, condition, or configuration
of a Job or Printer object. An Event occurs only at one instant in
time and does not span the time the physical Event takes place.
For example, jam-occurred and jam-cleared are two distinct,
instantaneous Events, even though the jam may last for a while.
Event Notification - the information about an Event that the Printer
sends when an Event occurs.
Compound Event Notification - two or more Event Notifications that a
Printer sends together as a single entity. The Delivery Method
Document specifies whether the Delivery Method supports Compound
Event Notifications.
Job Event - an Event caused by some change in a particular job on the
Printer, e.g., 'job-completed'.
Printer Event - an Event caused by some change in the Printer that is
not specific to a job, e.g., 'printer-state-changed'.
Herriot, et al. Expires May 19, 2002 [page 13]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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.
Notification Recipient - the entity to which the Printer sends an
Event Notification.
Delivery Method - the mechanism by which the Printer delivers the
Event Notification, e.g., via email or via an Event Notification
Delivery Method protocol defined for delivering IPP Event
Notifications.
Delivery Method Document - a document, separate from this document,
that defines a Delivery Method.
Push Delivery Method -The Printer sends the Event Notification
shortly after an Event occurs. For some Push Delivery Methods, the
Notification Recipient MUST send a response; for others it MUST
NOT send a response.
Pull Delivery Method - The Printer saves Event Notifications for some
event life time and expects the Notification Recipient to request
Event Notifications. The Printer returns the Event Notifications
in a response to such a request.
Event Life - For a Pull Delivery Method, the length of time in
seconds after an Event occurs during which the Printer will
return that Event in response to a request for Event
Notifications. After the Event Life expires, the Printer will
no longer return an Event Notification for that Event in such a
response.
Subscription Object - An object containing a set of attributes that
indicate: the Notification Recipient, the Delivery Method, the
Subscribed Events that cause the Printer to send an Event
Notification, and the information to send in an Event
Notification.
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.
Herriot, et al. Expires May 19, 2002 [page 14]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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.
Subscribing Client - The client that creates the Subscription Object.
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 a Subscription object. 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 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 Description Attributes - Subscription Object attributes
that a Printer supplies during a Subscription Creation Operation.
Subscription Template Attributes Group - The attributes group in a
request that contains Subscription Object attributes that are
Subscription Template Attributes.
Subscription Attributes Group - The attributes group in a response
that contains Subscription Object attributes.
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.
Machine Consumable Event Notification - bytes for program
consumption. The bytes are formatted according to the Delivery
Method document.
Printer - the software that supports an output device or print server
(see IPP/1.1 [RFC2911] which uses the terms Printer and Printer
object interchangeably). This document extends the IPP/1.1 Printer
definition to include the software that implements Subscription
Creation Operations and the sending of Event Notifications, even
Herriot, et al. Expires May 19, 2002 [page 15]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
if the software for such a Printer would be distributed across a
network (see section 2.3).
Notification - when not in the phrases 'Event Notification' and
'Notification Recipient' - the concepts of this specification,
i.e., Events, Subscription Objects, and Event Notifications.
4 Object Relationships
This section defines the object relationships between the Printer,
Job, and Subscription Objects. It does not define the
implementation. For an illustration of these relationships, see
Appendix E.
4.1 Printer and Per-Printer Subscription Objects
1.A Printer object can be associated with zero or more Per-Printer
Subscription Objects.
2.Each Per-Printer Subscription Object is associated with exactly
one Printer object.
4.2 Printer, Job and Per-Job Subscription Objects
1.A Printer object is associated with zero or more Job objects.
2.Each Job object is associated with exactly one Printer object.
3.A Job object is associated with zero or more Per-Job Subscription
Objects.
4.Each Per-Job Subscription Object is associated with exactly one
Job object.
5 Subscription Object
A Subscribing Client creates a Subscription Object with a
Subscription Creation Operation in order to indicate its interest in
certain Events. See section 11 for a description of these operations.
When an Event occurs, the Subscription Object specifies to the
Printer where to send Event Notifications, how to send them and what
to put in them. See section 9 for details on the contents of an Event
Notification.
Herriot, et al. Expires May 19, 2002 [page 16]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Using the IPP Job Template attributes as a model (see [RFC2911]
section 4.2), the attributes of a Subscription Object are divided
into two categories: Subscription Template Attributes and
Subscription Description Attributes.
Subscription Template attributes are, in turn, like the Job Template
attributes, divided into
1.Subscription Object attributes that a client can supply in a
Subscription Creation Request and
2.their associated Printer Object attributes that specify
supported and default values for the Subscription Object
attributes
The remainder of this section specifies general rules for
Subscription Template Attributes and describes each attribute in a
Subscription Object.
5.1 Rules for Support of Subscription Template Attributes
Subscription Template Attributes are fundamental to the Notification
model described in this specification. The client supplies these
attributes in Subscription Creation Operations and the Printer uses
these attributes to populate a newly created Subscription Object.
Subscription Objects attributes that are Subscription Template
Attributes conform to the following rules:
1.Each attribute's name starts with the prefix string "notify-"
and this document calls such attributes "notify-xxx".
2.For each "notify-xxx" Subscription Object attribute defined in
column 1 of Table 1 in section 5.3, Table 1 specifies
corresponding Printer attributes: "notify-xxx-default", "notify-
xxx-supported", "yyy-supported" and "notify-max-xxx-supported"
defined in column 2 of Table 1. Note "xxx" stands for the same
string in each case and "yyy" stands for some other string.
3.If a Printer supports "notify-xxx" in column 1 of Table 1, then
the Printer MUST support all associated attributes specified in
column 2 of Table 1. For example, Table 1 shows that if the
Printer supports "notify-events", it MUST support "notify-
events-default", "notify-events-supported" and "notify-max-
events-supported".
Herriot, et al. Expires May 19, 2002 [page 17]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
4.If a Printer does not support "notify-xxx" in column 1 of Table
1, then the Printer MUST NOT support any associated "notify-yyy"
attributes specified in column 2 of Table 1. For example, Table
1 shows that if the Printer doesn't support "notify-events", it
MUST NOT support "notify-events-default", "notify-events-
supported" and "notify-max-events-supported". Note this rule
does not apply to attributes whose names do not start with the
string "notify-" and are thus defined in another object and used
by other attributes.
5.Most "notify-xxx" attributes have a corresponding "yyy-
supported" attribute that specifies the supported values for
"notify-xxx". Column 2 of Table 1 specifies the name of each
"yyy-supported" attribute. The naming rules of IPP/1.1 (see
[RFC2911]) are used when "yyy-supported" is "notify-xxx-
supported".
6.Some "notify-xxx" attributes have a corresponding "notify-xxx-
default" attribute that specifies the value for "notify-xxx" if
the client does not supply it. Column 2 of Table 1 specifies the
name of each "notify-xxx-default" attribute. The naming rules of
IPP/1.1 (see [RFC2911]) are used.
If a client wishes to present an end user with a list of supported
values from which to choose, the client SHOULD query the Printer for
its supported value attributes. The client SHOULD also query the
default value attributes. If the client then limits selectable
values to only those values that are supported, the client can
guarantee that the values supplied by the client in the create
request all fall within the set of supported values at the Printer.
When querying the Printer, the client MAY enumerate each attribute by
name in the Get-Printer-Attributes Request, or the client MAY just
supply the 'subscription-template' group name in order to get the
complete set of supported attributes (both supported and default
attributes - see section 11.2.3).
5.2 Rules for Processing Subscription Template Attributes
This section defines a detailed set of rules that a Printer follows
when it processes Subscription Template Attributes in a Subscription
Creation Request. These rules are similar to the rules for processing
Operation attributes in [RFC2911]. That is, the Printer may or may
not support an attribute and a client may or may not supply the
attribute. Some combinations of these cases are OK. Others return
warnings or errors, and perhaps a list of unsupported attributes.
Herriot, et al. Expires May 19, 2002 [page 18]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
A Printer MUST implement the following behavior for processing
Subscription Template Attributes in a Subscription Creation Request:
1.If a client supplies a "notify-xxx" attribute from column 1 of
Table 1 and the Printer supports it and its value, the Printer
MUST populate the attribute on the created Subscription Object.
2.If a client supplies a "notify-xxx" attribute from column 1 of
Table 1 and the Printer doesn't support it or its value, the
Printer MUST NOT populate the attribute on the created
Subscription Object with it. The Printer MUST do one of the
following:
a) If the value of the "notify-xxx" attribute is unsupported, the
Printer MUST return the attribute with its value in the
Subscription Attributes Group of the response.
b) If "notify-xxx" is an unsupported attribute, the Printer MUST
return the attribute in the Subscription Attributes Group of the
response with the 'unsupported' out-of-band value.
Note: The rules of this step are the same as for Unsupported
Attributes [RFC2911] section 3.1.7. except that the unsupported
attributes are returned in the Subscription Attributes Group
rather than the Unsupported Attributes Group because Subscription
Creation Operations can create more than one Subscription Object).
3.If a client is REQUIRED to supply a "notify-xxx" attribute from
column 1 of Table 1 and the Printer doesn't support the supplied
value, the Printer MUST NOT create a Subscription Object. The
rules for Unsupported Attributes in step #2 still apply.
4.If a client does not supply a "notify-xxx" attribute from column 1
of Table 1 and the attribute is REQUIRED for the client to supply,
the Printer MUST reject the Subscription Creation Operation
(including Job Creation operations) without creating a
Subscription Object, and MUST return in the response:
c) the status code 'client-error-bad-request' AND
d) no Subscription Attribute Groups.
5.If a client does not supply a "notify-xxx" attribute from column 1
of Table 1 that is OPTIONAL for the client to supply, and column 2
of Table 1 either:
a) specifies a "notify-xxx-default" attribute, the Printer MUST
behave as if the client had supplied the "notify-xxx-default"
Herriot, et al. Expires May 19, 2002 [page 19]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
attribute (see step #1) and populate the Subscription object
with the value of the "notify-xxx-default" attribute as part of
the Subscription Creation operation (unlike Job Template
attributes where the Printer does not populate the Job object
with defaults - see [RFC2911]) OR
b) does not specify a "notify-xxx-default" attribute, the Printer
MUST populate the "notify-xxx" attribute on the Subscription
Object according to the definition of the "notify-xxx" attribute
in a section 5.3. For some attributes, the "notify-xxx" is
populated with the value of some other attribute, and for
others, the "notify-xxx" is NOT populated on the Subscription
object at all.
6.A Printer MUST create a Subscription Object for each Subscription
Template Attributes group in a request unless the Printer:
a) encounters some attributes in a Subscription Template Attributes
Group that require the Printer not to create the Subscription
Object OR
b) would create a Per-Job Subscription Object when it doesn't have
space for another Per-Job Subscription Object OR
c) would create a Per-Printer Subscription Object when it doesn't
have space for another Per-Printer Subscription Object.
7.A response MUST contain one Subscription Attributes Group for each
Subscription Template Attributes Group in the request (and in the
same order) whether the Printer creates a Subscription Object from
the Subscription Template Attributes Group or not. However, the
attributes in each Subscription Attributes Group can be in any
order.
8.The Printer MUST populate each Subscription Attributes Group of
the response such that each contains:
a) the "notify-subscription-id" attribute (see section 5.4.1), if
and only if the Printer creates a Subscription Object.
b) the "notify-lease-duration" attribute (see section 5.3.7), 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.7). If a client supplies this attribute in the
creation of a Per-Job Subscription Object, it MUST appear in
Herriot, et al. Expires May 19, 2002 [page 20]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
this group with the out-of-band value 'unsupported' to indicate
that the Printer doesn't support it in this context.
c) all of the unsupported Subscription Template Attributes from
step #2. Note, they are not returned in the Unsupported
Attributes Group in order to separate the unsupported attributes
for each Subscription Object.
d) the "notify-status-code" attribute if the Printer does not
create the Subscription Object or if there are unsupported
attributes from step #2. The possible values of the "notify-
status-code" attribute are shown below (see section 17 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 17.1
for more details about this status code. See step #3 in
this section for the case that causes this error, and the
resulting step #6a) that causes the Printer not to create
the Subscription Object.
'client-error-attributes-or-values-not-supported': the
Subscription Object was not created because the method of
the "notify-pull-method" attribute is not supported. See
section 17.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 SHOULD try
again later. See section 17.3 for more details about this
status code. See steps #6b) and #6c) in this section for
the cases that causes this error.
'successful-ok-too-many-events': the Subscription Object was
created without the "notify-events" values included in this
Subscription Attributes Group because the "notify-events"
attribute contains too many values. See section 17.4 for
more details about this status code. See step #2 in this
section and section 5.3.2 for the cases that cause this
status code.
'successful-ok-ignored-or-substituted-attributes' : the
Subscription Object was created but some supplied
Herriot, et al. Expires May 19, 2002 [page 21]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Subscription Template Attributes are unsupported. These
unsupported attributes are also in the Subscription
Attributes Group. See section 17.5 for more details about
this status code. See step #2 in this section for the cases
that cause this status code.
9.The Printer MUST validate all Subscription Template Attributes and
MUST return all unsupported attributes and values in the
corresponding Subscription Attributes Group of the response (see
step #2) unless it determines that it could not create additional
Subscription Objects because of condition #6b) or condition #6c).
Then, the Printer NEED NOT validate these additional Subscription
Template Attributes and the client MUST NOT expect to find
unsupported attributes from step #2 in such additional
Subscription Attribute Groups.
5.3 Subscription Template Attributes
This section contains the Subscription Template Attributes defined
for the Subscription and Printer objects.
Table 1 below shows the Subscription Template Attributes and has two
columns:
- Attribute in Subscription Object: the name and attribute syntax
of each Subscription Object Attribute that is a Subscription
Template Attribute
- Default and Supported Printer Attributes: the default attribute
and supported Printer attributes that are associated with the
attribute in column 1.
The "notify-recipient-uri" attribute is for use with Push Delivery
Methods. The "notify-pull-method" attribute is for use with Pull
Delivery Methods.
For Push Delivery Methods, a Printer MUST support all attributes in
Table 1 below except for "notify-pull-method" and "notify-attributes"
(and "notify-pull-method-supported" and "notify-attributes-
supported"). For Pull Delivery Methods, a Printer MUST support all
attributes in Table 1 below except for "notify-recipient-uri" and
"notify-attributes" (and "notify-schemes-supported" and "notify-
attributes-supported"). If a Printer supports both Push and Pull
Delivery Methods, then it MUST support both "notify-recipient-uri"
and "notify-pull-method" attributes.
Herriot, et al. Expires May 19, 2002 [page 22]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
For Pull Delivery Methods, a client MUST supply "notify-recipient-
uri" and MAY omit any of the rest of the attributes in column 1 of
Table 1 in a Subscription Creation Request. For Push Delivery
Methods, a client MUST supply "notify-pull-method" and MAY omit any
of the rest of the attributes in column 1 of Table 1 in a
Subscription Creation Request. A client MUST NOT supply both
"notify-recipient-uri" and "notify-pull-method" attributes in the
same Subscription Creation Request.
Note: The Default and Supported Printer attributes listed in column
2 of Table 1 do not have separate sections in this specification
defining their semantics. Instead, the section for the corresponding
Subscription Object attribute (column 1 of Table 1) contains the
semantics of these Printer attributes. This approach follows the
precedence of the Job Template attributes in section 4.2 of [RFC2911]
where the corresponding "xxx-default" and "xxx-supported" Printer
attributes are defined in the same section as the "xxx" Job
attribute.
Herriot, et al. Expires May 19, 2002 [page 23]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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.
Herriot, et al. Expires May 19, 2002 [page 24]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.3.1 notify-recipient-uri (uri) OR notify-pull-method (type2 keyword)
The "notify-recipient-uri" attribute MUST be used for Push Delivery
Methods and the "notify-pull-method" attribute MUST be used for Pull
Delivery Methods.
5.3.1.1 notify-recipient-uri (uri)
This attribute's value is a URL, which is a special case of a URI.
Its value consists of a scheme and an address. The address specifies
the Notification Recipient and the scheme specifies the Push Delivery
Method for each Event Notification associated with this Subscription
Object.
If a Printer supports any Push Delivery Methods, a Printer MUST
support this attribute and return the value as supplied by the client
(no case conversion or other canonicalization) in any operation
response that includes this attribute.
For a Push Delivery Method, a client MUST supply this attribute in a
Subscription Creation Operation. Thus there is no need for a default
Printer attribute.
The URI scheme of the value of this attribute on a Subscription
object MUST be a value of the "notify-schemes-supported (1setOf
uriScheme)" Printer attribute. Note: According to [RFC2396] the ":"
terminates the scheme and so is not part of the scheme. Therefore,
values of the "notify-schemes-supported" Printer attribute do not
include the ":" character.
If the client supplies an unsupported scheme in the value of this
attribute, then the Printer MUST NOT create the Subscription Object
and MUST return the "notify-status-code" attribute with the 'client-
error-uri-scheme-not-supported' value in the Subscription Attributes
Group in the response.
The Printer MUST treat the address part of this attribute as opaque.
5.3.1.2 notify-pull-method (type2 keyword)
This attribute's value is a type2 keyword indicating which Pull
Delivery Method is to be used.
If a Printer supports any Pull Delivery Methods, a Printer MUST
support this attribute and return the value as supplied by the client
in any operation response that includes this attribute.
Herriot, et al. Expires May 19, 2002 [page 25]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
For a Pull Delivery Method, a client MUST supply this attribute in a
Subscription Creation Operation. Thus there is no need for a default
Printer attribute.
The keyword value of this attribute on a Subscription object MUST be
a value of the "notify-pull-method-supported (1setOf type2 keyword)"
Printer attribute.
If the client supplies an unsupported method in the value of this
attribute, then the Printer MUST NOT create the Subscription Object
and MUST return the "notify-status-code" attribute with the 'client-
error-attributes-or-values-not-supported' value in the Subscription
Attributes Group in the response.
5.3.2 notify-events (1setOf type2 keyword)
This attribute contains a set of Subscribed Events. When an Event
occurs and it "matches" a value of this attribute, the Printer sends
an Event Notification using information in the Subscription Object.
The details of "matching" are described subsection 5.3.2.2.
A Printer MUST support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in
Subscription Creation Operation, the Printer MUST populate this
attribute on the Subscription Object with its "notify-events-default"
attribute value.
Each keyword value of this attribute on a Subscription Object MUST be
a value of the "notify-events-supported (1setOf type2 keyword)"
Printer attribute.
The number of values of this attribute MUST NOT exceed the value of
the "notify-max-events-supported" attribute. A Printer MUST support
at least 2 values per Subscription Object. If the number of values
supplied by a client in a Subscription Creation Operation exceeds the
value of this attribute, the Printer MUST treat extra values as
unsupported values and MUST use the value of 'successful-ok-too-many-
events' for the "notify-status-code" attribute in the Subscription
Attributes Group of the response.
5.3.2.1 Standard Values for Subscribed Events
Each value of this attribute is a keyword and it specifies a
Subscribed Event that represents certain changes. Some keywords
Herriot, et al. Expires May 19, 2002 [page 26]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
represent a subset of changes of another keyword, e.g., 'job-
completed' is an Event value which is a sub-value of 'job-state-
change'. See section 5.3.2.2 for the case where this attribute
contains both a value and a sub-value.
The values in this section are divided into three categories: No
Events, Job Events and Printer Events.
A Printer MUST support the Events indicated as "REQUIRED" and MAY
support the Events indicated as "OPTIONAL".
5.3.2.1.1 No Events
The standard and only keyword value for No Events is:
'none': REQUIRED - no Event Notifications for any Events. As the
sole value of "notify-events-supported", this value means that the
Printer does not support the sending of Event Notifications. As
the sole value of "notify-events-default", this value means that a
client MUST specify the "notify-events" attribute in order for a
Subscription Creation Operation to succeed. If the Printer
receives this value as the sole value of a Subscription Creation
Operation, it does not create a Subscription Object. If a Printer
receives this value with other values of a Subscription Creation
Operation, the Printer MUST treat this value as an unsupported
value.
5.3.2.1.2 Subscribed Printer Events
The standard keyword values for Subscribed Printer Events are:
'printer-state-changed': REQUIRED - the Printer changed state from
any state to any other state. Specifically, the value of the
Printer's "printer-state", "printer-state-reasons" or "printer-is-
accepting-jobs" attributes changed.
This Subscribed Event value has the following sub-values:
'printer-restarted' and 'printer-shutdown'. A client can listen
for any of these sub-values if it doesn't want to listen to all
printer-state changes:
'printer-restarted': OPTIONAL - when the printer is powered
up .
'printer-shutdown': OPTIONAL - when the device is being
powered down .
Herriot, et al. Expires May 19, 2002 [page 27]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
'printer-stopped: REQUIRED - when the printer stops printing,
i.e. the value of the "printer-state" Printer attribute
becomes 'stopped'.
'printer-config-changed': OPTIONAL - when the configuration of a
Printer has changed, i.e., the value of the "printer-message-from-
operator" or any "configuration" Printer attribute has changed. A
"configuration" Printer attribute is an attribute which can change
value because of some human interaction either direct or indirect,
and which is not covered by one of the other Events in this
section. Examples of "configuration" Printer attributes are any of
the Job Template attributes, such as "xxx-supported", "xxx-ready"
and "xxx-default". Often, such a change is the result of a client
performing a Set-Printer-Attributes operation (see [ipp-set]) on
the Printer. The client has to perform a Get-Printer-Attributes to
find out the new values of these changed attributes. This Event
is useful for GUI clients and drivers to update the available
printer capabilities to the user.
This Event value has the following sub-values: 'printer-media-
changed' and 'printer-finishings-changed'. A client can listen for
any of these sub-values if it doesn't want to listen to all
printer-configuration changes:
'printer-media-changed': OPTIONAL - when the media loaded on
a printer has been changed, i.e., the "media-ready"
attribute has changed. This Event includes two cases: an
input tray that goes empty and an input tray that receives
additional media of the same type or of a different type.
The client must check the "media-ready" Printer attribute
(see [RFC2911] section 4.2.11) separately to find out what
changed.
'printer-finishings-changed': OPTIONAL - when the finisher on
a printer has been changed, i.e., the "finishings-ready"
attribute has changed. This Event includes two cases: a
finisher that goes empty and a finisher that is refilled
(even if it is not full). The client must check the
"finishings-ready" Printer attribute separately to find out
what changed.
'printer-queue-order-changed': OPTIONAL - the order of jobs in the
Printer's queue has changed, so that an application that is
monitoring the queue can perform a Get-Jobs operation to determine
the new order. This Event does not include when a job enters the
queue (the 'job-created' Event covers that) and does not include
when a job leaves the queue (the 'job-completed' Event covers
that).
Herriot, et al. Expires May 19, 2002 [page 28]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.3.2.1.3 Subscribed Job Events
The standard keyword values for Subscribed Job Events are:
'job-state-changed': REQUIRED - the job has changed from any state
to any other state. Specifically, the Printer sends this Event
whenever the value of the "job-state" attribute or "job-state-
reasons" attribute changes. When a Job is removed from the Job
Retention or Job History phases (see [RFC2911] section 4.3.7.1),
no Event is generated.
This Event value has the following sub-values: 'job-created',
'job-completed' and 'job-stopped'. A client can listen for any of
these sub-values if it doesn't want to listen to all 'job-state
changes'.
'job-created': REQUIRED - the Printer has accepted a Job
Creation operation, a Restart-Job operation [RFC2911], or
any job operation that creates a Job object from an
existing Job object. The Printer sets 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 sends 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'.
'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
Herriot, et al. Expires May 19, 2002 [page 29]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
"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. Often, such a
change is the result of the user or the Operator performing a Set-
Job-Attributes operation (see [ipp-set]) on the Job object. 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 [ipp-prog] specification for additional
attributes that a Printer MAY send in an Event Notification caused
by this Event. The "notify-time-interval" attribute affects this
Event by causing the Printer NOT to send an Event Notification
every time a 'job-progress' Events occurs. See section 5.3.8 for
full details.
5.3.2.2 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.2.2.1 Rules for Matching of Printer Events
Suppose 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 sends 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 send 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).
Herriot, et al. Expires May 19, 2002 [page 30]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.3.2.2.2 Rules for Matching of Job Events
Suppose that Job J causes Job Event E to occur.
1.For each Per-Printer Subscription S in the Printer, if E equals
a value of this attribute in S or E is a sub-value of a value of
this attribute in S, the Printer MUST generate an Event
Notification.
2.For each Per-Job Subscription S associated with Job J, if E
equals a value of this attribute in S or E is a sub-value of a
value of this attribute in S, the Printer MUST generate an Event
Notification.
3.For each Per-Job Subscription S that is NOT associated Job J, if
E equals a value of this attribute in S or E is a sub-value of a
value of this attribute in, the Printer MUST NOT generate an
Event Notification from S.
Consider the example: There are three Subscription Objects listening
for the Job Event 'job-completed'. Subscription Object A is a Per-
Printer Subscription Object. Subscription Object B is a Per-Job
Subscription Object for Job 1, and Subscription Object C is a Per-Job
Subscription Object for Job 2. In addition, Per-Printer Subscription
Object D is listening for the Job Event 'job-state-changed'. When Job
1 completes, the Printer sends 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 sends 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 send 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.2.2.3 Special Cases for Matching Rules
This section contains rule for special cases.
If an Event matches Subscribed Events in two different Subscription
Objects and the Printer would send two identical Event Notifications
(except for the "notify-subscription-id" attribute) to the same
Notification Recipient using the same Delivery Method, the Printer
MUST send both Event Notifications. That is, the Printer MUST NOT try
to consolidate seemingly identical Event Notifications that occur in
Herriot, et al. Expires May 19, 2002 [page 31]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
separate Subscription objects. Incidentally, the Printer MUST NOT
reject Subscription Creation Operations that would create this
scenario.
If an Event matches two values of this "notify-events" attribute in a
single Subscription object (e.g., a value and its sub-value), a
Printer MAY send one Event Notification for each matched value in the
Subscription Object or it MAY send only one Event Notification per
Subscription Object. The rules in sections 5.3.2.2.1 and 5.3.2.2.2
are purposefully ambiguous about the number of Event Notification
sent when Event E matches two or more values in a Subscription
Object.
Consider the example: There are two Per-Printer Subscription Objects
when a Job completes. Subscription Object A has the Subscribed Job
Event 'job-state-changed'. Subscription Object B has the Subscribed
Job Events 'job-state-changed' and 'job-completed'. The Printer sends
an Event Notification to the Notification Recipient of Subscription
Object A with the value of 'job-state-changed' for the "notify-
subscribing-event" attribute. The Printer sends either one or two
Event Notifications to the Notification Recipient of Subscription
Object B, depending on implementation. If it sends two Event
Notifications, one has the value of 'job-state-changed' for the
"notify-subscribing-event" attribute, and the other has the value of
'job-completed' for the "notify-subscribing-event" attribute. If it
sends one Event Notification, it has the value of either 'job-state-
changed' or 'job-completed' for the "notify-subscribing-event"
attribute, depending on implementation. The algorithm for choosing
such a value is implementation dependent.
5.3.3 notify-attributes (1setOf type2 keyword)
This attribute contains a set of attribute names. When a Printer
sends a Machine Consumable Event Notification, it includes a fixed
set of attributes (see section 9.1). If this attribute is present
and the Event Notification is Machine Consumable, the Printer also
includes the attributes specified by this attribute.
A Printer MAY support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in
Subscription Creation Operation or the Printer does not support this
attribute, the Subscription Object either (1) MAY contain the
"notify-attributes" attribute with a 'none' value or (2) NEED NOT
contain the attribute at all. There is no "notify-attributes-
default" Printer attribute.
Herriot, et al. Expires May 19, 2002 [page 32]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Each keyword value of this attribute on a Subscription Object MUST be
a value of the "notify-attributes-supported (1setOf type2 keyword)"
Printer attribute. The "notify-attributes-supported" MAY contain any
Printer attribute, Job attribute or Subscription Object attribute
that the Printer supports in an Event Notification. It MUST NOT
contain any of the attributes in Section 9.1 that a Printer
automatically puts in an Event Notification; it would be redundant.
If a client supplies an attribute in Section 9.1, the Printer MUST
treat it as an unsupported attribute value of the "notify-attributes"
attribute.
The following rules apply to each keyword value N of the "notify-
attributes" attribute: If the value N names:
a)a Subscription attribute, the Printer MUST use the attribute N in
the Subscription Object that is being used to generate the Event
Notification.
b)a Job attribute and the Printer is generating an Event
Notification from a Per-Job Subscription Object S, the Printer
MUST use the attribute N in the Job object associated with S.
c)a Job attribute and the Printer is generating an Event
Notification from a Per-Printer Subscription Object and the Event
is:
? a Job Event, the Printer MUST use the attribute N in the Job
object that caused the Event.
? a Printer Event, the Printer MUST use the attribute N in the
active Job.
If a Printer supports this attribute and a Subscription Object
contains this attribute and the Delivery Method generates a Machine
Consumable Event Notification, the Printer MUST include in each Event
Notification:
a)the attributes specified in section 9.1 and
b)each attribute named by this attribute.
The Printer MUST NOT use this attribute to generate a Human
Consumable Event Notification.
Herriot, et al. Expires May 19, 2002 [page 33]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.3.4 notify-user-data (octetString(63))
This attribute contains opaque data that some Delivery Methods
include in each Machine Consumable Event Notification. The opaque
data might contain, for example:
- the identity of the Subscriber
- a path or index to some Subscriber information
- a key that identifies to the Notification Recipient the
ultimate recipient of the Event Notification
- the id for a Notification Recipient that had previously
registered with an Instant Messaging Service
A Printer MUST support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in the
Subscription Creation Operation, the Subscription Object either (1)
MAY contain the "notify-user-data" attribute with a zero length value
or (2) NEED NOT contain the attribute at all. There is no "notify-
user-data-default" Printer attribute.
There is no "notify-user-data-supported" Printer attribute. Rather,
any octetString whose length does not exceed 63 octets is a supported
value. If the length exceeds 63 octets, the Printer MUST treat it as
an unsupported value.
5.3.5 notify-charset (charset)
This attribute specifies the charset to be used in the Event
Notification content sent to the Notification Recipient, whether the
Event Notification content is Machine Consumable or Human Consumable.
A Printer MUST support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in
Subscription Creation Operation or supplies an unsupported value, the
Printer MUST populate this attribute in the Subscription Object with
the value of the "attributes-charset" operation attribute, which is a
REQUIRED attribute in all IPP requests (see [RFC2911]). If the value
of the "attributes-charset" attribute is unsupported, the Printer
MUST populate this attribute in the Subscription Object with the
Herriot, et al. Expires May 19, 2002 [page 34]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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.6 notify-natural-language (naturalLanguage)
This attribute specifies the natural language to be used in any human
consumable text in the Event Notification content sent to the
Notification Recipient, whether the Event Notification content is
Machine Consumable or Human Consumable.
A Printer MUST support this attribute.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in
Subscription Creation Operation or supplies an unsupported value, the
Printer MUST populate this attribute in the Subscription Object with
the value of the "attributes-natural-language" operation attribute,
which is a REQUIRED attribute in all IPP requests (see [RFC2911]). 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. 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.
5.3.7 notify-lease-duration (integer(0:67108863))
This attribute specifies the duration of the lease (in seconds)
associated with the Per-Printer Subscription Object at the time the
Subscription Object was created or the lease was renewed. The
duration of the lease is infinite if the value is 0, i.e., the lease
never expires. See section 5.4.3 on "notify-lease-expiration-time
(integer(0:MAX))" for more details.
This attribute is not present on a Per-Job Subscription Object
because the Subscription Object lasts exactly as long as the
associated Job object. See discussion of the 'job-completed' event
in section 5.3.2.1.3 about retention of the Job object after
completion.
Herriot, et al. Expires May 19, 2002 [page 35]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
A Printer MUST support this attribute.
For a Subscription Object Creation operation of a Per-Job
Subscription Object, the client MUST NOT supply this attribute. If
the client does supply this attribute, the Printer MUST treat it as
an unsupported attribute.
For a Subscription Creation Operation of a Per-Printer Subscription
Object or a Renew-Subscription operation, a client MAY supply this
attribute. If the client does not supply this attribute, the Printer
MUST populate this attribute with its "notify-lease-duration-default"
(0:67108863) attribute value. If the client supplies this attribute
with an unsupported value, the Printer MUST populate this attribute
with a supported value, and this value SHOULD be as close as possible
to the value requested by the client. Note: this rule implies that a
Printer doesn't assign the value of 0 (infinite) unless the client
requests it.
After the Printer has populated this attribute with a supported
value, the value represents the "granted duration" of the lease in
seconds and the Printer sets the value of the Subscription Object's
"notify-lease-expiration-time" attribute as specified in section
5.4.3.
The value of this attribute on a Subscription Object MUST be a value
of the "notify-lease-duration-supported" (1setOf (integer(0:67108863)
| rangeOfInteger(0:67108863))) Printer attribute.
A Printer MAY require authentication in order to return the value of
0 (the lease never expires) as one of the values of "notify-lease-
duration-supported", and to allow 0 as a value of the "notify-lease-
duration" attribute.
Note: The maximum value 67,108,863 is 2 raised to the 26 power minus
1 and is about 2 years in seconds. The value is considerably less
than MAX so that there is virtually no chance of an overflow when it
is added to "printer-up-time" to produce "notify-lease-expiration-
time".
5.3.8 notify-time-interval (integer(0:MAX))
The 'job-progress' Event occurs each time that a Printer completes a
sheet. Some Notification Recipients do not want to receive an Event
Notification every time this Event occurs. This attribute allows a
Subscribing Client to request how often it wants to receive Event
Notifications for 'job-progress' Events. The value of this attribute
Herriot, et al. Expires May 19, 2002 [page 36]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
MAY be any nonnegative integer (0,MAX) indicating the minimum number
of seconds between 'job-progress' Event Notifications.
The Printer MUST support this attribute if and only if the Printer
supports the 'job-progress' Event.
A client MAY supply this attribute in a Subscription Creation
Operation. If the client does not supply this attribute in the
Subscription Creation Operation, the Subscription Object either (1)
MAY contain the "notify-time-interval" attribute with a '0' value or
(2) NEED NOT contain this attribute at all. There is no "notify-
time-interval-default" Printer attribute.
There is no "notify-time-interval-supported" Printer attribute.
If the 'job-progress' Event occurs and a Subscription Object contains
the 'job-progress' Event as a value of the 'notify-events' attribute,
there are two cases to consider:
1.This attribute is not present on the Subscription Object or has
the value of 0. The Printer MUST generate and send an Event
Notification (as is the case with other Events).
2.This attribute is present with a nonzero value of N:
a)If the Printer has not sent an Event Notification for the 'job-
progress' Event for the associated Subscription Object within
the past N seconds, the Printer MUST send an Event Notification
for the Event that just occurred. Note when the Printer
completes the first page of a Job, this rule implies that the
Printer sends an Event Notification for a Per-Job Subscription
Object.
b)Otherwise, the Printer MUST NOT generate or send an Event
Notification for the associated Subscription Object. The Printer
MUST NOT increase the value of the "notify-sequence-number"
Subscription Object attribute (i.e., the sequence of values of
the "notify-sequence-number" attribute counts the Event
Notifications that the Printer sent and not the Events that do
not cause an Event Notification to be sent).
It is RECOMMENDED that a Subscribing Client use this attribute when
it subscribes to the 'job-progress' Event, and that the value be
sufficiently large to limit the frequency with which the Printer
sends Event Notifications requests.
This attribute MUST NOT effect any Events other than 'job-progress'.
Herriot, et al. Expires May 19, 2002 [page 37]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.4 Subscription Description Attributes
Subscription Description Attributes are those attributes that a
Printer adds to a Subscription Object at the time of its creation.
A Printer MUST support all attributes in this Table 2.
A client MUST NOT supply the attributes in Table 2 in a Subscription
Template Attributes Group of a Subscription Creation Operation. If
the client supplies them, the Printer MUST NOT set them and MUST
treat them as unsupported attributes. There are no corresponding
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 identifies a Subscription Object instance with a
number that is unique within the context of the Printer. The Printer
generates this value at the time it creates the Subscription Object.
A Printer MUST support this attribute.
The Printer MAY assign the value of this attribute sequentially as it
creates Subscription Objects. However, if there is no security on
Herriot, et al. Expires May 19, 2002 [page 38]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Subscription objects, sequential assignment exposes the system to a
passive traffic monitoring threat.
The Printer SHOULD avoid re-using recent values of this attribute
during continuous operation of the Printer as well as across power
cycles. Then a Subscribing Client is unlikely to find that a stale
reference accesses a new Subscription Object.
The 0 value is not permitted in order to allow for compatibility with
"job-id" and with SNMP index values, which also cannot be 0.
5.4.2 notify-sequence-number (integer (0:MAX))
The value of this attribute indicates the number of times that the
Printer has generated and attempted to send an Event Notification for
this Subscription object. When an Event Notification contains this
attribute, the Notification Recipient can determine whether it missed
some Event Notifications (i.e., numbers skipped) or received
duplicates (i.e., same number twice).
A Printer MUST support this attribute.
When the Printer creates a Subscription Object, it MUST set the value
of this attribute to 0. This value indicates that the Printer has not
sent any Event Notifications for this Subscription Object.
Each time the Printer sends a newly generated Event Notification, it
MUST increase the value of this attribute by 1. For some Delivery
Methods, the Printer MUST include this attribute in each Event
Notification, and the value MUST be the value after it is increased
by 1. That is, the value of this attribute in the first Event
Notification after Subscription object creation MUST be 1, the second
MUST be 2, etc. If a Delivery Method is defined such that the
Notification Recipient returns a response, the Printer can re-try
sending an Event Notification a certain number of times with the same
sequence number when the Notification Recipient fails to return a
response.
If a Subscription Object lasts long enough to reach the value of MAX,
its next value MUST be 0, i.e., it wraps.
5.4.3 notify-lease-expiration-time (integer(0:MAX))
This attribute specifies the time in the future when the lease on the
Per-Printer Subscription Object will expire, i.e. the "printer-up-
Herriot, et al. Expires May 19, 2002 [page 39]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
time" value at which the lease will expire. If the value is 0, the
lease never expires.
A Printer MUST support this attribute.
When the Printer creates a Per-Job Subscription Object, this
attribute MUST NOT be present - the Subscription Object lasts exactly
as long as the associated Job object. See also the discussion of the
'job-completed' event in section 5.3.2.1.3 about retention of the Job
object after completion so that a Notification Recipient can query
the Job object after receiving the 'job-completed' Event
Notification.
When the Printer creates a Per-Printer Subscription Object, it
populates this attribute with a value that is the sum of the values
of the Printer's "printer-up-time" attribute and the Subscription
Object's "notify-lease-duration" attribute with the following
exception. If the value of the Subscription Object's "notify-lease-
duration" attribute is 0 (i.e., no expiration time), then the value
of this attribute MUST be set to 0 (i.e., no expiration time).
When the Printer powers up, it MUST set the value of this attribute
in each persistent Subscription Object using the algorithm in the
previous paragraph.
When the "printer-up-time" equals the value of this attribute, the
Printer MUST delete the Subscription Object. A client can extend a
lease of a Per-Printer Subscription Object with the Renew-
Subscription operation (see section 11.2.6).
Note: In order to compute the number of seconds remaining in a lease
for a Per-Printer Subscription Object, a client can subtract the
Subscription's "notify-printer-up-time" attribute (see section 5.4.4)
from the Subscription's "notify-lease-expiration-time" attribute.
5.4.4 notify-printer-up-time (integer(1:MAX))
This attribute is an alias for the Printer's "printer-up-time"
attribute " (see [RFC2911] section 4.4.29). In other words, when
this attribute is queried with the Get-Subscriptions or Get-
Subscription-Attributes operations (see sections 11.2.4 and 11.2.5),
the value returned is the current value of the Printer's "printer-up-
time" attribute, rather than the time at which the Subscription
Object was created.
A Printer MUST support this attribute.
Herriot, et al. Expires May 19, 2002 [page 40]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
When the Printer creates a Per-Job Subscription Object, this
attribute MUST NOT be present. When the Printer creates a Per-Printer
Subscription Object, this attribute MUST be present.
Note: this attribute exists in a Per-Printer Subscription Object so
that a client using the Get-Subscription-Attributes or Get-
Subscription operations can convert the Per-Printer Subscription's
"notify-lease-expiration-time" attribute to wall clock time with one
request. If the value of the "notify-lease-expiration-time" attribute
is not 0 (i.e., no expiration time), then the difference between the
"notify-lease-expiration-time" attribute and the "notify-printer-up-
time" is the remaining number of seconds on the lease from the
current time.
5.4.5 notify-printer-uri (uri)
This attribute identifies the Printer object that created this
Subscription Object.
A Printer MUST support this attribute.
During a Subscription Creation Operation, the Printer MUST populate
this attribute with the value of the "printer-uri" operation
attribute in the request. From the Printer URI, the client can, for
example, determine what security scheme was used.
5.4.6 notify-job-id (integer(1:MAX))
This attribute specifies whether the containing Subscription Object
is a Per-Job or Per-Printer Subscription Object, and for Per-Job
Subscription Objects, it specifies the associated Job.
A Printer MUST support this attribute.
If this attribute is not present, the Subscription Object MUST be a
Per-Printer Subscription. If this attribute is present, the
Subscription Object MUST be a Per-Job Subscription Object and this
attribute MUST identify the Job with which the Subscription Object is
associated.
Note: This attribute could be useful to a Notification Recipient that
receives an Event Notification generated from a Per-Job Subscription
Object and caused by a Printer Event. The Event Notification gives
access to the Printer and the Subscription Object. The Event
Notification gives access to the associated Job only via this
attribute. See discussion of the 'job-completed' event in section
Herriot, et al. Expires May 19, 2002 [page 41]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
5.3.2.1.3 about retention of the Job object after completion so that
a Notification Recipient can query the Job object after receiving the
'job-completed' Event Notification.
5.4.7 notify-subscriber-user-name (name(MAX))
This attribute contains the name of the user who performed the
Subscription Creation Operation.
A Printer MUST support this attribute.
The Printer sets this attribute to the most authenticated printable
name that it can obtain from the authentication service over which
the Subscription Creation Operation was received. The Printer uses
the same mechanism for determining the value of this attribute as it
does for a Job's "job-originating-user-name" (see [RFC2911] section
4.3.6).
Note: To help with authentication, a Subscription Object may have
additional private attributes about the user, e.g., a credential of a
principal. Such private attributes are implementation-dependent and
not defined in this document.
6 Printer Description Attributes Related to Notification
This section defines the Printer Description attributes that are
related to Notification. Table 3 lists the Printer Description
attributes, indicates the Printer support required for conformance,
and whether or not the attribute is READ-ONLY (see section 3.1):
Table 3 - Printer Description Attributes Associated with Notification
Printer object attributes: REQUIRED READ-ONLY
printer-state-change-time (integer(1:MAX)) No Yes
printer-state-change-date-time (dateTime) No Yes
Herriot, et al. Expires May 19, 2002 [page 42]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
6.1 printer-state-change-time (integer(1:MAX))
This OPTIONAL attribute records the most recent time at which the
'printer-state-changed' Printer Event occurred whether or not any
Subscription objects were listening for this event. This attribute
helps a client or operator to determine how long the Printer has been
in its current state.
A Printer MAY support this attribute and if so, the attribute MUST be
READ-ONLY.
On power-up, the Printer MUST set the value of this attribute to be
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 set this attribute to the value of the Printer's
"printer-up-time" attribute.
6.2 printer-state-change-date-time (dateTime)
This OPTIONAL attribute records the most recent time at which the
'printer-state-changed' Printer Event occurred whether or not there
were any Subscription Objects listening for this event. This
attribute helps a client or operator to determine how long the
Printer has been in its current state.
A Printer MAY support this attribute and if so, the attribute MUST be
READ-ONLY.
On power-up, the Printer MUST set the value of this attribute to be
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 set this attribute to the value of the Printer's
"printer-current-time" attribute.
7 New Values for Existing Printer Description Attributes
This section contains those attributes for which additional values
are added.
7.1 operations-supported (1setOf type2 enum)
The following "operation-id" values are added in order to support the
new operations defined in this document:
Herriot, et al. Expires May 19, 2002 [page 43]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 4 - Operation-id assignments
Value Operation Name
0x0016 Create-Printer-Subscriptions
0x0017 Create-Job-Subscriptions
0x0018 Get-Subscription-Attributes
0x0019 Get-Subscriptions
0x001A Renew-Subscription
0x001B Cancel-Subscription
8 Attributes Only in Event Notifications
This section contains those attributes that exist only in Event
Notifications and do not exist in any objects.
8.1 notify-subscribed-event (type2 keyword)
This attribute indicates the Subscribed Event that caused the Printer
to send this Event Notification. This attribute exists only in Event
Notifications.
This attribute MUST contain one of the values of the "notify-events"
attribute in the Subscription Object, i.e., one of the Subscribed
Event values. Its value is the Subscribed Event that "matches" the
Event that caused the Printer to send 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 send an Event Notification for
either the 'job-completed' or 'job-state-changed' Subscribed Events
and to send the 'job-completed' or 'job-state-changed' value for this
attribute, respectively,. See section 5.3.2.2 for the "matching"
rules of Subscribed Events and for additional examples.
The Delivery Method Document specifies whether the Printer includes
the value of this attribute in an Event Notification.
Herriot, et al. Expires May 19, 2002 [page 44]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
8.2 notify-text (text(MAX))
This attribute contains a Human Consumable text message (see section
9.2). This message describes the Event and is encoded as plain text,
i.e., 'text/plain' with the charset specified by Subscription
Object's "notify-charset" attribute.
The Delivery Method Document specifies whether the Printer includes
this attribute in an Event Notification.
9 Event Notification Content
This section defines the Event Notification content that the Printer
sends when an Event occurs.
When an Event occurs, the Printer MUST find each Subscription object
whose "notify-events" attribute "matches" the Event. See section
5.3.2.2 for details on "matching". For each matched Subscription
Object, the Printer MUST create an Event Notification with the
content and format that the Delivery Method Document specifies. The
content contains the value of attributes specified by the Delivery
Method Document. The Printer obtains the values immediately after the
Event occurs. For example, if the "printer-state" attribute changes
from 'idle' to 'processing', the Event 'printer-state-changed' occurs
and the Printer puts various attributes into the Event Notification,
including "printer-up-time" and "printer-state" with the values that
they have immediately after the Event occurs, i.e., the value of
"printer-state" is 'processing'.
Event Notification Ordering:
When a Printer sends Event Notifications, the Event Notifications
from any given Subscription Object MUST be in time stamp order, i.e.,
in order of increasing "printer-up-time" attribute value in the Event
Notification (see Table 5). These Event Notifications MAY be
interleaved with those from other Subscription Objects, as long as
those others are also in time stamp order. The Printer MUST observe
these ordering requirements whether sending multiple pending Events
as multiple separate Event Notifications or together in a single
Compound Event Notification.
If a Subscribing Client wants the Printer to send certain Event
Notifications in time stamp order, the Subscribing Client uses a
single Subscription Object. Even so, depending on the underlying
transport, the actual order that a Notification Recipient receives
separate Event Notifications may differ from the order sent by the
Printer (e.g., email).
Herriot, et al. Expires May 19, 2002 [page 45]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Example: Consider two Per-Printer Subscription Objects: SO1 and SO2.
SO1 requests 'job-state-changed' events and SO2 requests 'printer-
state-changed' events. The number in parens is the time stamp. The
following Event Notification sequences are the only ones that conform
to the ordering requirements for the Printer to send the Event
Notifications:
(a) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO1: 'job-
completed' (1009), SO2: 'printer-stopped' (1005)
(b) SO1: 'job-created' (1000), SO1: 'job-stopped' (1005), SO2:
'printer-stopped' (1005), SO1: 'job-completed' (1009)
(c) SO1: 'job-created' (1000), SO2: 'printer-stopped' (1005), SO1:
'job-stopped' (1005), SO1: 'job-completed' (1009)
(d) SO2: 'printer-stopped (1005), SO1: 'job-created' (1000), SO1:
'job-stopped' (1005), SO1: 'job-completed' (1009)
Examples (b) and (c) are interleaved; examples (a) and (d) are not
interleaved and are not appropriate for some Delivery Methods.
If two different Events occur simultaneously, or nearly so (e.g.,
"printer-up-time" has the same value for both), the Printer MUST
create a separate Event Notification for each Event, even if the
associated Subscription Object is the same for both Events. However,
the Printer MAY combine these distinct Event Notifications into a
single Compound Event Notification if the Delivery Method supports
Compound Event Notifications. For example, suppose that two nearly-
simultaneously Events represent two successive 'printer-state-
changed' Events, one from 'idle' to 'processing' and another from
'processing' to 'stopped'. These two Events have the same name but
are different instances of the Event. Then the Printer MUST create a
separate Event Notification for each Event and SHOULD accurately
report the "printer-state" of the first Event as 'processing' and the
second Event as 'stopped'.
If a Subscription Object contains more than one Subscribed Event, and
several Events occur in quick succession each matching a different
Subscribed Event in the Subscription Object, the Printer MUST NOT
generate a single Event Notification from several of these Events,
but MAY combine distinct Event Notifications into a single Compound
Event Notification if the Delivery Method supports Compound Event
Notifications.
After the Printer has created the Event Notification, the Printer
delivers it via either a:
Herriot, et al. Expires May 19, 2002 [page 46]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Push Delivery Method: The Printer sends the Event Notification
shortly after an Event occurs. For some Push Delivery Methods,
the Notification Recipient MUST send a response; for others it
MUST NOT send a response.
Pull Delivery Method: The Printer saves Event Notifications for
some Event Life and expects the Notification Recipient to
request Event Notifications. The Printer returns the Event
Notifications in a response to such a request.
If an error that meets the following conditions occurs, the Printer
MUST cancel the Subscription Object.
a)the error occurs during the sending of an Event Notification
generated from Subscription Object S AND
b)the error would continue to occur every time the Printer sends an
Event Notification generated from Subscription Object S in the
future.
For example, if the address of the "notify-recipient-uri" of
Subscription Object A references a non-existent target and the
Printer determines this fact, it MUST delete Subscription Object A.
The next two sections describe the values that a Printer sends in the
content of Machine Consumable and Human Consumable Event
Notifications, respectively.
The tables in the sub-sections of this section contain the following
columns:
a)Source Value: the name of the attribute that supplies the value
for the Event Notification. Asterisks in this field refer to a
note below the table.
b)Sends: if the Printer supports the value (column 1) on the
Source Object (column 3) the Delivery Method MUST specify:
MUST: that the Printer MUST send the value.
SHOULD: either that the Printer MUST send the value or that
the value is incompatible with the Delivery Method.
MAY: that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT,
or NEED NOT send the value. The Delivery Method specifies the
level of conformance for the Printer.
Herriot, et al. Expires May 19, 2002 [page 47]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
c)Source Object: the object from which the source value comes. If
the object is "Event Notification", the Printer fabricates the
value when it sends the Event Notification. See section 8.
9.1 Content of Machine Consumable Event Notifications
This section defines the attributes that a Delivery Method MUST
mention in a Delivery Method Document when specifying the Machine
Consumable Event Notification's contents.
This document does not define the order of attributes in Event
Notifications. However, Delivery Method Documents MAY define the
order of some or all of the attributes.
A Delivery Method Document MUST specify additional attributes (if
any) that a Printer implementation sends in a Machine Consumable
Event Notification.
Notification Recipients MUST be able to accept Event Notifications
containing attributes they do not recognize. What a Notification
Recipient does with an unrecognized attribute is implementation-
dependent. Notification Recipients MAY attempt to display
unrecognized attributes anyway or MAY ignore them.
The next three sections define the attributes in Event Notification
Contents that are:
1.for all Events
2.for Job Events only
3.for Printer Events only
9.1.1 Event Notification Content Common to All Events
This section lists the attributes that a Delivery Method Document
MUST specify for all Events.
Table 5 lists potential values in each Event Notification.
Herriot, et al. Expires May 19, 2002 [page 48]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 5 - Attributes in Event Notification Content
Source Value Sends 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 send 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
send the "notify-user-data" source value in the Event Notification,
the Printer MUST send an octet-string of length 0.
*** The last three rows represent additional attributes that a client
MAY request via the "notify-attributes" attribute. A Printer MAY
Herriot, et al. Expires May 19, 2002 [page 49]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
support the "notify-attributes" attribute. The Delivery Method MUST
say that the Printer MUST, SHOULD, MAY, MUST NOT, SHOULD NOT, or NEED
NOT support the "notify-attributes" attribute and specific values of
this attribute. The Delivery Method MAY say that support for the
"notify-attributes" is conditioned on support of the attribute by the
Printer or it MAY say that Printer MUST support the "notify-
attributes" attribute if the Printer supports the Delivery Method.
9.1.2 Additional Event Notification Content for Job Events
This section lists the additional attributes that a Delivery Method
Document MUST specify for Job Events. See Table 6.
Table 6 - Additional Event Notification Content for Job Events
Source Value Sends 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 send the "job-impressions-completed" attribute in
an Event Notification only for the combinations of Events and
Subscribed Events shown in Table 7.
Herriot, et al. Expires May 19, 2002 [page 50]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 7 - Combinations of Events and Subscribed Events for "job-
impressions-completed"
Job Event Subscribed Job Event
'job-progress' 'job-progress'
'job-completed' 'job-completed'
'job-completed' 'job-state-changed'
9.1.3 Additional Event Notification Content for Printer Events
This section lists the additional attributes that a Delivery Method
Document MUST specify for Printer Events. See Table 8.
Table 8 - Additional Event Notification Content for Printer Events
Source Value Sends Source Object
printer-state (type1 enum) MUST Printer
printer-state-reasons (1setOf type2 keyword) MUST Printer
printer-is-accepting-jobs (boolean) MUST Printer
9.2 Content of Human Consumable Event Notification
This section defines the information that a Delivery Method MUST
mention in a Delivery Method Document when specifying the Human
Consumable Event Notifications contents or the value of the "notify-
text" attribute.
Such a Delivery Method MUST specify the following information and a
Printer SHOULD send it:
a)the Printer name (see Table 9)
Herriot, et al. Expires May 19, 2002 [page 51]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
b)the time of the Event (see Table 11)
c)for Printer Events only:
i) the Event (see Table 10) and/or Printer state information
(see Table 14)
d)for Job Events only:
i) the job identity (see Table 12)
ii) the Event (see Table 10) and/or Job state information (see
Table 13)
The subsections of this section specify the attributes that a Printer
MUST use to obtain this information.
A Delivery Method Document MUST specify additional information (if
any) that a Printer implementation sends in a Human Consumable Event
Notification or in the "notify-text" attribute.
A client MUST NOT request additional attributes via the "notify-
attributes" attribute because this attribute works only for Machine
Consumable Event Notifications.
Notification Recipients MUST NOT expect to be able to parse the Human
Consumable Event Notification contents or the value of the "notify-
text" attribute.
The next three sections define the attributes in Event Notification
Contents that are:
a) for all Events
b) for Job Events only
c) for Printer Events only
9.2.1 Event Notification Content Common to All Events
This section lists the source of the information that a Delivery
Method MUST specify for all Events.
There is a separate table for each piece of information. Each row in
the table represents a source value for the information and the
values are listed in order of preference, with the first one being
the preferred one. An implementation SHOULD use the source value from
the earliest row in each table. It MAY use the source value from
another row instead, or it MAY combine the source values from several
rows. An implementation is free to determine the best way to present
this information.
In all tables of this section, all rows contain a "MAY" in order to
state that the Delivery Method specifies the conformance.
Herriot, et al. Expires May 19, 2002 [page 52]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 9 lists the source of the information for the Printer Name. The
"printer-name" is more user-friendly unless the Notification
Recipient is in a place where the Printer name is not meaningful. For
example, an implementation could have the intelligence to send the
value of the "printer-name" attribute to a Notification Recipient
that can access the Printer via value of the "printer-name" attribute
and otherwise send the value of the "notify-printer-uri" attribute.
Table 9 - Printer Name in Event Notification Content
Source Value Sends Source Object
printer-name (name(127)) MAY Printer
notify-printer-uri (uri) MAY Subscription
Table 10 lists the source of the information for the Event name. A
Printer MAY combine this information with state information described
for Jobs in Table 13 or for Printers in Table 14.
Table 10 - Event Name in Event Notification Content
Source Value Sends Source Object
notify-subscribed-event (type2 keyword) MAY Subscription
Table 11 lists the source of the information for the time that the
Event occurred. A Printer can send this value only if it supports the
Printer's "printer-current-time" attribute. If a Printer does not
support the "printer-current-time" attribute, it MUST NOT send the
"printer-up-time" value instead, since it is not an allowed option
for human consumable information.
Herriot, et al. Expires May 19, 2002 [page 53]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 11 - Event Time in Event Notification Content
Source Value Sends Source Object
printer-current-time (dateTime) MAY Printer
9.2.2 Additional Event Notification Content for Job Events
This section lists the source of the additional information that a
Delivery Method MUST specify for Job Events.
Table 12 lists the source of the information for the job name. The
"job-name" is likely more meaningful to a user than "job-id".
Table 12 - Job Name in Event Notification Content
Source Value Sends Source Object
job-name (name(MAX)) MAY Job
job-id (integer(1:MAX)) MAY Job
Table 13 lists the source of the information for the job state. If a
Printer supports the "job-state-message" and "job-detailed-state-
message" attributes, it SHOULD use those attributes for the job state
information, otherwise, it should fabricate such information from the
"job-state" and "job-state-reasons". For some Events, a Printer MAY
combine this information with Event information.
Herriot, et al. Expires May 19, 2002 [page 54]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 13 - Job State in Event Notification Content
Source Value Sends Source
Object
job-state-message (text(MAX)) MAY Job
job-detailed-status-messages (1setOf text(MAX)) MAY Job
job-state (type1 enum) MAY Job
job-state-reasons (1setOf type2 keyword) MAY Job
9.2.3 Additional Event Notification Content for Printer Events
This section lists the source of the additional information that a
Delivery Method MUST specify for Printer Events.
Table 14 lists the source of the information for the printer state.
If a Printer supports the "printer-state-message", it SHOULD use that
attribute for the job state information, otherwise it SHOULD
fabricate such information from the "printer-state" and "printer-
state-reasons". For some Events, a Printer MAY combine this
information with Event information.
Herriot, et al. Expires May 19, 2002 [page 55]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Table 14 - Printer State in Event Notification Content
Source Value Sends Source
Object
printer-state-message (text(MAX)) MAY Printer
printer-state (type1 enum) MAY Printer
printer-state-reasons (1setOf type2 keyword) MAY Printer
printer-is-accepting-jobs (boolean) MAY Printer
10 Delivery Methods
A Delivery Method is the mechanism, i.e., protocol, by which the
Printer delivers an Event Notification to a Notification Recipient.
There are several potential Delivery Methods for Event Notifications,
standardized, as well as proprietary. This document does not define
any of these delivery mechanisms. Each Delivery Method MUST be
defined in a Delivery Method Document that is separate from this
document. New Delivery Methods will be created as needed using an
extension to the registration procedures defined in [RFC2911]. Such
documents are registered with IANA (see section 13.7.3).
The following sorts of Delivery Methods are expected:
- The Notification Recipient polls for Event Notifications at
intervals directed by the Printer
- The Printer sends Event Notifications to the Notification
Recipient using http as the transport.
- The Printer sends an email message.
This section specifies how to define a Delivery Method Document and
what to put in such a document.
A Delivery Method Document MUST contain an exact copy of the
following paragraph, caption and table. In addition, column 2 of the
table in the Delivery Method Document MUST contain answers to
questions in column 1 for the Delivery Method. Also, the Delivery
Method document MUST contain a reference to this document and call
that reference [ipp-ntfy] because the table contains an [ipp-ntfy]
reference.
Herriot, et al. Expires May 19, 2002 [page 56]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
If a Printer supports this Delivery Method, the following are its
characteristics.
Table 15 - Information about the Delivery Method
Document Method Conformance Requirement Delivery Method
Realization
1.What is the URL scheme name for the Push
Delivery Method or the keyword method
name for the Pull Delivery Method?
2.Is the Delivery Method REQUIRED,
RECOMMENDED, or OPTIONAL for an IPP
Printer to support?
3.What transport and delivery protocols
does the Printer use to deliver the
Event Notification Content, i.e., what
is the entire network stack?
4.Can several Event Notifications be
combined into a Compound Event
Notification?
5.Is the Delivery Method initiated by the
Notification Recipient (pull), or by the
Printer (push)?
6.Is the Event Notification content
Machine Consumable or Human Consumable?
7.What section in this document answers
the following question? For a Machine
Consumable Event Notification, what is
the representation and encoding of
values defined in section 9.1 of [ipp-
ntfy] 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 [ipp-ntfy] and
the conformance requirements thereof?
Herriot, et al. Expires May 19, 2002 [page 57]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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
sends in an Event Notification content
and the conformance requirements
thereof?
12. What are the additional Subscription
Template and/or Subscription Description
attributes and the conformance
requirements thereof?
13. What are the additional Printer
Description attributes and the
conformance requirements thereof?
11 Operations for Notification
This section defines all of the operations for Notification. Section
7.1 assigns the "operation-id" for each operation. The following two
sub-sections define Subscription Creation Operations, and other
operations.
11.1 Subscription Creation Operations
This section defines the Subscription Creation Operations. The first
section on Create-Job-Subscriptions gives most of the information.
The other Subscription Creation Operations refer to the section on
Create-Job-Subscriptions, even though the Create-Job-Subscriptions
operation is the only OPTIONAL operation in this document (see
section 12).
A Printer MUST support Create-Printer-Subscriptions and the
Subscription Template Attributes Group in Job Creation operations. It
MAY support Create-Job-Subscriptions operations.
Herriot, et al. Expires May 19, 2002 [page 58]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
11.1.1 Create-Job-Subscriptions Operation
The operation creates one or more Per-Job Subscription Objects. The
client supplies one or more Subscription Template Attributes Groups
each containing one or more of Subscription Template Attributes
(defined in section 5.3).
Except for errors, the Printer MUST create exactly one Per-Job
Subscription Object from each Subscription Template Attributes Group
in the request, even if the newly created Subscription Object would
have identical behavior to some existing Subscription Object. The
Printer MUST associate each newly created Per-Job Subscription Object
with the target Job, which is specified by the "notify-job-id"
operation attribute.
The Printer MUST accept the request in any of the target job's 'not-
completed' states, i.e., 'pending', 'pending-held', 'processing', or
'processing-stopped'. The Printer MUST NOT change the job's "job-
state" attribute because of this operation. If the target job is in
any of the 'completed' states, i.e., 'completed', 'canceled', or
'aborted, then the Printer MUST reject the request and return the
'client-error-not-possible' status code; the response MUST NOT
contain any Subscription Attribute Groups.
Access Rights: To create Per-Job Subscription Objects, the
authenticated user (see [RFC2911] section 8.3) performing this
operation MUST either be the job owner or have Operator or
Administrator access rights for this Printer (see [RFC2911] sections
1 and 8.5). Otherwise the Printer MUST reject the operation and
return: the 'client-error-forbidden', 'client-error-not-
authenticated', or 'client-error-not-authorized' status code as
appropriate.
11.1.1.1 Create-Job-Subscriptions Request
The following groups of attributes are part of the Create-Job-
Subscriptions Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Herriot, et al. Expires May 19, 2002 [page 59]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
notify-job-id (integer(1:MAX)):
The client MUST supply this attribute and it MUST specify the
Job object to associate the Per-Job Subscription with. The
value of "notify-job-id" MUST be the value of the "job-id" of
the associated Job object. If the client does not supply this
attribute, the Printer MUST reject this request with a 'client-
error-bad-request' status code.
Group 2-N: Subscription Template Attributes
For each occurrence of this group:
The client MUST supply one or more Subscription Template
Attributes in any order. See section 5.3 for a description of
each such attribute. See section 5.2 for details on processing
these attributes.
11.1.1.2 Create-Job-Subscriptions Response
The Printer MUST return to the client the following sets of
attributes as part of a Create-Job-Subscriptions response:
Group 1: Operation Attributes
Status Message:
In addition to the REQUIRED status code returned in every
response, the response OPTIONALLY includes a "status-message"
(text(255)) and/or a "detailed-status-message" (text(MAX))
operation attribute as described in [RFC2911] sections 13 and
3.1.6.
In this group, the Printer can return any status codes defined
in [RFC2911] and section 16. The following is a description of
the important status codes:
successful-ok: the Printer created all Subscription Objects
requested (see [RFC2911]).
successful-ok-ignored-subscriptions: the Printer created
some Subscription Objects requested but some failed. The
Subscription Attributes Groups with a "notify-status-
code" attribute are the ones that failed (see section
16.1).
Herriot, et al. Expires May 19, 2002 [page 60]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
client-error-ignored-all-subscriptions: the Printer created
no Subscription Objects requested and all failed. The
Subscription Attributes Groups with a "notify-status-
code" attribute are the ones that failed (see section
16.2).
client-error-not-possible: For this operation and other
Per-Job Subscription operations, this error can occur
because the specified Job has already completed (see
[RFC2911], whether or not the Job is retained in the Job
Retention and/or Job History phases (see [RFC2911]
section 4.3.7.1).
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 for details on returning
Unsupported Attributes. This group does not contain any
unsupported Subscription Template Attributes; they are returned
in the Subscription Attributes Group (see below).
Group 3-N: Subscription Attributes
These groups MUST be returned unless the Printer is unable to
interpret the entire request, e.g., the "status-code" parameter
returned in Group 1 has the value: 'client-error-bad-request'.
"notify-status-code" (type2 enum):
Indicates the status of this subscription (see section 17
for the status code definitions). Section 5.2 defines when
this attribute MUST be present in this group.
See section 5.2 for details on the contents of each occurrence
of this group.
11.1.2 Create-Printer-Subscriptions operation
The operation is identical to Create-Job-Subscriptions with
exceptions noted in this section.
The operation creates Per-Printer Subscription Objects instead of
Per-Job Subscription Objects, and associates each newly created Per-
Printer Subscription Object with the Printer specified by the
operation target rather than with a specific Job.
Herriot, et al. Expires May 19, 2002 [page 61]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
The Printer MUST accept the request in any of its states, i.e.,
'idle', 'processing', or 'stopped'. The Printer MUST NOT change its
"printer-state" attribute because of this operation.
Access Rights: To create Per-Printer Subscription Objects, the
authenticated user (see [RFC2911] section 8.3) performing this
operation MUST have Operator or Administrator access rights for this
Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the Printer
MUST reject the operation and return: the 'client-error-forbidden',
'client-error-not-authenticated', or 'client-error-not-authorized'
status code as appropriate.
11.1.2.1 Create-Printer-Subscriptions Request
The groups are identical to the Create-Job-Subscriptions (see section
11.1.1.1) except that the Operation Attributes group MUST NOT contain
the "notify-job-id" attribute. If the client does supply the
"notify-job-id" attribute, then the Printer MUST treat it as any
other unsupported Operation attribute and MUST return it in the
Unsupported Attributes group.
11.1.2.2 Create-Printer-Subscriptions Response
The groups are identical to the Create-Job-Subscriptions (see section
11.1.1.2).
11.1.3 Job Creation Operations - Extensions for Notification
This document extends the Job Creation operations (see section 3.2)
to create Subscription Objects as a part of the operation.
The Job Creation operations are identical to Create-Job-Subscriptions
operation with exceptions noted in this section.
Unlike the Create-Job-Subscriptions operation, a Job Creation
operation associates the newly created Subscription Objects with the
Job object created by this operation. The operation succeeds if and
only if the Job creation succeeds. If the Printer does not create
some or all of the requested Subscription Objects, the Printer MUST
return a 'successful-ok-ignored-subscriptions' status-code instead
of a 'successful-ok' status-code, but the Printer MUST NOT reject the
operation because of a failure to create Subscription Objects.
Herriot, et al. Expires May 19, 2002 [page 62]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
If the Job Creation operation includes a Job Template group, the
client MUST supply it after the Operation Attributes group and before
the first Subscription Template Attributes Group.
If a Printer does not support this Notification specification, then
it MUST treat the Subscription Attributes Group like an unknown group
and ignore it (see [RFC2911] section 5.2.2). Because the Printer
ignores the Subscription Attributes Group, it doesn't return them in
the response either, thus indicating to the client that the Printer
doesn't support Notification.
After completion of a successful Job Creation operation, the Printer
generates a 'job-created' event (see section 5.3.2.1.3).
Access Rights: To create Per-Job Subscription Objects, the
authenticated user (see [RFC2911] section 8.3) performing this
operation MUST either have permission to create Jobs on the Printer
or have Operator or Administrator access rights for this Printer (see
[RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the
operation and return: the 'client-error-forbidden', 'client-error-
not-authenticated', or 'client-error-not-authorized' status code as
appropriate.
11.1.3.1 Job Creation Request
The groups for this operation are sufficiently different from the
Create-Job-Subscriptions operation that they are all presented here.
The following groups of attributes are supplied as part of a Job
Creation Request:
Group 1: Operation Attributes
Same as defined in [RFC2911] for Print-Job, Print-URI, and
Create-Job requests.
Group 2: Job Template Attributes
The client OPTIONALLY supplies a set of Job Template attributes
as defined in [RFC2911] section 4.2.
Group 3 to N: Subscription Template Attributes
The same as Group 2-N in Create-Job-Subscriptions. See section
11.1.1.1.
Group N+1: Document Content (Print-Job only)
The client MUST supply the document data to be processed.
Herriot, et al. Expires May 19, 2002 [page 63]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
11.1.3.2 Job Creation Response
The Printer MUST return to the client the following sets of
attributes as part of a Print-Job, Print-URI, and Create-Job
Response:
Group 1: Operation Attributes
Status Message:
As defined in [RFC2911] for Print-Job, Print-URI, and Create-
Job requests.
In this group, the Printer can return any status codes defined
in [RFC2911] and section 16. The following is a description of
the important status codes:
successful-ok: the Printer created the Job and all
Subscription Objects requested (see [RFC2911].
successful-ok-ignored-subscriptions: the Printer created
the Job and not all of the Subscription Objects requested
(see section 16.1). This status-code hides 'successful-
ok-xxx' status-codes that could reveal problems in Job
creation. The Printer MUST NOT return the 'client-error-
ignored-all-subscriptions' status code for Job Creation
operations because the Printer returns an error status-
code only when it fails to create a Job.
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
See [RFC2911] section 3.1.7 for details on returning
Unsupported Attributes. This group does not contain any
unsupported Subscription Template Attributes; they are returned
in the Subscription Attributes Group (see below).
Group 3: Job Object Attributes
The "job-id" of the Job Object just created, etc., as defined
in [RFC2911] for Print-Job, Print-URI, and Create-Job requests.
Group 4 to N: Subscription Attributes
Herriot, et al. Expires May 19, 2002 [page 64]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
These groups MUST be returned if and only if the client
supplied Subscription Template Attributes and the operation was
accepted.
See section 5.2 for details on the contents of each occurrence
of this group.
11.2 Other Operations
This section defines other operations on Subscription objects.
11.2.1 Restart-Job Operation - Extensions for Notification
The Restart-Job operation [RFC2911] is neither a Job Creation
operation nor a Subscription Creation operation (see section 3.2).
For the Restart-Job operation, the client MUST NOT supply any Job
Subscription Attributes Groups. The Printer MUST treat any supplied
Job Subscription Attributes as unsupported attributes.
For this operation, the Printer does not return a job-id or any
Subscription Attributes groups because the Printer reuses the
existing Job object with the same job-id and the existing Per-Job
Subscription Objects with the same subscription-ids. However, after
successful completion of this operation, the Printer generates a
'job-created' event (see section 5.3.2.1.3).
11.2.2 Validate-Job Operation - Extensions for Notification
A client can test whether one or more Subscription Objects could be
created using the Validate-Job operation. The client supplies one or
more Subscription Template Attributes Groups (defined in section
5.3), just as in a Job Creation request.
A Printer MUST support this extension to this operation.
The Printer MUST accept requests that are identical to the Job
Creation request defined in section 11.1.3.1, except that the request
MUST NOT contain document data.
The Printer MUST return the same groups and attributes as the Print-
Job operation (section 11.1.3.1) with the following exceptions. The
Printer MUST NOT return a Job Object Attributes Group because no Job
is created. The Printer MUST NOT return the "notify-subscription-id"
attribute in any Subscription Attribute Group because no Subscription
Object is created.
Herriot, et al. Expires May 19, 2002 [page 65]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
If the Printer would succeed in creating a Subscription Object, the
corresponding Subscription Attributes Group either has no 'status-
code' attribute or a 'status-code' attribute with a value of
'successful-ok-too-many-events' or 'successful-ok-ignored-or-
substituted-attributes' (see sections 5.2 and 17). The status-codes
have the same meaning as in Job Creation except the results state
what "would happen".
The Printer MUST validate Subscription Template Attributes Groups in
the same manner as the Job Creation operations.
11.2.3 Get-Printer-Attributes - Extensions for Notification
This operation is extended so that it returns Printer attributes
defined in this document.
A Printer MUST support this extension to this operation.
In addition to the requirements of [RFC2911] section 3.2.5, a Printer
MUST support the following additional values for the "requested-
attributes" Operation attribute in this operation and return such
attributes in the Printer Object Attributes group of its response.
1.Subscription Template Attributes: Each supported attribute in
column 2 of Table 1.
2.New Printer Description Attributes: Each supported attribute in
section 6.
3.New Group Name: The 'subscription-template' group name, which
names all supported Subscription Template Attribute in column 2
of Table 1. This group name is also used in the Get-
Subscription-Attributes and Get-Subscriptions operation with an
analogous meaning.
4.Extended Group Name: The 'all' group name, which names all
Printer attributes according to [RFC2911] section 3.2.5. In
this extension 'all' names all attributes specified in [RFC2911]
plus those named in items 1 and 2 of this list.
11.2.4 Get-Subscription-Attributes operation
This operation allows a client to request the values of the
attributes of a Subscription Object.
A Printer MUST support this operation.
Herriot, et al. Expires May 19, 2002 [page 66]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
This operation is almost identical to the Get-Job-Attributes
operation (see [RFC2911] section 3.3.4). The only differences are
that the operation is directed at a Subscription Object rather than a
Job object, and the returned attribute group contains Subscription
Object attributes rather than Job object attributes.
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.
"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.
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
"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).
Herriot, et al. Expires May 19, 2002 [page 67]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
- '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
Herriot, et al. Expires May 19, 2002 [page 68]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
This group contains a set of attributes with their current
values. Each attribute 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] section 8.
The Printer can return the attributes of the Subscription
Object in any order. The client MUST accept the attributes in
any order.
11.2.5 Get-Subscriptions operation
This operation allows a client to retrieve the values of attributes
of all Subscription Objects belonging to a Job or Printer.
A Printer MUST supported this operation.
This operation is similar to the Get-Subscription-Attributes
operation, except that this Get-Subscriptions operation returns
attributes from possibly more than one object.
This operation is similar to the Get-Jobs operation (see [RFC2911]
section 3.2.6), except that the operation returns Subscription
Objects rather than Job objects.
11.2.5.1 Get-Subscriptions Request
The following groups of attributes are part of the Get-Subscriptions
request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
Herriot, et al. Expires May 19, 2002 [page 69]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
"notify-job-id" (integer(1:MAX)):
If the client specifies this attribute, the Printer returns the
specified attributes of all Per-Job Subscription Objects
associated with the Job whose "job-id" attribute value equals
the value of this attribute. If the client does not specify
this attribute, the Printer returns the specified attributes of
all Per-Printer Subscription Objects. Note: there is no way to
get all Per-Job Subscriptions known to the Printer in a single
operation. A Get-Jobs operation followed by a Get-
Subscriptions operation for each Job will return all Per-Job
Subscriptions.
"limit" (integer(1:MAX)):
The client OPTIONALLY supplies this attribute. The Printer
MUST support this attribute. It is an integer value that
determines the maximum number of Subscription Objects that a
client will receive from the Printer even if the "my-
subscriptions" attribute constrains which Subscription Objects
are returned. The limit is a "stateless limit" in that if the
value supplied by the client is 'N', then only the first 'N'
Subscription Objects are returned in the Get-Subscriptions
Response. There is no mechanism to allow for the next 'M'
Subscription Objects after the first 'N' Subscription Objects.
If the client does not supply this attribute, the Printer
responds with all applicable Subscription Objects.
"requested-attributes" (1setOf type2 keyword):
The client OPTIONALLY supplies this attribute. The Printer
MUST support this attribute. This attribute specifies the
attributes of the specified Subscription Objects that the
Printer MUST return in the response. Each value of this
attribute is either an attribute name (defined in sections 5.3
and 5.4) or an attribute group name (defined in section
11.2.4.1). If the client omits this attribute, the Printer MUST
respond as if the client had supplied this attribute with the
one value: 'notify-subscription-id'.
"my-subscriptions" (boolean):
The client OPTIONALLY supplies this attribute. The Printer
MUST support this attribute. If the value is 'false', the
Printer MUST consider the Subscription Objects from all users
as candidates. If the value is 'true', the Printer MUST return
the Subscription Objects created by the requesting user of this
Herriot, et al. Expires May 19, 2002 [page 70]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
request. If the client does not supply this attribute, the
Printer MUST respond as if the client had supplied the
attribute with a value of 'false'. The means for
authenticating the requesting user and matching the
Subscription Objects is similar to that for Jobs which is
described in [RFC2911] section 8.
11.2.5.2 Get-Subscriptions Response
The Printer returns the following sets of attributes as part of the
Get-Subscriptions Response:
Group 1: Operation Attributes
Status Message:
Same as [RFC2911].
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.2.
Group 2: Unsupported Attributes
Same as for Get-Subscription-Attributes.
Groups 3 to N: Subscription Attributes
The Printer responds with one Subscription Attributes Group for
each requested Subscription Object (see the "notify-job-id"
attribute in the Operation Attributes Group of this operation).
The Printer returns Subscription Objects in any order.
If the "limit" attribute is present in the Operation Attributes
group of the request, the number of Subscription Attributes
Groups in the response MUST NOT exceed the value of the "limit"
attribute.
It there are no Subscription Objects associated with the
specified Job or Printer, the Printer MUST return zero
Subscription Attributes Groups and it MUST NOT treat this case
as an error, i.e., the status-code MUST be 'successful-ok'
unless something else causes the status code to have some other
value.
Herriot, et al. Expires May 19, 2002 [page 71]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
See the Group 3 response (Subscription Attributes Group) of the
Get-Subscription-Attributes operation (section 11.2.4.2) for
the attributes that a Printer returns in this group.
11.2.6 Renew-Subscription operation
This operation allows a client to request the Printer to extend the
lease on a Per-Printer Subscription Object.
The Printer MUST support this operation.
The Printer MUST accept this request for a Per-Printer Subscription
Object in any of the target Printer's states, i.e., 'idle',
'processing', or 'stopped', but MUST NOT change the Printer's
"printer-state" attribute.
The Printer MUST reject this request for a Per-Job Subscription
Object because it has no lease (see section 5.4.3). The status code
returned MUST be 'client-error-not-possible'.
Access Rights: The authenticated user (see [RFC2911] section 8.3)
performing this operation MUST either be the owner of the Per-Printer
Subscription Object or have Operator or Administrator access rights
for the Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the
Printer MUST reject the operation and return: the 'client-error-
forbidden', 'client-error-not-authenticated', or 'client-error-not-
authorized' status code as appropriate.
11.2.6.1 Renew-Subscription Request
The following groups of attributes are part of the Renew-Subscription
Request:
Group 1: Operation Attributes
Natural Language and Character Set:
The "attributes-charset" and "attributes-natural-language"
attributes as described in [RFC2911] section 3.1.4.1.
Target:
The "printer-uri" attribute which defines the target for this
operation as described in [RFC2911] section 3.1.5.
"notify-subscription-id" (integer (1:MAX)):
The client MUST supply this attribute. The Printer MUST
support this attribute. This attribute specifies the Per-
Herriot, et al. Expires May 19, 2002 [page 72]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Printer Subscription Object whose lease the Printer MUST renew.
If the client omits this attribute, the Printer MUST reject
this request with the 'client-error-bad-request' status code.
Requesting User Name:
The "requesting-user-name" (name(MAX)) attribute SHOULD be
supplied by the client as described in [RFC2911] section 8.3.
Group 2: Subscription Template Attributes
"notify-lease-duration" (integer(0:MAX)):
The client MAY supply this attribute. It indicates the number
of seconds to renew the lease for the specified Subscription
Object. A value of 0 requests an infinite lease (which MAY
require Operator access rights). If the client omits this
attribute, the Printer MUST use the value of the Printer's
"notify-lease-duration-default" attribute. See section 5.3.7
for more details.
11.2.6.2 Renew-Subscription Response
The Printer returns the following sets of attributes as part of the
Renew-Subscription Response:
Group 1: Operation Attributes
Status Message:
Same as [RFC2911].
The following are some of the status codes returned (see
[RFC2911]:
successful-ok: The operation successfully renewed the lease
on the Subscription Object for the requested duration.
successful-ok-ignored-or-substituted-attributes: The
operation successfully renewed the lease on the
Subscription Object for some duration other than the
amount requested.
client-error-not-possible: The operation failed because the
"notify-subscription-id" Operation attribute identified a
Per-Job Subscription Object.
client-error-not-found: The operation failed because the
"notify-subscription-id" Operation attribute identified a
non-existent Subscription Object.
Herriot, et al. Expires May 19, 2002 [page 73]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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:
"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.7 for details, such as the value of
this attribute when the Printer doesn't support the requested
value).
11.2.7 Cancel-Subscription operation
This operation allows a client to delete a Subscription Object and
stop the Printer from sending more Event Notifications. Once
performed, there is no way to reference the Subscription Object.
A Printer MUST supported this operation.
The Printer MUST accept this request in any of the target Printer's
states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change
the Printer's "printer-state" attribute.
If the specified Subscription Object is a Per-Job Subscription
Object, the Printer MUST accept this request in any of the target
Job's states, but MUST NOT change the Job's "job-state" attribute or
affect the Job.
Access Rights: The authenticated user (see [RFC2911] section 8.3)
performing this operation MUST either be the owner of the
Subscription Object or have Operator or Administrator access rights
for the Printer (see [RFC2911] sections 1 and 8.5). Otherwise, the
Printer MUST reject the operation and return: the 'client-error-
Herriot, et al. Expires May 19, 2002 [page 74]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
forbidden', 'client-error-not-authenticated', or 'client-error-not-
authorized' status code as appropriate.
Note: There is no way to change any attributes on a Subscription
Object, except the "notify-lease-duration" attribute (using the
Renew-Subscription operation). In order to change other attributes,
a client performs a Subscription Creation Operation and Cancel-
Subscription operation on the old Subscription Object. If the client
wants to avoid missing Event Notifications, it performs the
Subscription Creation Operation first. If this order would create too
many Subscription Objects on the Printer, the client reverses the
order.
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.
"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.
Requesting User Name:
The "requesting-user-name" attribute SHOULD be supplied by the
client as described in [RFC2911] section 8.3.
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
Herriot, et al. Expires May 19, 2002 [page 75]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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 Conformance Requirements
It is OPTIONAL for IPP clients and Printers to implement this Event
Notification specification.
If this Event Notification specification is implemented, Printers
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.
- send 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
Herriot, et al. Expires May 19, 2002 [page 76]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
requirements for Delivery Method Documents is specified in
section 10).
- for all of the Job Creation Operations that the Printer
supports, MUST support the REQUIRED extensions for notification
defined in section 11.1.3.
- meet the conformance requirements for operations as described
in Table 16 and meet the requirements for Printers as specified
in the indicated sub-sections of section 11:
Table 16 - Printer Conformance Requirements for Operations
Operation Printer
Conformance
Requirements
Create-Printer-Subscriptions (section 11.1.2) REQUIRED
Create-Job-Subscriptions (section 11.1.1) OPTIONAL
Get-Subscription-Attributes (section 11.2.3) REQUIRED
Get-Subscriptions (section 11.2.5) REQUIRED
Renew-Subscription (section 11.2.6) REQUIRED
Cancel-Subscription (section 11.2.7) REQUIRED
13 IANA Considerations
This section contains the registration information for IANA to add to
the various IPP Registries according to the procedures defined in RFC
2911 [RFC2911] section 6 to cover the definitions in this document.
In addition, this section defines how Events and Delivery Methods
will be registered when they are defined in other documents.
Note to RFC Editors: Replace RFC NNNN below with the RFC number
for this document, so that it accurately reflects the content of
the information for the IANA Registry.
Herriot, et al. Expires May 19, 2002 [page 77]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
13.1 Attribute Registrations
The following table lists all the attributes defined in this
document. These are to be registered according to the procedures in
RFC 2911 [RFC2911] section 6.2.
Subscription Template attributes: Ref. Section:
notify-recipient-uri (uri) RFC NNNN 5.3.1.1
notify-schemes-supported (1setOf uriScheme) RFC NNNN 5.3.1.1
notify-pull-method (type2 keyword) RFC NNNN 5.3.1.2
notify-pull-method-supported (1setOf type2 keyword)
RFC NNNN 5.3.1.2
notify-events (1setOf type2 keyword) RFC NNNN 5.3.2
notify-events-default (1setOf type2 keyword) RFC NNNN 5.3.2
notify-events-supported (1setOf type2 keyword) RFC NNNN 5.3.2
notify-max-events-supported (integer(2:MAX)) RFC NNNN 5.3.2
notify-attributes (1setOf type2 keyword) RFC NNNN 5.3.3
notify-attributes-supported (1setOf type2 keyword)
RFC NNNN 5.3.3
notify-user-data (octetString(63)) RFC NNNN 5.3.4
notify-charset (charset) RFC NNNN 5.3.5
notify-natural-language (naturalLanguage) RFC NNNN 5.3.6
notify-lease-duration (integer(0:67108863)) RFC NNNN 5.3.7
notify-lease-duration-default (integer(0:67108863))
RFC NNNN 5.3.7
notify-lease-duration-supported (1setOf (integer(0: 67108863) |
rangeOfInteger(0:67108863))) RFC NNNN 5.3.7
notify-time-interval (integer(0:MAX)) RFC NNNN 5.3.8
Subscription Description Attributes:
notify-subscription-id (integer (1:MAX))) RFC NNNN 5.4.1
notify-sequence-number (integer (0:MAX))) RFC NNNN 5.4.2
notify-lease-expiration-time (integer(0:MAX))) RFC NNNN 5.4.3
notify-printer-up-time (integer(1:MAX))) RFC NNNN 5.4.4
notify-printer-uri (uri)) RFC NNNN 5.4.5
notify-job-id (integer(1:MAX))) RFC NNNN 5.4.6
notify-subscriber-user-name (name(MAX))) RFC NNNN 5.4.7
Printer Description Attributes:
printer-state-change-time (integer(1:MAX))) RFC NNNN 6.1
printer-state-change-date-time (dateTime)) RFC NNNN 6.2
Attributes Only in Event Notifications
notify-subscribed-event (type2 keyword) RFC NNNN 8.1
notify-text (text(MAX)) RFC NNNN 8.2
The resulting attribute registrations will be published in the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attributes/
Herriot, et al. Expires May 19, 2002 [page 78]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
area.
13.2 Additional Enum Attribute Value Registrations for the "operations-
supported" Printer Attribute
The following table lists all the new enum attribute values defined
in this document as additional type2 enum values for use with the
"operations-supported" Printer Description attribute. These are to
be registered according to the procedures in RFC 2911 [RFC2911]
section 6.1.
type2 enum Attribute Values: Value Ref. Section:
Create-Printer-Subscriptions 0x0016 RFC NNNN 7.1
Create-Job-Subscriptions 0x0017 RFC NNNN 7.1
Get-Subscription-Attributes 0x0018 RFC NNNN 7.1
Get-Subscriptions 0x0019 RFC NNNN 7.1
Renew-Subscription 0x001A RFC NNNN 7.1
Cancel-Subscription 0x001B RFC NNNN 7.1
The resulting enum attribute value registrations will be published in
the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-
values/operations-supported/
area.
13.3 Operation Registrations
The following table lists all of the operations defined in this
document. These are to be registered according to the procedures in
RFC 2911 [RFC2911] section 6.4.
Operations: Ref. Section:
Create-Job-Subscriptions Operation RFC NNNN 11.1.1
Create-Printer-Subscriptions Operation RFC NNNN 11.1.2
Job Creation Operations - Extensions RFC NNNN 11.1.3
Validate-Job Operation - Extensions RFC NNNN 0
Get-Printer-Attributes - Extensions RFC NNNN 11.2.3
Get-Subscription-Attributes Operation RFC NNNN 11.2.4
Get-Subscriptions Operation RFC NNNN 11.2.5
Renew-Subscription Operation RFC NNNN 11.2.6
Cancel-Subscription Operation RFC NNNN 11.2.7
The resulting operation registrations will be published in the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/operations/
area.
Herriot, et al. Expires May 19, 2002 [page 79]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
13.4 Status code Registrations
The following table lists all the status codes defined in this
document. These are to be registered according to the procedures in
RFC 2911 [RFC2911] section 6.6.
Status codes: Ref. Section:
successful-ok-ignored-subscriptions (0x0003) RFC NNNN 16.1
client-error-ignored-all-subscriptions (0x0414) RFC NNNN 16.2
Status Codes in Subscription Attributes Groups:
client-error-uri-scheme-not-supported (0x040C) RFC NNNN 17.1
client-error-attributes-or-values-not-supported (0x040B)
RFC NNNN 17.2
client-error-too-many-subscriptions (0x0415) RFC NNNN 17.3
successful-ok-too-many-events (0x0005) RFC NNNN 17.4
successful-ok-ignored-or-substituted-attributes (0x0001)
RFC NNNN 17.5
The resulting status code registrations will be published in the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/status-codes/
area.
13.5 Attribute Group tag Registrations
The following table lists all the attribute group tags defined in
this document. These are to be registered according to the
procedures in RFC 2911 [RFC2911] section 6.5.
Attribute Group Tags: Tag Value: Ref. Section:
subscription-attributes-tag 0x06 RFC NNNN 18
event-notification-attributes-tag 0x07 RFC NNNN 18
The resulting attribute group tag registrations will be published in
the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-group-
tags/
area.
13.6 Registration of Events
When other document define additional type2 keywords to be used with
the "notify-events" Subscription Template attribute (see section
5.3.2)), these event keywords will be registered according to the
procedures of [RFC2911] section 7.1 as additional attribute values
for use with the "notify-events" Subscription Template attribute,
Herriot, et al. Expires May 19, 2002 [page 80]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
i.e., the "notify-events", "notify-events-default", and "notify-
events-supported" attributes.
Therefore, the IPP Registry entry for an Event will be of the form:
type2 enum Attribute Values: Ref. Section:
<scheme name> RFC xxxx m.n
The resulting type2 keyword attribute values will be published in the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-
values/notify-events/
area.
13.7 Registration of Event Notification Delivery Methods
This section describes the requirements and procedures for
registration and publication of Event Notification Delivery Methods
and for the submission of such proposals.
13.7.1 Requirements for Registration of Event Notification Delivery
Methods
Registered IPP Event Notification Delivery Methods are expected to
follow a number of requirements described below.
13.7.1.1 Required Characteristics
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 in combination is the Delivery Method (e.g., mailto). In either
case, the Delivery Method Document (and any documents it requires)
MUST define a URL for a Push Delivery Method or a keyword for a Pull
Delivery method and be a standards track, informational, or
experimental RFC that the meets the requirements of [RFC2717].
IPP Event Notification Delivery Method Documents MUST meet the
requirements of this document (see sections 9 and 10).
In addition, a Delivery Method Document MUST contain the following
information:
Type of registration: IPP Event Notification Delivery Method
Name of this delivery method:
Herriot, et al. Expires May 19, 2002 [page 81]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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:
13.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.
All Push Delivery Method names MUST conform to the rules for URL
scheme names, according to [RFC2396] and [RFC2717] for schemes in the
IETF tree. All Pull Delivery Method names MUST conform to the rules
for keywords according to [RFC2911].
13.7.1.3 Functionality Requirements
Delivery Methods MUST function as a protocol that is capable of
delivering (push or pull) IPP Event Notifications to Notification
Recipients.
13.7.1.4 Usage and Implementation Requirements
Use of a large number of Delivery Methods may hamper
interoperability. However, the use of a large number of undocumented
and/or unlabelled Delivery Methods hampers interoperability even
more.
A Delivery Method should therefore be registered ONLY if it adds
significant functionality that is valuable to a large community, OR
if it documents existing practice in a large community. Note that
Delivery Methods registered for the second reason should be
explicitly marked as being of limited or specialized use and should
only be used with prior bilateral agreement.
Herriot, et al. Expires May 19, 2002 [page 82]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
13.7.1.5 Publication Requirements
Delivery Method Documents MUST be published in a standards track,
informational, or experimental RFCs.
13.7.2 Registration Procedure
The IPP WG is developing a small number of Delivery Methods which are
intended to be published as standards track RFCs. However, some
parties may wish to register additional Delivery Methods in the
future. This section describes the procedures for these additional
Delivery Methods.
13.7.2.1 Present the proposal to the Community
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 that it references.
Send the proposed Delivery Method Document proposal to the
"
[email protected]" mailing list. This mailing list has been established
by [RFC2911] for reviewing proposed registrations and discussing
other IPP matters. Proposed Delivery Method Documents are not
formally registered and MUST NOT be used until approved.
The intent of the public posting is to solicit comments and feedback
on the definition and suitability of the Delivery Method and the name
chosen for it over a four week period.
13.7.2.2 Delivery Method Reviewer
The Delivery Method Reviewer is the same person who has been
appointed by the IETF Application Area Director(s) as the IPP
Designated Expert according to [RFC2911] and [IANA-CON]. When the
four week period is over and the IPP Designated Expert is convinced
that consensus has been achieved, the IPP Designated Expert either
approves the request for registration or rejects it. Rejection may
occur because of significant objections raised on the list or
objections raised externally.
Decisions made by the Reviewer must be posted to the
[email protected]
mailing list within 14 days. Decisions made by the Reviewer may be
appealed to the IESG.
Herriot, et al. Expires May 19, 2002 [page 83]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
13.7.2.3 IANA Registration
Provided that the Delivery Method registration proposal has either
passed review or has been successfully appealed to the IESG, the IANA
will register the Delivery Method and make it available to the
community.
13.7.3 Delivery Method Document Registrations
Each Push Delivery Method Document defines a URI scheme which is
registered as an additional value of the "notify-schemes-supported"
Printer attribute. These uriScheme values will be registered
according to the procedures of [RFC2911] section 7.1 for additional
attribute values. Therefore, the IPP Registry entry for a Push
Delivery Method will be of the form:
uriScheme Attribute Values: Ref. Section:
<scheme name> RFC xxxx m.n
The resulting Delivery Method URI schemes will be published in the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-
values/notify-schemes-supported/
area.
Each Pull Delivery Method Document defines a keyword method which is
registered as an additional value of the "notify-pull-method-
supported" Printer attribute. These keyword values will be
registered according to the procedures of [RFC2911] section 7.1 for
additional attribute values. Therefore, the IPP Registry entry for a
Pull Delivery Method will be of the form:
keyword Attribute Values: Ref. Section:
<method name> RFC xxxx m.n
The resulting Delivery Method URI schemes will be published in the
ftp://ftp.iana.org/in-notes/iana/assignments/ipp/attribute-
values/notify-pull-method-supported/
area.
13.7.4 Registration Template
To:
[email protected]
Subject: Registration of a new Delivery Method
Delivery Method name:
Herriot, et al. Expires May 19, 2002 [page 84]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
(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:
14 Internationalization Considerations
This IPP Notification specification continues support for the
internationalization of [RFC2911] of attributes containing text
strings and names. Allowing a Subscribing Client to specify a
different natural language and charset for each Subscription Object
increases the internationalization support.
The Printer MUST be able to localize the content of Human Consumable
Event Notifications and to localize the value of "notify-text"
attribute in Machine Consumable Event Notifications that it sends 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 supplied by the
Subscribing Client.
15 Security Considerations
By far the biggest security concern is the abuse of notification:
sending unwanted Event Notifications to third parties (i.e., spam).
The problem is made worse by notification addresses that may be
redistributed to multiple parties (e.g., mailing lists). There exist
scenarios where third party notification is required (see Scenario #2
and #3 in [ipp-not-req]). The fully secure solution would require
active agreement of all recipients before sending out anything.
However, requirement #9 in [ipp-req] ("There is no requirement for
IPP Printer receiving the print request to validate the identity of
an Event recipient") argues against this. Certain systems may decide
to disallow third party Event Notifications (a traditional fax
model).
Clients submitting Notification requests to the IPP Printer have the
same security issues as submitting an IPP/1.1 print job request. The
same mechanisms used by IPP/1.1 can therefore be used by the client
Notification submission. Operations that require authentication can
use the HTTP authentication. Operations that require privacy can use
Herriot, et al. Expires May 19, 2002 [page 85]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
the HTTP/TLS privacy. As with IPP/1.1 Print Jobs, if there is no
security on Subscription Objects, sequential assignment of
subscription-ids exposes the system to a passive traffic monitoring
threat.
The Notification access control model should be similar to the IPP
access control model for Jobs. Creating a Per-Printer Subscription
Object is associated with a user. Only the creator or an Operator
can cancel the Subscription Object. The system may limit the listing
of items to only those items owned by the user. Some Subscription
Objects (e.g., those that have a lifetime longer than a job) can be
done only by privileged users (users having Operator and/or
Administrator access rights), if that is the authorization policy.
The standard security concerns (delivery to the right user, privacy
of content, tamper proof content) apply to the Delivery Method. IPP
should use the security mechanism of the Delivery Method used. Some
delivery mechanisms are more secure than others. Therefore,
sensitive Event Notifications should use the Delivery Method that has
the strongest security.
16 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.
16.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-
Herriot, et al. Expires May 19, 2002 [page 86]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
attributes' and/or 'successful-ok-conflicting-attributes', it MUST
return 'successful-ok-ignored-subscriptions'.
16.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.
17 Status Codes in Subscription Attributes Groups
This section contains values of the "notify-status-code" (type2 enum)
attribute that the Printer returns in a Subscription Attributes Group
in a response when the corresponding Subscription Object:
1.is not created or
2.is created and some of the client-supplied attributes are not
supported.
The following sections are ordered in decreasing order of importance
of the status-codes.
17.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.1.
17.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.1.2.
Herriot, et al. Expires May 19, 2002 [page 87]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
17.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).
17.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.2).
17.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.
18 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:
Herriot, et al. Expires May 19, 2002 [page 88]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Tag Value (Hex) Meaning
0x06 "subscription-attributes-tag"
0x07 "event-notification-attributes-tag"
19 References
[IANA-CON]
Narte, T. and Alvestrand, H.T.: Guidelines for Writing an IANA
Considerations Section in RFCs, BCP 26, RFC 2434, October 1998.
[ipp-not-req]
deBry, R., Lewis, H., Hastings, T., "Internet Printing
Protocol/1.1: Requirements for IPP Notifications", <draft-ietf-ipp-
not-06.txt>, work in progress, July 17, 2001.
[ipp-prog]
Hastings, T., Bergman, R., Lewis, H., "IPP: Job Progress
Attributes", <draft-ietf-ipp-job-prog-03.txt> work in
progress, July 17, 2001.
[ipp-set]
Kugler, C., Hastings, T., Herriot, R., Lewis, H, "Internet Printing
Protocol (IPP): Job and Printer Set Operations", <draft-ietf-ipp-
job-printer-set-ops-04.txt>, work in progress, July 17, 2001.
[RFC2026]
S. Bradner, "The Internet Standards Process -- Revision 3", RFC
2026, October 1996.
[RFC2119]
S. Bradner, "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119 , March 1997
[RFC2396]
Berners-Lee, T., Fielding, R., Masinter, L., "Uniform Resource
Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
[RFC2565]
Herriot, R., Butler, S., Moore, P., and R. Turner, "Internet
Printing Protocol/1.0: Encoding and Transport", RFC 2565, April
1999.
Herriot, et al. Expires May 19, 2002 [page 89]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
[RFC2566]
deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P.,
"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., Martin, J., "Mapping between
LPD and IPP Protocols", RFC 2569, April 1999.
[RFC2717]
R. Petke and I. King, "Registration Procedures for URL Scheme
Names", RFC 2717, November 1999.
[RFC2910]
Herriot, R., Butler, S., Moore, P., Turner, R., "Internet Printing
Protocol/1.1: Encoding and Transport", RFC 2910, September 2000.
[RFC2911]
deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P.,
"Internet Printing Protocol/1.1: Model and Semantics", RFC 2911,
September 2000.
20 Author's Addresses
Robert Herriot
2066 Byron St.
Palo Alto, CA 94301
Phone: 650-326-8279
Fax: 650-327-4466
Email:
[email protected]
Tom Hastings
Xerox Corporation
737 Hawaii St. ESAE 231
El Segundo, CA 90245
Phone: 310-333-6413
Fax: 310-333-5514
Herriot, et al. Expires May 19, 2002 [page 90]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
e-mail:
[email protected]
Scott A. Isaacson
Novell, Inc.
122 E 1700 S
Provo, UT 84606
Phone: 801-861-7366
Fax: 801-861-2517
e-mail:
[email protected]
Roger deBry
Utah Valley State College
Orem, UT 84058
Phone: (801) 222-8000
EMail:
[email protected]
Jay Martin
Underscore Inc.
9 Jacqueline St.
Hudson, NH 03051-5308
603-889-7000
fax: 775-414-0245
e-mail:
[email protected]
Michael Shepherd
Xerox Corporation
800 Phillips Road MS 128-51E
Webster, NY 14450
Phone: 716-422-2338
Fax: 716-265-8871
e-mail:
[email protected]
Ron Bergman
Hitachi Koki Imaging Solutions
1757 Tapo Canyon Road
Simi Valley, CA 93063-3394
Phone: 805-578-4421
Fax: 805-578-4001
Email:
[email protected]
Herriot, et al. Expires May 19, 2002 [page 91]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
IPP Web Page:
http://www.pwg.org/ipp/
IPP Mailing List:
[email protected]
To subscribe to the ipp mailing list, send the following email:
1) send it to
[email protected]
2) leave the subject line blank
3) put the following two lines in the message body:
subscribe ipp
end
Implementers of this specification document are encouraged to join
the IPP Mailing List in order to participate in any discussions of
clarification issues and review of registration proposals for
additional attributes and values. In order to reduce spam the
mailing list rejects mail from non-subscribers, so you must subscribe
to the mailing list in order to send a question or comment to the
mailing list.
A. Appendix - Model for Notification with Cascading Printers
With this model (see Figure 2), there is an intervening Print server
between the human user and the output-device. So the system
effectively has two Printers. There are two cases to consider.
1.When the Printer 1 (in the server) generates Events, the system
behaves like the client and Printer in Figure 1. In this case,
Printer 1 sends Event Notifications that are shown as Event
Notifications (A) of Figure 2,.
2.When the Printer 2 (in the output-device) generates Events, there
are two possible system configurations:
a)Printer 1 forwards the client-supplied Subscription Creation
Operations to the downstream Printer 2 and lets Printer 2 send
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 sends 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
Herriot, et al. Expires May 19, 2002 [page 92]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Subscription Creation Operation to Printer 2 if it would create
a duplicate Subscription Object on Printer 2.
Note: when Printer 1 is forwarding Subscription Creation Operations
to Printer 2, it may request Printer 2 to create additional
Subscription Objects (called "piggy-backing"). Piggy-backing is
useful when:
- Device A is configured to accept (IPP or non-IPP) requests from
other servers.
- Server S wants to receive Job Events that the client didn't
request and Server S wants these Events for jobs it submits and
not for other jobs.
server S device A
+------------+ +------------+
| | | |
+--------+ Subscription | ###########| | ###########|
| client |--Creation ----># Printer #| Subscription | # Printer #|
+--------+ Operation | # Object 1#|---Creation------|># Object 2#|
| ###|#######| Operation | ####|#|####|
+----|---^---+ +-----|-|----+
+--------+ Event | | | |
|Notific-|<-Notifications(A)-+ +-- Event Notifications(B)--+ |
|ation Re|<-------------Event Notifications(C)-----------------+
|cipient |
+--------+
Figure 2 - Model for Notification with Cascading Printers
B. Appendix - Distributed Model for Notification
A Printer implementation could use some other remote notification
service to provide some or most of the service. For example, the
remote notification service could send Event Notifications using
Delivery Methods that are not directly supported by the output device
or server. Or, the remote notification service 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 send the Event Notifications to the Notification Recipient(s).
Figure 3 shows this partitioning. The interface between the output
device (or server) and the remote notification service is outside the
scope of this document and is intended to be transparent to the
client and this document. The combination of the output device (or
Herriot, et al. Expires May 19, 2002 [page 93]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
server) and the notification service together constitute an IPP
Printer conforming to this Notification document.
***********************
*
* Printer (including
* the distributed
* Notification Service)
*
* output device or server
* +---------------+
PDA, desktop, or server * + ########### +
+--------+ * | # partial # |
| client |---IPP Subscription--------># Printer # |
+--------+ Creation operation * | # Object # |
* | #####|##### |
* +-------|-------+
* | Subscriptions
* | OR Event
+------------+ * | Notifications
|Notification| IPP-defined * +------v--------+
|Recipient |<--Event Notifications---| Notification |
+------------+ * | Service |
* +---------------+
*
*************************
*** = Implementation configuration opaque boundary
Figure 3 - Opaque Use of a Notification Service Transparent to the
Client
C. Appendix - Extended Notification Recipient
The model allows for an extended Notification Recipient that is
itself a notification service 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.
Herriot, et al. Expires May 19, 2002 [page 94]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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 service 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 Service)
Figure 4 - Use of an Extended Notification Recipient transparent to
the Printer
D. Appendix - Details about Conformance Terminology
The following paragraphs provide more details about conformance
terminology.
REQUIRED - an adjective used to indicate that a conforming IPP
Printer implementation MUST support the indicated operation,
object, attribute, attribute value, status code, or out-of-band
value in requests and responses. See [RFC2911] "Appendix A -
Herriot, et al. Expires May 19, 2002 [page 95]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Terminology for a definition of "support". Since support of this
entire Notification specification is OPTIONAL for conformance to
IPP/1.0 or IPP/1.1, the use of the term REQUIRED in this document
means "REQUIRED if this OPTIONAL Notification specification is
implemented".
RECOMMENDED - an adjective used to indicate that a conforming IPP
Printer implementation is recommended to support the indicated
operation, object, attribute, attribute value, status code, or
out-of-band value in requests and responses. Since support of
this entire Notification specification is OPTIONAL for conformance
to IPP/1.0 or IPP/1.1, the use of the term RECOMMENDED in this
document means "RECOMMENDED if this OPTIONAL Notification
specification is implemented".
OPTIONAL - an adjective used to indicate that a conforming IPP
Printer implementation MAY, but is NOT REQUIRED to, support the
indicated operation, object, attribute, attribute value, status
code, or out-of-band value in requests and responses.
E. Appendix - Object Model for Notification
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.
Herriot, et al. Expires May 19, 2002 [page 96]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
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.
E.1 Appendix - 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
Herriot, et al. Expires May 19, 2002 [page 97]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
with them in some way is IMPLEMENTATION DEPENDENT and is transparent
to the client. The object relationships are defined as follows:
E.2 Printer Object and Per-Printer Subscription Objects
1.The Printer object contains (is associated with) zero or more
Per-Printer Subscription Objects (p1 contains s1-s3 Per-Printer
Subscription Objects).
2.Each Per-Printer Subscription Object (s1, s2, and s3) is
contained in (or is associated with) exactly one Printer object
(p1).
E.3 Job Object and Per-Job Subscription Objects
1.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.
2.Each Per-Job Subscription Object is associated with exactly one
Job object.
F. Appendix - Per-Job versus Per-Printer Subscription Objects
Per-Job and Per-Printer Subscription Objects are quite similar.
Either type of Subscription Object can subscribe to Job Events,
Printer Events, or both. Both types of Subscription Objects can be
queried using the Get-Subscriptions and Get-Subscription-Attributes
operations and canceled using the Cancel-Subscription operation.
Both types of Subscription Objects create Subscription Objects which
have the same Subscription Object attributes defined. However, there
are some semantic differences between Per-Job Subscription Objects
and Per-Printer Subscription Objects. A Per-Job Subscription Object
is established by the client when submitting a job and after creating
the job using the Create-Job-Subscriptions operation by specifying
the "job-id" of the Job with the "notify-job-id" attribute. A Per-
Printer Subscription Object is established between a client and a
Printer using the Create-Printer-Subscriptions operation. Some
specific differences are:
1.A client usually creates one or more Per-Job Subscription
Objects as part of the Job Creation operations (Create-Job,
Print-Job, and Print-URI), rather than using the OPTIONAL
Herriot, et al. Expires May 19, 2002 [page 98]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Create-Job-Subscriptions operation, especially since Printer
implementations NEED NOT support the Create-Job-Subscriptions
operation, since it is OPTIONAL.
2.For Per-Job Subscription Objects, the Subscription Object is
only valid while the job is "not-complete" (see sections 5.4.3)
while for the Per-Printer Subscription Objects, the Subscription
Object is valid until the time (in seconds) that the Printer
returned in the "notify-lease-expiration-time" operation
attribute.
3.Job Events in a Per-Job Subscription Object apply only to "one
job" (the Job created by the Job Creation operation or
references by the Create-Job-Subscriptions operation) while Job
Events in a Per-Printer Subscription Object apply to ALL jobs
contained in the IPP Printer.
G. Appendix - Description of the base IPP documents
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 [IPP-IIG]
Mapping between LPD and IPP Protocols [RFC2569]
The "Design Goals for an Internet Printing Protocol" document takes a
broad look at distributed printing functionality, and it enumerates
real-life scenarios that help to clarify the features that need to be
included in a printing protocol for the Internet. 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, defines a roadmap for the various documents that form the suite
of IPP specification documents, and gives background and rationale
for the IETF IPP working group's major decisions.
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. The
Herriot, et al. Expires May 19, 2002 [page 99]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
Job supports multiple documents per Job. The model document also
addresses 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 defined
in 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 also defines the rules for
transporting over HTTP a message body whose Content-Type is
"application/ipp". This document 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 is intended to help them understand IPP/1.1 and some of
the considerations that may assist them in the design of 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.
H. Appendix - Full Copyright Statement
Copyright (C) The Internet Society (1998,1999,2000,2001). All Rights
Reserved
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
Herriot, et al. Expires May 19, 2002 [page 100]
INTERNET-DRAFT IPP: Event Notifications and Subscriptions Nov 19, 2001
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS 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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Herriot, et al. Expires May 19, 2002 [page 101]
