I've created a short (12-page) IPP Notification Model paper for discussion
on the DL and the IPP telecon, this Wednesday, 8/4/99, 10-12 PDT (1-3 EDT).
This model will allow us to agree on the model semantics for notification
before updating the detailed specification. The .pdf is much more readable
and has line numbers.
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-model-990802.docftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-model-990802.pdfftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-model-990802.txt
There are four issues embedded in the document:
ISSUE 1: Agreed that we don't want the Get-Printer-Subscriptions operation
to return the
Subscription objects associated with Jobs, correct?
ISSUE 2: or is it was simpler for the Get-Printer-Subscriptions operation
to always return all of the attributes of the Subscription object and not
have "requested-
attributes"?
ISSUE 3: We don't really need a parallel Get-Job-Subscriptions
operation, since a client can use either Get-Job-Attributes or Get-Jobs
to request the Job's "subscription-ids" attribute and then do a Get-
Subscription-Attributes for each, ok?
ISSUE 4: or is it simpler for the Get-Subscription-Attributes operation to
always
return all of the attributes of the Subscription object, since there are not
too many?
Here is the plain text version of the document:
IPP Notification Model
From: Tom Hastings
Date: 8/02/99
File: ipp-notification-model-990802.doc
There are 4 issues highlighted like this that need to be resolved.
This paper uses object modeling techniques to describe the current IPP
Notification Specification object model (July 22, 1999):
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-990722.pdf
and the proposed new object model that introduces the Subscription
object as an OPTIONAL object when implementing notification. In other
words, notification can be implemented with or without the Subscription
object. Review of this object model before writing the complete spec
will help speed up the production of the spec and will also help with
the understanding of the semantics. I suggest that this modeling be
kept in the final spec in some form similar to this paper.
NOTE - In this model document, the notation [ ] indicates that the
sender (client in a request, IPP object in a response, notification
sender in a notification) MAY omit the attribute inside the square
brackets. For simplicity, the conformance requirements for attribute
support are not indicated in this document.
1 Current IPP Notification Operations
The current IPP Notification object model (July 22, 1999) consists of
the Printer object and the Job object. The following operations are
defined for each of the object targets:
1.1 Printer object - current
Printer object target: salient inputs beside printer-
uri:
job creation operations recipients, [events,] [user-data]
Subscribe-Printer recipients, [events,] [lease-time]
Get-Printer-Attributes [requested-attributes]
Renew-Printer-Subscription [lease time]
Get-Printer-Subscriptions [my-subscriptions]
Unsubscribe-Printer subscription-id
1.2 Job object
Job object target: salient inputs besides job-id:
Subscribe-Job recipients, [events]
Get-Job-Attributes [requested-attributes]
Unsubscribe-Job subscription-id
2 New IPP Notification Operations
The Printer, Job, and (new) Subscription object targets have the
following operations defined for use with notification:
2.1 Printer object
Printer object target: salient inputs beside printer-uri:
job creation operations recipients, [events,] [user-data,]
[subscription-ids]
Get-Printer-Attributes [requested-attributes]
Get-Printer-Subscriptions[my-subscriptions]
2.2 Job object
Job object target: salient inputs besides job-id/job-
uri
Get-Job-Attributes [requested-attributes]
2.3 Subscription object - new OPTIONAL package
Subscription object related: salient inputs besides printer-uri:
Create-Subscription recipients, [events,] [user-data,]
[lease-time,] [job-id or printer-
uri]
Get-Subscription-Attributes subscription-id, [requested-
attributes]
Renew-Subscription subscription-id, [lease time]
Cancel-Subscription subscription-id
3 Notification attributes defined for each object
The following notification attributes are defined for each of the
Printer, Job, and (new) Subscription objects. Attributes and objects
not in the current, July 22, spec are labeled as "new":
3.1.1Printer object notification attributes
Printer object attributes: set by:
printer-trigger-event (type2 keyword) System - event
occurring
printer-trigger-message (text(255)) System - event
occurring
printer-trigger-time (integer(MIN:MAX)) System - event
occurring
printer-trigger-date-time (dateTime) System - event
occurring
previous-printer-state (type1 enum) System - event
occurring
printer-state-reasons-added (1setOf type2 keyword) System - event
occurring
printer-state-reasons-deleted (1setOf type2 keyword) System - event
occurring
notify-recipients-schemes-supported (1setOf uriScheme) Administrator
notify-events-default (1setOf type2 keyword) Administrator
notify-events-supported (1setOf type2 keyword) Administrator
notify-lease-time-supported (rangeOfInteger(0:MAX)) Administrator
notify-lease-time-default (integer(0:MAX)) Administrator
max-number-of-subscriptions-supported (integer(1:MAX)) Administrator
3.1.2Job object notification attributes
Job object attributes: set by:
notify-recipients (1setOf uri) job creation operation
notify-events (1setOf type2 keyword) job creation operation
notify-user-data (octetString(255)) job creation operation
new: job-subscription-ids (1setOf integer(0:MAX)) job creation
operation and/or
subsequent Create-Subscription
0 indicates no Subscription
objects
job-trigger-event (type2 keyword) System - event occurring
job-trigger-message (text(255)) System - event occurring
job-trigger-time (integer(MIN:MAX)) System - event occurring
job-trigger-date-time (dateTime) System - event occurring
previous-job-state (type1 enum) System - event occurring
job-state-reasons-added (1setOf type2 keyword) System - event
occurring
job-state-reasons-deleted (1setOf type2 keyword) System - event
occurring
3.1.3Subscription object attributes (new)
Subscription object attributes: set by:
notify-recipients (1setOf uri) client - Create-Subscription
notify-events (1setOf type2 keyword) client - Create-Subscription
notify-user-data (octetString(255)) client - Create-Subscription
notify-lease-time (integer(0:MAX)) client - Create-Subscription
notify-lease-time-remaining (integer(0:MAX)) system -
Create-Subscription
0 means infinite (for jobs
only)
most-recent-sequence-number (integer(0:MAX)) system - event occurring
delivery-failure-count (integer(0:MAX)) system - event occurring
Note: The "notify-least-time" attribute is the number of seconds
granted for the subscription. It is used to restore the subscription on
the Restart-Job and Reprocess-Job operations.
The "notify-lease-time-remaining" attribute is the number of seconds
remaining in the lease. Internally, the implementation may have a more
absolute representation of when the least expires, but this relative
value is returned to help the client know how much more time is
remaining in the lease. A value of 0 is used for Subscriptions
associated with Jobs, since they don't have a lease, but depend on the
life time of the documents of the Job.
The "most-recent-sequence-number" attribute maintains the sequence
number that was delivered in the most recent notification for the
subscription.
The "delivery-failure-count" attribute is the number of transport
delivery failures in delivering a notification to any of the "notify-
recipients" using the transport indicated. Notification Recipients do
not respond to the Notification Source.
4 Notification Content
The notification content is the same for the current and new specs:
4.1 Basic Job Event Notification content
version-number
status-code (with the value: basic-job-event(600))
request-id (used as notification delivery sequence number)
job-printer-uri (uri)
job-id (integer(1:MAX))
job-trigger-event (type2 keyword)
[job-trigger-message* (text(255))]
job-trigger-time (integer(1:MAX))
[job-trigger-date-time (dateTime)]
job-state (type1 enum)
previous-job-state (type1 enum)
job-state-reasons (1setOf type2 keyword)
job-state-reasons-added (1setOf type2 keyword)
job-state-reasons-deleted (1setOf type2 keyword)
[subscription-id** (integer(1:MAX))]
** If the Subscription object is implemented, the "subscription-id" MUST
be supplied in the notification content.
4.2 Basic Printer Event Notification content:
version-number
status-code (with the value: basic-printer-event(601))
request-id (used as sequence number
printer-uri-supported (uri)
printer-trigger-event (type2 keyword)
[printer-trigger-message* (text(255))]
printer-trigger-time (integer(1:MAX))
[printer-trigger-date-time (dateTime)]
printer-state (type1 enum)
previous-printer-state (type1 enum)
printer-state-reasons (1setOf type2 keyword)
printer-state-reasons-added (1setOf type2 keyword)
printer-state-reasons-deleted (1setOf type2 keyword)
[subscription-id** (integer(1:MAX))]
** If the Subscription object is implemented, the "subscription-id" MUST
be supplied in the notification content.
5 REQUIRED Job Submission Subscription
As in the current notification spec (July 22, 1999), the usual method
for a client to associate one subscription with a Job is to specify the
subscription when the job is created. For a Job Submission
Subscription, the client supplies the following notification operation
attributes:
notify-recipients (1setOf uri) REQUIRED to support
[notify-events (1setOf type2 keyword)] REQUIRED to support
[notify-user-data (octetString(255))] OPTIONAL to support
5.1 REQUIRED operation requests and responses related to notification
This section lists the REQUIRED operation requests and response that
have some relation to notification. The section 6 lists the OPTIONAL
operation requests and responses associated with the OPTIONAL
Subscription object.
5.1.1Job Creation Operations (Create-Job, Print-Job, Print-URI, and
Validate-Job)
The following IPP/1.1 extension operation attributes are defined for use
with any of the job creation operations, including Validate-Job (which
doesn't create a job or subscription):
Request:
Group 1: Operation Attributes
["notify-recipients" (1setOf uri)
["notify-events" (1setOf type2 keyword)]
["notify-user-data" (octetString(255))]]
Response:
Group 1: Operation Attributes
5.1.2Get-Printer-Attributes
The Get-Printer-Attributes can be used to request the additional Printer
Description attributes that indicate the notification supported. See
section 3.1.1.
5.1.3Get-Printer-Subscriptions
The Get-Printer-Subscriptions operations returns Printer subscription
objects, i.e., ones associated with the Printer object or ones that have
not been associated with either a Printer or Job object. Subscription
objects that are associated with a Job object are not returned, since
there could be a large number of them associated with a large number of
jobs and the Job Subscription can be easily queried using the Get-Job-
Attributes or Get-Jobs operations to request the "subscription-ids"
attribute and then performing Get-Subscriptions operations.
ISSUE 1: Agreed that we don't want this operation to return the
Subscription objects associated with Jobs, correct?
Request:
Group 1: Operation Attributes
"attributes-charset"
"attributes-natural-language"
"printer-uri" (uri)
["requesting-user-name" (name(MAX))]
["limit" (integer(1:MAX))]
["requested-attributes" (1setOf type2 keyword)]
ISSUE 2: or is it was simpler just to always return all of the
attributes of the Subscription object and not have "requested-
attributes"?
["my-subscriptions" (boolean)]
Response:
Group 1: Operation Attributes
"status-code" (type2 enum)
"attributes-charset"
"attributes-natural-language"
["status-message" (text)]
["detailed-status-message" (text(MAX))]
["subscription-ids" (1setOf integer(1:MAX))]
Group 2: Unsupported Attributes
Group 3 to N:
<the requested Subscription Attributes for each
Subscription object
in a separate group>
ISSUE 3: We don't really need a parallel Get-Job-Subscriptions
operation, since a client can use either Get-Job-Attributes or Get-Jobs
to request the Job's "subscription-ids" attribute and then do a Get-
Subscription-Attributes for each, ok?
5.1.4Get-Job-Attributes
The Get-Job-Attributes can be used to request the additional Job
Description attributes that relate to notification. See section 3.1.2.
6 OPTIONAL Explicit Subscriptions and the Subscription object
This section describes the new notification object model that adds a
Subscription object which together with the Job and Printer object
provide the notification semantics. The Subscription object is
OPTIONAL. Without the Subscription object, the Job Submission
Subscription semantics are supported with only a single subscription per
job and no explicit Subscriptions for the Job or Printer object as
described in section 5.
6.1 Object Relationships
When the Subscription object is supported, it is created and associated
with one Printer object, one previously created Job object, or neither
(so that a subsequent job creation operation can perform the association
of the Job object with the Subscription object and possibly other
previously created Subscription objects).
The object relationships can be stated as follows:
The Printer object contains zero or more Subscription objects
A Subscription object is contained in one Printer object
A Subscription object is exactly one of:
associated with one Printer object (s1-s3)
associated with one previously created Job object (s5 and s6
are associated with job j1
s7 is associated with job j2)
not associated with either a Printer object or a Job object
(s4)
A Printer object is associated with zero or more Subscription
objects (p1 is associated with s1-s3)
A Job object is associated with zero or more previously created
Subscription objects (j1 is
associated with s5 and s6;
j2 is associated with s7
j3 is not associated with any s
objects)
A Subscription object cannot be contained in or associated with
more than one Printer object
A Subscription object cannot be associated with more than one Job
object
A Subscription object cannot be associated with both a Printer
object and a Job object
A Subscription object MUST be associated ONLY with jobs that are
contained in its Printer object
The object association relationships can be seen pictorially as (object
containment not shown):
Subscription objects Printer object
+----+ +------------+
| s1 |<---------------------------------------------->| |
+----++ | |
| s2 |<--------------------------------------------->| p1 |
+----++ | |
| s3 |<-------------------------------------------->| |
+----++ +------------+
| s4 | Job objects
+----++ +------+
| s5 |<---------->| |
+----++ | j1 |
| s6 |<--------->| |
+----++ +------++
| s7 |<--------->| |
+----+ | j2 |
| |
+------++
| |
| j3 |
| |
+------+
6.2 Extensions to Job Submission Subscriptions for Subscription object
Even when the Subscription object is supported, the usual method for a
client to associate one subscription with a Job is to specify the
subscription when the job is created. For a Job Submission
Subscription, the client supplies the following notification operation
attributes:
notify-recipients (1setOf uri) REQUIRED to support
[notify-events (1setOf type2 keyword)] REQUIRED to support
[notify-user-data (octetString(255))] OPTIONAL to support
If the implementation supports the Subscription operation, then the
Printer MUST create a Subscription object, duplicate these notification
operation attributes on it, and return subscription id of the
Subscription object in the job creation response. Otherwise, the
subscription couldn't be canceled for the job. If the implementation
does not support the Subscription object, then the notification
operation attributes remain only on the Job object.
If the client only supplies a "subscription-ids" attribute and does not
supply these explicit "notify-xxx" attributes, the Printer MUST copy
these three attributes from the first Subscription object identified in
the "subscription-ids" operation attribute. Then all clients will see
the subscription attributes of the first subscription on the Job object,
thereby simplifying client query of job-related notification
subscription information. When the client does not supply any "xxx-
notify" operation attributes in the job creation operation, the Printer
does not create any new Subscription objects.
6.3 Operation requests and responses related to the Subscription object
This section lists the operation requests and responses the MUST be
supported if the OPTIONAL Subscription object is supported and vice
versa.
6.3.1Job Creation Operations (Create-Job, Print-Job, Print-URI, and
Validate-Job)
The following IPP/1.1 extension operation attributes are defined for use
with any of the job creation operations, including Validate-Job (which
doesn't create a job or subscription):
Request:
Group 1: Operation Attributes
["subscription-ids" (1setOf integer(1:MAX))]
["notify-recipients" (1setOf uri)
["notify-events" (1setOf type2 keyword)]
["notify-user-data" (octetString(255))]]
Response:
Group 1: Operation Attributes
[subscription-ids (1setOf integer(1:MAX))]
Notes: The client MAY supply one or both of:
1. one or more subscription ids for previously created (but
unassociated) Subscription objects
2. explicit "notify-xxx" attributes
If the implementation supports the Subscription object and the client
supplies "notify-xxx" operation attributes, the Printer MUST create a
new Subscription object initialized with these "notify-xxx" operation
attributes and return the "subscription-ids" operation attribute with
the new subscription-id as the first value.
No lease time is requested or returned, since Subscription objects
associated with Jobs have no real lease. Instead the Subscription
object is maintained until the job completes and the document data is
deleted.
6.3.2Create-Subscription Operation
Request:
Group 1: Operation Attributes
"attributes-charset" (charset)
"attributes-natural-language" (naturalLanguage)
"printer-uri" (uri)
["requesting-user-name" (name(MAX))]
"notify-recipients" (1setOf uri)
["notify-events" (1setOf type2 keyword)]
["notify-user-data" (octetString(255))]
["notify-lease-time" (integer(0:MAX))]
["associated-job-id" (integer(1:MAX)) OR
"associated-printer" (boolean)]
Response:
Group 1: Operation Attributes
"status-code" (type2 enum)
"attributes-charset" (charset)
"attributes-natural-language" (naturalLanguage
["status-message" (text(255))]
["detailed-status-message" (text(MAX))
"subscription-id" (integer(1:MAX))
"notify-lease-time" (integer(0:MAX))
"notify-lease-time-remaining" (integer(0:MAX))
Group 2: Unsupported Attributes
Notes: A "notify-lease-time" and "notify-lease-time-remaining" of 0
means infinite for use with Subscriptions associated with Job objects,
since the life of the subscription is the same as for the documents in
the job.
The client MUST supply either "associated-job-id" or "associated-
printer" or neither one, but MUST NOT specify both, since a Subscription
object can be associated with at most one (Job or Printer) object.
The Printer object MUST return the "notify-lease-time" actually granted
which may be less than the requester requested if it was greater than
the MAX supported or more than the requester requested if it was less
than the MIN supported, as indicated in the Printer's "lease-time-
supported" (rangeOfInteger(0:MAX)) attribute.
The Printer object MUST return the "notify-lease-time-remaining" which
is the number of seconds remaining in the lease.
6.3.3Get-Subscription-Attributes
The Get-Subscription-Attributes can be used to request the Subscription
object attributes. See section 3.1.3.
Request:
Group 1: Operation Attributes
"attributes-charset"
"attributes-natural-language"
"printer-uri" (uri)
["job-id" (integer(1:MAX))]
["requesting-user-name" (name(MAX))]
"subscription-id" (integer(1:MAX))
["requested-attributes" (1setOf type2 keyword)]
ISSUE 4: or is it simpler just to always return all of the attributes of
the Subscription object, since there are not too many?
Response:
Group 1: Operation Attributes
"status-code" (type2 enum)
"status-message" (text)
"attributes-charset"
"attributes-natural-language"
Group 2: Unsupported Attributes
Group 3: <the requested Subscription object attributes>
Notes: A client MUST supply the "job-id" operation attribute, if the
Subscription object is associated with a Job. If the "job-id" operation
attribute is omitted, the "subscription-id" is assumed to apply to a
Subscription object associated with the Printer object or not associated
yet with either the Printer object or a Job object.
6.3.4Renew-Subscription
Group 1: Operation Attributes
"attributes-charset"
"attributes-natural-language"
"printer-uri" (uri)
"requesting-user-name" (name(MAX))
"subscription-id" (integer(1:MAX))
"notify-lease-time" (integer(0:MAX))
Response:
Group 1: Operation Attributes
"status-code" (type2 enum)
"attributes-charset"
"attributes-natural-language"
["status-message" (text(255))]
["detailed-status-message" (text(MAX))]
"notify-lease-time" (integer(0:MAX))
"notify-lease-time-remaining" (integer(0:MAX))
Group 2: Unsupported Attributes
Notes: The Printer object MUST return the "notify-lease-time" actually
granted which may be less than the requester requested if it was greater
than the MAX supported or more than the requester requested if it was
less than the MIN supported, as indicated in the Printer's "lease-time-
supported" (rangeOfInteger(0:MAX)) attribute.
The Printer object MUST return the "notify-lease-time-remaining" which
is the number of seconds remaining in the lease.
6.3.5Cancel-Subscription
Request:
Group 1: Operation Attributes
"attributes-charset"
"attributes-natural-language"
"printer-uri" (uri)
["job-id" (integer(1:MAX))]
["requesting-user-name" (name(MAX))]
"subscription-id" (integer(1:MAX))
Response:
Group 1: Operation Attributes
"status-code" (type2 enum)
"attributes-charset"
"attributes-natural-language"
["status-message" (text(255))]
["detailed-status-message" (text(MAX))]
Group 2: Unsupported Attributes
Notes: A client MUST supply the "job-id" operation attribute, if the
Subscription object is associated with a Job. If the "job-id" operation
attribute is omitted, the "subscription-id" is assumed to apply to a
Subscription object associated with the Printer object or not associated
yet with either the Printer object or a Job object.
6.4 Subscription object lease time
A Subscription object that is associated with a Printer object or is not
associated with any object has a lease time. When the lease time
expires, the Printer object MUST delete the Subscription object. A
subscriber is expected to renew such Subscriptions before the lease
expires. A Subscription object that is associated with a Job object has
no lease; instead the Printer object deletes Subscription object when it
deletes document data for the job. Thus if the job is in one of the
Retained states ('completed', 'canceled', or 'aborted') and a client
issues the Restart-Job or Reprocess-Job operation, the Printer
initializes the associated Subscription objects with new lease times.
A Subscription object that is associated with a Job does not have a
lease. Instead the life of the job is used instead. When the Job
completes (or is aborted or canceled), the documents may be retained for
a period of time so that a client can use the Restart-Job or Reprocess-
Job operation to perform the job again. In these cases, the
subscription(s) associated with the Job are automatically renewed. When
the Printer object deletes the Documents for a completed (aborted or
canceled) Job, then it MUST also delete any Subscription objects
associated with the Job.
6.5 Sequencing of Subscription object association with the Printer or a
Job object
Subscription object may be created before Job objects and vice versa.
All associations between Subscription objects and a Printer or a Job
object occurs when the second object instance is created by specifying
the first object instance that is to form the association. Therefore,
one and only one of the following rules for the timing and sequencing of
associating objects applies to each association:
1. A Subscription object is associated with its Printer object when
the Subscription object is created
2. A Subscription object is associated with a previously created Job
object when the Subscription object is created
3. A Subscription object is created without any association and a
subsequent Job object creation associates the Job object with (one
or more previously created, but unassociated) Subscription
object(s)
6.6 Not implementing the Subscription object
As an implementer option, only Job Submission Subscription need be
supported. In this case, the Subscription object and the Create-
Subscription, Cancel-Subscription, Renew-Subscription, and Get-Printer-
Subscriptions operations are not implemented. Thus no Explicit
subscriptions are provided. However, a Job Submission Subscription can
still specify Job events and/or Printer events, just as when the
Subscription object and the other operations are implemented.