INTERNET-DRAFT 6 ISSUES are highlighted like this. S. Isaacson Novell, Inc. J. Martin Underscore R. deBry Utah Valley State College T. Hastings Xerox Corporation M. Shepherd Xerox Corporation R. Bergman Dataproducts Corp. August 25, 1999 Internet Printing Protocol/1.0&1.1: Event Notification Specification Copyright (C) The Internet Society (1999). 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 extension to the IPP/1.0 & IPP/1.1 model that allows a client to subscribe to printing related events. Subscriptions include "Per-Job Submission subscription" and "Per-Printer subscriptions". One or more Per-Job Submission subscriptions are specified by the client when submitting a job. One or more Per-Printer subscriptions are created by performing separate explicit Create- Printer-Subscription operations on the Printer. Four other operations are defined for Per-Printer subscription objects: get attributes, get subscriptions, renew a subscription, and cancel a subscription. A subscription includes: the names of Job and/or Printer events, the Notification Recipient URL, the Notification content MIME type, possibly some opaque data and the charset and natural language. In addition, the Per-Printer subscription includes: the requested lease time and persistency for the subscription. When the event occurs, a notification is generated and delivered using the information specified in the subscription. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 1] Expires February 25, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 The full set of IPP documents includes: Design Goals for an Internet Printing Protocol [IPP-REQ] Rationale for the Structure and Model and Protocol for the Internet Printing Protocol [IPP-RAT] Internet Printing Protocol/1.1: Model and Semantics [IPP-MOD] Internet Printing Protocol/1.1: Encoding and Transport [IPP-PRO] Internet Printing Protocol/1.0: Implementer's Guide [IPP-IIG] Mapping between LPD and IPP Protocols [IPP LPD] 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. Operator and administrator requirements are out of scope for version 1.0. A few OPTIONAL operator operations have been added to IPP/1.1. 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 specifications, and gives background and rationale for the IETF working group's major decisions. The "Internet Printing Protocol/1.1: Model and Semantics", describes a simplified model with abstract objects, their attributes, and their operations that are independent of encoding and transport. It introduces a Printer and a Job object. The Job object optionally supports multiple documents per Job. It also addresses security, internationalization, and directory issues. 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. It 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 a new scheme named 'ipp' for identifying IPP printers and jobs. Finally, this document defines interoperability rules for supporting IPP/1.0 clients. The "Internet Printing Protocol/1.0: 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.0 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. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 2] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Table of Contents 1 Introduction.......................................................6 1.1Notification Overview..........................................6 2 Model for Per-Job and Per-Printer Subscription and Event Notification 9 2.1Model for Per-Job Subscription and Notification................9 2.2Model for Per-Printer Subscription and Notification...........10 2.3Relationship between the Printer object and the Notification Delivery Service..................................................11 3 Terminology.......................................................12 3.1Conformance Terminology.......................................12 3.2Other terminology.............................................12 4 Object Model for Notification.....................................15 4.1Object relationships..........................................16 5 Object attributes defined for Notification........................17 5.1"job-notify" (1setOf collection) Job Description attribute....17 5.2Subscription object attributes................................18 5.3Common Per-Job and Per-Printer Subscription attributes........19 5.3.1 notify-recipient (uri)...................................20 5.3.2 notify-events (1setOf type2 keyword).....................20 5.3.3 notify-content-type (mimeMediaType)......................23 5.3.4 subscriber-user-data (octetString(63))...................24 5.3.5 notify-attributes-charset (charset)......................24 5.3.6 notify-attributes-natural-languages (naturalLanguage)....24 5.3.7 request-id...............................................24 5.4Additional attributes for the Subscription object only........24 5.4.1 subscription-id (integer (1:MAX))........................24 5.4.2 notify-lease-expiration-time (integer(0:MAX))............25 5.4.3 printer-uri (uri)........................................25 5.4.4 subscriber-user-name (name(MAX)).........................25 5.4.5 notify-printer-up-time (integer(1:MAX))..................26 5.5Printer Description Attributes related to Notification........26 5.5.1 notify-schemes-supported (1setOf uriScheme)..............27 5.5.2 notify-events-default (1setOf type2 keyword).............27 5.5.3 notify-events-supported (1setOf type2 keyword)...........27 5.5.4 max-events-supported (integer(5:MAX))....................27 5.5.5 max-job-subscriptions-supported (integer(1:MAX)).........27 5.5.6 max-printer-subscriptions-supported (integer(0:MAX)).....27 5.5.7 notify-lease-time-supported (rangeOfInteger(0:MAX))......28 5.5.8 notify-lease-time-default (integer(0:MAX))...............28 5.5.9 persistent-jobs-supported (boolean)......................28 5.5.10persistent-subscriptions-supported (boolean).............28 5.5.11printer-state-change-time (integer(1:MAX))...............28 5.5.12printer-state-change-date-time (dateTime)................28 6 Notification Content..............................................29 6.1Notification content MIME media type formats..................29 Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 3] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 6.2Notification content attributes common to Job and Printer events 29 6.3Additional Notification content attributes for Job events only 31 6.4Additional Notification content attributes for Printer events only 32 7 Operations for Per-Job Subscriptions..............................32 7.1Job Creation Operations (Create-Job, Print-Job, Print-URI) and Validate-Job......................................................33 7.2Get-Printer-Attributes operation..............................34 7.3Get-Job-Attributes operation..................................34 7.4Set-Job-Attributes operation..................................35 8 Per-Printer Subscriptions and the Subscription object.............35 8.1Create-Printer-Subscription operation.........................35 8.2Get-Printer-Subscription-Attributes operation.................38 8.3Get-Printer-Subscriptions operation...........................39 8.4Renew-Printer-Subscription operation..........................39 8.5Cancel-Printer-Subscription operation.........................40 9 Comparison of Per-Job Submission Subscriptions versus Per-Printer Subscriptions........................................................41 10 Conformance Requirements........................................42 11 IANA Considerations.............................................42 12 Internationalization Considerations.............................42 13 Security Considerations.........................................43 14 Status Codes....................................................43 14.1 client-error-uri-notification-scheme-not-supported (0x04??)..43 14.2 server-error-too-many-subscriptions (0x04??).................44 14.3 server-error-too-many-events (0x04??)........................44 15 References......................................................44 16 Author's Addresses..............................................45 17 Appendix C: Full Copyright Statement............................46 Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 4] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Tables Table 1 - Summary of Per-Job Subscription operations..................7 Table 2 - Summary of Per-Printer Subscription operations..............8 Table 3 - Job object 'job-notify' colletion member attributes........18 Table 4 - Subscription object attributes.............................19 Table 5 - Printer Description attributes associated with Notification26 Table 6 - Common Job and Printer Notification content attributes.....30 Table 7 - Additional Notification content attributes for Job events only .................................................................31 Table 8 - Additional Notification content attributes for Printer events only.............................................................32 Table 9 - Member attributes of the "job-notify" collection operation attribute........................................................33 Table 10 - Conformance Requirements for Operations...................42 Figures Figure 1 - Client-Printer Per-Job Subscription and Notification Model.9 Figure 2 - Client-Server-Printer Per-Job Subscription and Notification Model............................................................10 Figure 3 - Client-Printer Per-Printer Subscription and Notification Model............................................................11 Figure 4 - Opaque Use of a Notification Service......................11 Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 5] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 1 Introduction This IPP notification specification is an extension to IPP/1.0 [RFC2568, RFC2569]. This document in combination with the following documents is intended to meet the notification requirements described in [ipp-not- req]: Internet Printing Protocol/1.0 & 1.1: "Collection Attribute Syntax" [ipp-coll] Internet Printing Protocol/1.0 & 1.1: "Job Progress Attributes" [ipp-prog] Internet Printing Protocol/1.0 & 1.1: "Notification Change History" [ipp-not-hist] The rest of this document is laid out as follows: - The rest of Section 1.1 is an overview of IPP Notification. - Section 2 is the model for network entities that use IPP notification, including clients (desktop and servers), IPP Printers (servers and devices), and Notification Recipients. - Section 3 is the terminology used throughout the document. - Section 4 is the object model for notification, including Job, Printer, and Subscription objects. - Section 5 defines the notification attributes for each of the Job, Printer, and Subscription objects. - Section 6 defines the content of Human Consumable and Machine Consumable Event Notifications. - Sections 7, 8, and 9 define the Per-Job and Per-Printer Subscription mechanisms. - Section 10 and 11 define the conformance requirements and IANA requirements, respectively. - Section 12 - 14 cover Internationalization, Security, and Status codes. 1.1 Notification Overview A client can establish an event notification subscription so that when one of the specified events occurs, an asynchronous Notification is sent to a specified Notification Recipient. One or more Per-Job Submission subscriptions are specified by the client when submitting a job. One or more Per-Printer subscriptions are created by performing separate explicit Create-Printer-Subscription operations on the Printer. A Per-Job or Per-Printer subscription includes: 1. the names of Job and/or Printer events that are of interest to the Notification Recipient Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 6] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 2. the delivery method and address to use to deliver the notification to one Notification Recipient 3. whether Human Consumable or Machine Consumable notification content is to be sent 4. some opaque data that the subscriber wants to be send to the Notification Recipient in the Notification, perhaps to identify either the subscriber or the ultimate recipient 5. the charset to use in the Notification, if it is to be different than the one used in the request that created the subscription 6. the natural language to use in the Human Consumable Notification, if it is to be different than the one used in the request that created the subscription In addition, a Per-Printer subscription includes: 7. the requested lease time in seconds for the subscription 8. whether or not the subscription is requested to be persistent across power cycles. For Per-Job subscriptions, a client requests job and printer event notification using the "job-notify" operation attribute when creating a job with any of the Job Creation operation: Print-Job, Print-URI, and Create-Job. The "job-notify" operation attributes may be submitted to the Validate-Job in order to be validated. The "job-notify" operation attribute is copied to the Job object as a Job Description attribute and so may be queried using the Get-Job-Attributes and Get-Jobs operations (see [ipp-mod]). Also this "job-notify" Job Description attribute may be changed using the Set-Job-Attributes (see [ipp-set2]). The "job- notify" operation attribute contains one or more collection values, each consisting of a number of member attributes the specify a subscription, so that a Job can contain more than one Per-Job subscription. The 'collection' is a new attribute syntax (see [ipp-coll]). Table 1 summarizes the Per-Job Subscription operations and their salient input operation attributes. All operations are REQUIRED, except the Set-Job- Attributes operation. Table 1 - Summary of Per-Job Subscription operations Operation: salient inputs besides printer-uri: Print-Job, 1setOf {recipient, [events,] [content-type,] Print-URI, [user-data,] [charset,] [natural-language]} Create-Job Validate-Job 1setOf {recipient, [events,] [content-type,] [user-data,] [charset,] [natural-language]} Get-Job- job-id, [requested-attributes] Attributes Set-Job- job-id, 1setOf {[recipient,] [events,] Attributes [content-type,] [user-data,] [charset,] [natural-language]} Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 7] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 For Per-Printer subscriptions, a client requests job and printer event notification using new operations independent of any job. The Printer keeps each subscription in a separate Subscription object which is similar to a Job object in its operations and security. The Get- Printer-Attributes (see [ipp-mod]) returns the supported notification capabilities supported. The Create-Printer-Subscription operation creates an instance of the Subscription object supplying these new operation attributes and returns a subscription-id (analogous to a job- id for a Job object). These operation attributes are copied to the Subscription object as Subscription Description attributes and so may be queried using the Get-Subscription-Attributes and Get-Subscriptions operations. The subscriber requests a lease time for each Per-Printer subscription which MAY be infinite. The Printer grants a lease time according to its configured policy. A client MUST renew the Subscription before the granted lease time expires using the Renew- Printer-Subscription operation. Table 2 summarizes the Per-Printer- Subscription operations and their salient input operation attributes. Table 2 - Summary of Per-Printer Subscription operations Operation: salient inputs beside printer-uri: Get-Printer-Attributes [requested-attributes] Create-Printer- recipient, [events,] [content- Subscription type,][user- data,][charset,][natural- language,][lease-time-requested,] [persistence-requested] Get-Printer- subscription-id, [requested- Subscription-Attributes attributes] Get-Printer- [my-printer-subscriptions,] Subscriptions [requested-attributes] Renew-Printer- subscription-id, [lease time- Subscription requested] Cancel-Printer- subscription-id Subscription There are two steps that IPP notification must take regarding each event . an internal event recording, and an external notification: 1) As an events occurs, the printer internally records in the job objects and the printer objects those events which are required to be supported by the system and those that are subscribed to by a notification recipient. 2) As an events occurs, the Printer searches the set of subscriptions for any interest in that event. As the Printer finds that some notification recipient is interested in that event (the notification recipient is subscribed to the event), the "request- id" sequence number for that event is incremented and a notification is generated and delivered using the methods and target addresses identified in the subscription. The "request-id" Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 8] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 sequence number permits a Notification Recipient to detect duplicate notifications due either to duplicate subscriptions or retries and to detect dropped notifications. 2 Model for Per-Job and Per-Printer Subscription and Event Notification 2.1 Model for Per-Job Subscription and Notification Per-Job subscriptions are created by a client (desktop or server acting as a client) as part of creation of the job in an IPP Printer (printing device or server).. More than one subscription may be submitted with a job. The IPP Printer object delivers a Notifications to the Notification Recipient supplied by the Client in each subscription. A Notification Recipient can be the Job submitter or a third party. Figure 1 shows the Per-Job subscription notification model for a simple Client - Printer relationship. embedded printer: output device or server desktop or server +---------------+ +--------+ | ########### | | client |---IPP job submission------># Printer # | +--------+ Per-Job subscription | # Object # | | #####|##### | +---------+ +-------|-------+ |recipient|<-----Notifications-------------+ +---------+ (Job and/or Printer events) Figure 1 - Client-Printer Per-Job Subscription and Notification Model Figure 2 shows a (spooling or non-spooling) Server that implements two Printer objects (1 and 2) that represent two devices. The devices A and B in turn each implement an IPP Printer object (3 and 4, respectively). The Server implementation has three choices for how to support Per-Job subscriptions to the client (and itself): 1.forward the Per-Job subscriptions to the down stream IPP Printer and let it perform the notification directly to the Notification Recipients supplied by the Client (Notifications(C)) and use Per-Printer Subscriptions for the Server's own purposes. 2.save the client-supplied Per-Job subscription on the Job object in the server and substitute its own Per-Job subscription with the Server as the Notification Recipient (Notifications(B)). Then the Server relays Notifications to the client-supplied Notification Recipients (Notifications(A)). 3.A combination of 1 and 2 in which the Server adds its own Per- Job subscriptions to those supplied by the client. Thus the IPP Job that goes to Printer object 4 has a combination of subscription information from both the Client and the Server. This latter approach is sometimes called "piggy-backing" because Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 9] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 the Server is adding its Per-Job subscription information to that supplied by the client. Piggy-backing is especially useful, if device B also accepts (IPP or non-IPP) requests from other servers. Then when all the jobs from Server S have been completed by device B, there will be no more Job events sent to Server S. (Server S could still maintain a long term Per- Printer subscription with Printer D to that Server S can have Printer B's state track (shadow) that of Printer D or Server S could poll Printer D when queried about Printer B). device A server S +------------+ +------------+ | ###########| +--------+ IPP Job | ###########| IPP Job | # Printer #| | client |--submission---># Printer #|---submission-----># Object 3#| +--------+ Per-Job | # Object 1#| Per-Job | ###########| subscription | ###########| subscription +------------+ | | device B +--------+ IPP Job | ###########| +------------+ | client |--submission---># Printer #| IPP Job | ###########| +--------+ Per-Job | # Object 2#|---submission-----># Printer #| subscription | ###|#######| Per-Job | # Object 4#| +----|---^---+ subscription | ####|#|####| +--------+ | | +-----|-|----+ |Notific-|<-Notifications(A)-+ +--- Notifications(B)-------+ | |ation Re|<----------------Notifications(C)--------------------+ |cipient | +--------+ Figure 2 - Client-Server-Printer Per-Job Subscription and Notification Model 2.2 Model for Per-Printer Subscription and Notification Per-Printer subscriptions are created by a client (an end user, an operator, or a server acting as a client) using a Create-Printer- Subscription operation that is independent of Job Submission. The Printer object (printing device or server) creates a Subscription object to hold the attributes supplied by the subscriber. The client creates separate Per-Printer subscriptions if more than one Notification Recipient is desired. The Printer delivers Notifications to the Notification Recipient specified by each Per-Printer subscription. A Notification Recipient may be the subscriber or a third party. Figure 3 shows the Per-Printer subscription notification model for the Client - Printer relationship where the client may be an end user, an operator, or a server acting as a client. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 10] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 desktop or server server or printing device +---------------+ +--------+ | ########### | | client |---IPP job submission------># Printer # | +--------+ Per-Job subscription | # Object # | | #####|##### | +---------+ +-------|-------+ |recipient|<-----Notifications-------------+ +---------+ (Job and/or Printer events) Figure 3 - Client-Printer Per-Printer Subscription and Notification Model 2.3 Relationship between the Printer object and the Notification Delivery Service The IPP Notification model does not mandate that the IPP Printer object implement the full semantics of subscription, report generation, and multiple delivery methods itself. An implementation may be configured to use some other notification service. Figure 4 shows this partitioning. Create Request with ########### ----Subscriptions-------------------># IPP # # Printer # # Object # ########### | *******|********** * Subscriptions * * & Events * * | * +----v---------+ * | notification | <---Job and Printer ------*---------| service | Notifications * +--------------+ * * *** = Implementation configuration opaque boundary Figure 4 - Opaque Use of a Notification Service If an IPP Printer does use some other notification service, it MAY do so in either of two ways: 1.The IPP Printer forwards the Subscriptions and the Events to the other notification service which then sends the Notifications to the proper Recipients. 2.The IPP Printer keeps the subscriptions and uses them to send Notifications to the other notification service which forwards Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 11] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 them to Recipients that have also subscribed directly with the other notification service. Examples of this latter approach are paging and immediate messaging services. In any case, the interface between the IPP Printer and the other notification service is outside the scope of this document and is intended to be transparent to this specification. 3 Terminology This section defines terminology used throughout this document. 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 to this specification. These terms are defined in [ipp-mod section 13.1 on conformance terminology, most of which is taken from RFC 2119 [RFC2119]. 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 notification specification is implemented". Likewise, the term RECOMMENDED means "RECOMMENDED if this notification specification is implemented". READ-ONLY - indicates an attribute that MUST NOT be settable using the Set-Job-Attributes or Set-Printer-Attributes operations (see [ipp-set2]). 3.2 Other terminology Job Submitting End User - A human end user who submits a print job to an IPP Printer. This person may or may not be within the same security domain as the Printer. This person may or may not be geographically near the printer. Administrator - A human user who established 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. Job Submitting Application - An application (for example, a batch application), acting on behalf of a Job Submitting End User, which submits a print job to an IPP Printer. The application may or may not be within the same security domain as the Printer. This application may or may not be geographically near the printer. Security Domain - The set of network components which can communicate without going through a proxy or firewall. A security domain may be geographically very large, for example - anyplace within IBM.COM. IPP Client (or client) - The software component (desktop or server) that sends an IPP operation request to an IPP Printer object (server or printing device) and accepts the resulting operation response from the IPP Printer object.. Job Recipient - A human who is the ultimate consumer of the print job. In many cases this will Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 12] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 be the same person as the Job Submitting End User, but need not be. Example: If I use IPP to print a document on a printer in a business partner's office, I am the Job Submitting End User, while the person I intend the document for in my business partner's office is the Job Recipient. Since one of the goals of IPP is to be able to print near the Job Recipient of the printed output, we would normally expect that person to be in the same security domain as, and geographically near, the Printer. However, this may not always be the case. For example, I submit a print job across the Internet to a Kinko's print shop. I am both the Submitting End User and the Job Recipient, but I am neither near nor in the same security domain as the Printer. Job Recipient Proxy - A human acting on behalf of the Job Recipient. In particular, the Job Recipient Proxy physically picks up the printed document from the Printer, if the Job Recipient cannot perform that function. The Proxy is by definition geographically near and in the same security domain as the printer. Example: I submit a print job from home to be printed on a printer at work. I'd like my secretary to pick up the print job and put it on my desk. In this case, I am acting as both Job Submitting End User and Job Recipient. My secretary is acting as a Job Recipient Proxy Notification Subscriber (or Subscriber) - A client that requests the IPP Printer to send Event Notifications to one or more Notification Recipients. A Notification Subscriber may be: 1.a Job Submitting End User or Job Submitting Application (desktop or server) that is submitting a job or 2.an End User, an Operator, or an Administrator that is not submitting a job. Subscription - A request by a Notification Subscriber to the IPP Printer to send Event Notifications to a specified Notification Recipient when the event occur. A Subscription is represented as a set of attributes that indicate the "what, where, who, and how" for notification. Notifications are generated for certain events (what) and delivered using various delivery methods (how) to certain addresses (where and who). Per-Job Subscription - A Subscription that a client specifies as part of a create job operation (Print-Job, Print-URI, Create-Job), or a Validate-Job operation. Per-Printer Subscription - A Subscription that a client specifies using an explicit Create-Printer-Subscription operation, that is attached to a Printer object. Notification Source - The entity that sends Event Notifications. Notification Recipient - The entity identified as a recipient within a subscription that receives IPP Notifications about Job and/or Printer events. A Notification Recipient may be a: Job Submitting End User, Job Submitting Application (desktop or server), Job Recipient, Job Recipient Proxy, Operator, or Administrator, etc., and their representative or log file or usage statistics gathering application or other active or passive entities. Notification Recipient Agent - A program which receives Notifications on behalf of the Notification Recipient. The agent Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 13] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 may take some action on behalf of the recipient, forward the notification to the recipient via some alternative means (for example, page the recipient), or queue the notification for later retrieval by the recipient. Event - An event is some occurrence (either expected or unexpected) within the printing system of a change of state, condition, or configuration of a Job or Printer object. A property of an event is that it only occurs at one instant in time and does not span the time the physical event takes place. For instance, jam-occurred and jam-cleared are two distinct events. The jam-occurred event is reported only when the jam initially occurs and only if there is one or more event subscriptions outstanding for that event. Events can be classified along two dimensions: - Either as Job Events or Printer Events, and - Either as Errors, Warnings, or Reports A Job event is some interesting state change in the Job object, and a Printer event is some interesting change in the Printer object. A report event is purely informational, such as 'job-completed' or 'accepting-jobs'. A warning is not serious and processing continues. An error is serious and either the job is aborted or the printer stops. These are typical uses of the terms report, warning, and error, although the actual usage is implementation dependent. An event occurs for a job or printer whether any entity has subscribed to be notified for that event or not. A notification is only generated depending on the set of subscriptions outstanding. Notification - When an event occurs, a Notification is generated that fully describes the event (what the event was, where it occurred, when it occurred, etc.). Notifications are delivered to each Notification Recipient that has a subscription that includes the event, if any. The Notification is delivered to the address of the Notification Recipient using the notification delivery method defined in the subscription. However, a Notification is sent ONLY if there is a corresponding subscription. Notification Delivery Method (or Delivery Method for short) - Notifications are delivered using a method, such as email, TCP/IP, etc. Immediate Notification - Notifications that are delivered using a delivery method which is not store-and-forward (e.g. TCP connection, UDP datagram). This can be on the order of several minutes subject to network latency. Store and Forward Notification - A Notification which are not necessarily delivered to Notification Recipients immediately, but is queued for delivery by some intermediate network application, for later retrieval. Email is an example of a store and forward notification delivery method. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 14] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Human Consumable Notification - Notifications that are intended to be consumed by human End Users only. They are simple text that has been localized for the Notification Recipient as specified in the subscription. Programs are not intended to parse Human Consumable Notification, since it is localized and the content depends on implementation. There is no standardized format. Machine Consumable Notification - Notifications that are intended for consumption by a program only. They use the encoding of an IPP response. The Notification Recipient must localize the contents, if displaying it to a human. 4 Object Model for Notification This section describes the notification object model that adds a REQUIRED Subscription object which together with the Job and Printer object provide the complete notification semantics. Per-Job subscriptions do not use the Subscription object. Instead, a Job can have one or more Per-Job subscription which is represented entirely as a single Job attribute. Each Per-Job subscription is represented as a collection value of the "job-notify" Job attribute. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 15] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 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 ++---+----++ | | | j2 | | | +----+----| | s5 | s6 | s5 and s6 are Per-Job subscriptions ++---+----++ | | | j3 | | | | | +---------+ 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 subscriptions (not objects) and can identify Printer and/or Job events. 4.1 Object relationships The object relationships can be stated as follows: 1. The Printer object contains zero or more Subscription objects (p1 contains s1-s3 Subscription objects). 2. Each Subscription object (s1, s2, and s3) is contained in one Printer object (p1) and represents one Per-Printer subscription. 3. Each "Per-Printer" Subscription object identifies one or more Job and/or Printer events. Such Job events are for all jobs on the Printer. Such Printer events are for any Printer event, no matter which job is processing and when no jobs are processing. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 16] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 4. Each "Per-Job" subscription (not an object by itself, but is attributes of the Job object) identifies one or more Job and/or Printer events. Such Job events are only for this job (different than "per-Printer" Subscriptions). Such Printer events are for any Printer event, no matter which job and when no jobs are processing (same as for "per-Printer" Subscriptions). 5. A Job object contains zero or more Per-Job subscriptions (not an object). Job j1 contains Per-Job subscription s4, Job j2 contains Per-Job subscription s5 and s6, and Job j3 does not contain a Per- Job subscription. 6. A Subscription object cannot be contained in or associated with more than one Printer object. 7. A Per-Job subscription cannot be contained in or associated with more than one Job object. 5 Object attributes defined for Notification The following notification attributes are defined for each of the Printer, Job, and Subscription objects. The definitions of the object attributes are specified here so that they can be referred to from the subsequence definitions of the operations that set them. 5.1 "job-notify" (1setOf collection) Job Description attribute In order to permit more than one Per-Job subscription, each subscription is represented as a collection value of the "job-notify (1setOf collection)" Job Description attribute. An implementation MUST support at least one collection value of the "job-notify" attribute. Table 3 lists the member attributes of the "job-notify" attribute. Section 5.3 defines each of the "job-notify" member attributes. The "job-notify" Job Description attribute MAY be modified by the Set- Job-Attributes operation (see section 7.4) in which case all of its member attributes are replaced and the READ-ONLY "request-id" member attribute is reset with a value of '0' (see section 5.3.7). Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 17] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Table 3 - Job object 'job-notify' colletion member attributes Job object attributes: Print set by: er suppo rt notify-recipient (uri) R job creation operation, Set-Job-Attributes notify-events (1setOf type2 R job creation operation, keyword) Set-Job-Attributes notify-content-type R job creation operation, (mimeMediaType) Set-Job-Attributes subscriber-user-data R job creation operation, (octetString(63)) Set-Job-Attributes notify-charset (charset) O job creation operation, Set-Job-Attributes notify-natural-languages O job creation operation, (naturalLanguage) Set-Job-Attributes request-id (integer(0:MAX)) R Printer - event occurring 5.2 Subscription object attributes Each Per-Printer subscription is contained in a separate Subscription object. An implementation MUST support at least one Subscription object instance. Table 4 lists the Subscription attributes defined for the Subscription object. Sections 5.3 and 5.4 define each of the Subscription attributes. All of the Subscription object attributes are READ-ONLY. They are set by other operations. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 18] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Table 4 - Subscription object attributes Subscription object attributes: Print READ-ONLY, set by: er suppo rt notify-recipient (uri) R client - Create-Printer- Subscription notify-events (1setOf type2 R client - Create-Printer- keyword) Subscription notify-content-type R client - Create-Printer- (mimeMediaType) Subscription subscriber-user-data R client - Create-Printer- (octetString(63)) Subscription notify-charset (charset) O client - Create-Printer- Subscription notify-natural-languages (1setOf O client - Create-Printer- naturalLanguage) Subscription request-id (integer(0:MAX)) R Printer - event occurring Not in a Per-Job subscription: subscription-id (integer(1:MAX)) R Printer - Create-Printer- Subscription notify-lease-expiration-time R Printer - Create-Printer- (integer(0:MAX)) Subscription, Renew-Printer- Subscription printer-uri (uri) R Printer - Create-Printer- Subscription subscriber-user-name (name(MAX)) R Printer - Create-Printer- Subscription notify-printer-up-time R Printer - returned by (integer(1:MAX)) Get-Printer-Subscription- Attributes and Get- Printer-Subscriptions 5.3 Common Per-Job and Per-Printer Subscription attributes The following sub-sections define attributes that are in common to both Per-Job and Per-Printer subscriptions, i.e., are member attributes of the "job-notify" collection Job Description attribute and are Subscription object attributes. Section 5.4 defines additional attributes that are only Subscription object attributes. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 19] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 5.3.1 notify-recipient (uri) This REQUIRED attribute describes both where (the address of the Notification Recipient) and how (the delivery method) notifications are to be delivered to the Notification Recipient when any of the events specified in the "notify-events" attribute occur. There are potentially many different notification delivery methods for IPP notifications, standardized as well as proprietary. This document does not define any of these delivery mechanisms; they will each be described in separate complementary documents. Each of the notification delivery method documents must provide at least the following information: 1) The URI scheme used. 2) The supported and default delivery format, and if not one of the specified types in Section 5.3.3, description of the notification content. 3)Any content length restrictions imposed by the delivery protocol. 4) The latency of the delivery protocol used. 5)The reliability of the transport and delivery protocol used. 6) The security aspects of the transport and delivery protocol used, e.g. how it is handled in firewalls. 7) How the delivery protocol is initiated, e.g. does it have to be initiated by the receiving user (pull), or is it initiated by the notification service (push). ISSUE 1: Once a number of delivery solutions have been developed and evaluated, we may want to make one or several of them REQUIRED for implementation to ensure a minimum set of interoperability. Which one or ones should be REQUIRED? 5.3.2 notify-events (1setOf type2 keyword) This REQUIRED attribute identifies the job and/or printer events that are to be delivered to the Notification Recipient as Notifications as defined in section 6. If the client did not supply this attribute when supplying the subscription, the Printer object populates this attribute with its "notify-events-default" attribute value (see section 5.5.2). There are both job events and printer events. Each job and printer event is assigned a keyword to use in this attribute and in the Notification. The events are defined to be disjoint. A Printer MUST support the events indicated as "REQUIRED". The standard job event keyword values are: 'none': REQUIRED - no notifications of any events (an IPP object can use this value to indicate that it is configured not to support event notification; a client would not subscribe to this event). Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 20] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 'job-created': REQUIRED - the Printer object has accepted a job creation operation (Print-Job, Print-URI, or Create-Job) and the job's "time-at-creation" attribute value is set (see [ipp-mod] section 4.3.14.1). The Printer puts the job in the 'pending', 'pending-held' or 'processing' states. Note: This event is separate from the 'job-state-changed' event so that it can be subscribed to without having to get every job state change event for a Notification Recipient that is only interested in when the job is first created. '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 [ipp-mod] section 4.3.14). Note: This event is separate from 'job-state-changed' so that it can be subscribed to without having to get every job state change event for a Notification Recipient that is only interested in when the job is completed. 'job-state-changed': REQUIRED - the job has changed from any state to any other state and/or a value has been added or removed from the job's "job-state-reasons" attribute, except when the job is created or when the job moves to any of the "completed" job states ('completed', 'aborted', or 'canceled'). This event also indicates that one or more values have been added to or removed from the Job's "job-state-reasons" attribute, such as 'job-queued' or 'job-printing', whether or not the job's state has changed. If job state reasons are added when the job is created, only the 'job-created' event is generated, in order to keep the events disjoint. If job state reasons are added or removed when the job is completed, only the 'job-completed' event is generated, in order to keep the events disjoint. A client that wants to subscribe to all job state changes, including creation and completion, includes the 'job-created', 'job-state-changed', and 'job-completed' in the notification subscription. When a job is finally removed from the Job History (see [ipp-mod] 4.3.7.1) no event is generated, i.e., neither a 'job-state-changed' event nor a 'job-purged' event is generated. '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 non-READ-ONLY Job attributes have changed, such as any of the job template attributes or the "job-name" attribute. Typically, such a change is the result of the user or the operator performing a Set-Job-Attributes operation (see [ipp-set2]) 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-purged': OPTIONAL - when a 'not-completed' job (i.e., not 'completed', 'canceled', or 'aborted') was purged from the printer using the Purge-Jobs operation. No event, including this event, is Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 21] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 generated when a job is aged out of the Job History or moved out explicitly with the Purge-Jobs operation. 'job-progress' - a sheet or copy has completed. See separate [ipp- prog] spec. The standard Printer event keywords values are: 'none': REQUIRED - no notification of any events (an IPP object can use this value to indicate that it is configured not to support event notification; a client would not subscribe to this event). 'printer-restarted': OPTIONAL - when the printer is powered up or the Restart-Printer operation is performed (see [ipp-set2]). Note: This event is separate from the 'printer-state-changed' event so that it can be subscribed to without having to get every printer state change event, for a Notification Recipient that is only interested in when the Printer first comes up. 'printer-shutdown': OPTIONAL - when the device is being powered down or the Shutdown-Printer operation has been performed with either power-off or standby options (see [ipp-set2]). Note: This event is separate from 'printer-state-changed' so that it can be subscribed to without having to get every Printer state change event, for a Notification Recipient that is only interested in when the Printer is powered down or shutdown. 'printer-state-changed': REQUIRED - the Printer changed state, i.e., the value of the Printer's "printer-state", "printer-state-reasons" (whether "printer-state" changed or not), and/or "printer-is- accepting-jobs" attributes changed, except when the Printer starts up or is shutdown. If printer state reasons are added when the Printer is started up, only the 'printer-restarted' event is generated, in order to keep the events disjoint. If printer state reasons are added or removed when the printer is powered-down or shutdown, only the 'printer-shutdown' event is generated, in order to keep the events disjoint. A client that wants to subscribe to all printer state changes, including restart and power-down/shutdown, includes the 'printer- restarted', 'printer-state-changed', and 'printer-shutdown' in the notification subscription. '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 both an actual media change and filling an empty input tray with the same or different media. The client must check the "media-ready" Printer attribute (see [ipp- mod] section 4.2.11) separately to find out what new media was loaded or filled. 'printer-config-changed': OPTIONAL . when the configuration of a Printer has changed, i.e., the value of the "printer-message-from- operator" or any non-READ-ONLY Printer attribute has changed, except for "media-ready" (which has its own event), whether through the Set-Printer-Attributes operation or by other means and whether initiated by a human or not. For example, any "xxx-supported", "xxx-default", "printer-message-from-operator", etc. values have changed. The client has to perform a Get-Printer-Attributes to Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 22] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 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. 'printer-queue-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). 'printer-no-longer-full': OPTIONAL . when the Printer can now accept a Print-Job, Print-URI, Create-Job, Send-Document, or Send-URI request. This event is used when there is more than one client feeding a printer/server (fan-in), and the Printer may still be printing but has acquired more buffer space to accept jobs. This event only occurs when the Printer did not have room to accept jobs previously and rejected a Print-Job, Print-URI, Create-Job, Send- Document, or Send-URI operation. 'printer-almost-idle': OPTIONAL . when the Printer needs another Job in order to stay busy. This event is used when a spooler is feeding more than one printer/server (fan-out), and the spooler holds jobs until a Printer requests them, rather than committing jobs to IPP Printers before it is necessary. This event MAY be used by a Printer implementation to request a new job from any subscribers sufficiently ahead of time so that the device does not run out of work between jobs. 5.3.3 notify-content-type (mimeMediaType) This REQUIRED attribute specifies the type of content that is to be sent in the notifications. Thus the subscriber can control whether the event notification content is Human Readable or Machine Readable. Most delivery methods support both forms of content type and MUST define one of them as the default. If a delivery method only supports one form of content type, then that form is also the default. If the MIME media type registration permits a charset parameter, than such a specification MUST be used (instead of the "notify-charset" attribute) in order to indicate the charset to be used in the notification content. If the Subscriber did not supply this attribute when requesting the subscription, the Printer object populates this attribute from the default value defined for the delivery method. Standard mimeMediaType values are: 'application/ipp' - the Machine Consumable notification content using the 'application/ipp' MIME media type [ipp-mod] as defined in section 6. 'text/plain; charset=utf-8': A plain text document in ISO 10646 represented as UTF-8 [RFC-2044] as defined in section 6. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 23] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 5.3.4 subscriber-user-data (octetString(63)) This REQUIRED attribute holds opaque information being sent from the Subscriber to the Notification Recipient, such as the identify of the Subscriber or a path or index to some Subscriber information. Or it MAY contain a key that the Notification Recipient needs in order to process the Notification, such as the ultimate recipient, if the Notification Recipient is a general application that in turn forwards notifications. 5.3.5 notify-attributes-charset (charset) This OPTIONAL attribute specifies the charset to be used in the Notification content sent to the notification recipient. This attribute MUST NOT be used when the "notify-content-type" attribute value specifies the charset parameter in its MIME media type value. 5.3.6 notify-attributes-natural-languages (naturalLanguage) This OPTIONAL attribute specifies the natural language for the IPP object to use in the Notification content that is sent to the Notification Recipient. 5.3.7 request-id This REQUIRED READ-ONLY attribute holds the most recent request-id sequence number delivered in a Notification content to the Notification Recipient. A value of 0 indicates that no Notifications have been sent for this subscription. The first request-id sent for a subscription MUST be 1. Each Notification Recipient has its own monotonically increasing series of request-ids, i.e., no gaps, in order to be able to detect a missing notification. For a Per-Job subscription, "request-id" is a READ-ONLY member attribute of each collection value. All of the other member attributes (see section 5.1) are not READ-ONLY and MAY be modified by a Set-Job- Attributes operation (see 7.4). 5.4 Additional attributes for the Subscription object only The following sub-sections define additional attributes that are only for the Subscription object and have no counter part in Per-Job subscriptions. 5.4.1 subscription-id (integer (1:MAX)) This REQUIRED READ-ONLY Subscription object attribute uniquely identifies this Subscription object instance on this Printer. The Printer object, on acceptance of a Create-Printer-Subscription request, generates an ID which identifies the new Subscription object on that Printer. The Printer returns the value of the "subscription-id" attribute as part of the response to a Create-Printer-Subscription request. The 0 value is not included to allow for compatibility with "job-id" and with SNMP index values which also cannot be 0. It is RECOMMENDED that Per-Printer Subscription objects be persistent. Then the Subscription objects including the subscription-id remains unique across power-cycles. Even if an implementation does not make Per-Printer subscription objects persist, the implementation SHOULD make Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 24] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 every attempt not to re-use subscription ids that subscribers might still think are valid. In other words, the Printer SHOULD at least keep the next subscription-id to be assigned in non-volatile memory. 5.4.2 notify-lease-expiration-time (integer(0:MAX)) This REQUIRED READ-ONLY Subscription object attribute specifies the time in the future when the subscription lease will expire, i.e., the "printer-up-time" value at which the lease will expire. When the Printer object creates a Subscription object, it populates this attribute with the appropriate value. When the indicated time arrives, the Printer MUST delete the Per-Printer Subscription object. A client is able to extend a lease using the Renew-Printer-Subscription operation (see section 8.4). A value of 0 indicates an infinite time, if such a policy is supported as indicated in the "notify-lease-time- supported" (integer(0:MAX)) Printer Description attribute (see section 5.5.7) and the subscriber is authorized to request an infinite lease. Note: In order to compute the number of seconds remaining in a Per- Printer Subscription lease, a client can subtract the "notify-printer- up-time" Printer object attribute (see section 5.4.5) from the "notify- lease-time" Subscription object attribute. 5.4.3 printer-uri (uri) This REQUIRED READ-ONLY Subscription object attribute identifies the Printer object that created this Subscription object. When a Printer object creates a Subscription object, it populates this attribute with the Printer object URI that was used in the create request. This attribute permits a client to identify the Printer object URI that was used to create this Subscription object, i.e., what security scheme was used. 5.4.4 subscriber-user-name (name(MAX)) This REQUIRED READ-ONLY Subscription object attribute contains the name of the user that created the Subscription object. The Printer object sets this attribute to the most authenticated printable name that it can obtain from the authentication service over which the IPP operation was received. This attribute is intended to help a human user determine for which Per-Printer Subscriptions they are the Subscriber. Only if such is not available, does the Printer object use the value supplied by the client in the "requesting-user-name" operation attribute of the create operation (see [IPP-MOD] Sections 4.4.2, 4.4.3, and 8). ISSUE 2 - What is the value of the "subscriber-user-name" when the Subscriber is a server send a job to an IPP Printer? The original Job Submitting End User use name or some "user name" that identifies the Server? Note: The Printer object needs to keep an internal originating user id of some form, typically as a credential of a principal, with the Subscription object. Since such an internal attribute is implementation-dependent and not of interest to clients, it is not specified as a Subscription Description attribute. This originating Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 25] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 user id is used for authorization checks (if any) on all subsequent operations. 5.4.5 notify-printer-up-time (integer(1:MAX)) This REQUIRED READ-ONLY Subscription object attribute indicates the amount of time (in seconds) that the Printer implementation has been up and running. This attribute is an alias for the Printer's "printer-up- time" attribute" (see [ipp-mod] section 4.4.29), in an analogous way that the Job's "job-printer-up-time" is an alias for "printer-up-time" (see [ipp-mod] section 4.3.13.4). Note: A client can request this attribute in a Get-Printer- Subscription-Attributes or Get-Printer-Subscriptions request and use the value returned in combination with the "notify-subscription-expiration- time" (see section 5.4.2) in order to display wall clock time equivalent to the user. The difference between this attribute and the 'integer' value of the "notify-subscription-expiration-time" attribute is the number of seconds in the future that the subscription will expire. A client can compute the wall-clock time at which the subscription will expire by adding this difference to the client.s wall-clock time. 5.5 Printer Description Attributes related to Notification This section defines the Printer Description attributes that are related to Notification. Table 5 - Printer Description attributes associated with Notification Printer object attributes: Printer READ-ONLY, set by: support notify-schemes-supported (1setOf R Administrator/implem uriScheme) entation notify-events-default (1setOf R Administrator/implem type2 keyword) entation notify-events-supported (1setOf R Administrator/implem type2 keyword) entation max-events-supported R Administrator/implem (integer(5:MAX)) entation max-job-subscriptions-supported R Administrator/implem (integer(1:MAX)) entation max-printer-subscriptions- R Administrator/implem supported (integer(0:MAX)) entation notify-lease-time-supported R Administrator/implem (rangeOfInteger(0:MAX)) entation notify-lease-time-default R Administrator/implem (integer(0:MAX)) entation persistent-jobs-supported O Administrator/implem (boolean) entation persistent-subscriptions-supported O Administrator/implem Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 26] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Printer object attributes: Printer READ-ONLY, set by: support (boolean) entation printer-state-change-time O Administrator/implem (integer(1:MAX)) entation printer-state-change-date-time O Administrator/implem (dateTime) entation 5.5.1 notify-schemes-supported (1setOf uriScheme) This REQUIRED Printer attribute describes the notification delivery methods supported by this Printer object. Standard values are defined in Section 5.3.1). 5.5.2 notify-events-default (1setOf type2 keyword) This REQUIRED Printer attribute identifies the event values if the client does not supply the "notify-events" operation attribute in either a Job creation request or the Create-Printer-Subscription request. Any value in this attribute MUST also appear in the notify-events-supported attribute, i.e., be a supported event. 5.5.3 notify-events-supported (1setOf type2 keyword) This REQUIRED Printer attribute identifies the events supported by this Printer object for both Per-Job and Per-Printer subscriptions which MUST be the same. Standard values are defined in Section 5.3.2. 5.5.4 max-events-supported (integer(5:MAX)) This REQUIRED Printer attribute specifies the maximum number of events that are supported in a single Per-Job or Per-Printer subscription which must be the same. A Printer MUST support at least 5 events per subscription, so that clients can depend on at least 5 events in a single subscription. If the number of events supplied by a client in a subscription exceed this number, the Printer rejects the request and returns the 'server-error-too-many-events (see section 14.3). If notification is not supported, this attribute MUST NOT be supported. 5.5.5 max-job-subscriptions-supported (integer(1:MAX)) This REQUIRED Printer attribute specifies the maximum number of Per-Job subscriptions that are supported in a single Job Creation request, i.e., the maximum number of collection values for the "job-notify" operation attribute. A value of 0 indicates no effective maximum. A Printer MUST support at least 1 Per-Job subscription. If the number of Per-Job subscriptions supplied by a client in a Job Creation request exceed this number, the Printer rejects the request and returns the 'server-error- too-many-subscriptions' (see section 14.2). 5.5.6 max-printer-subscriptions-supported (integer(0:MAX)) This REQUIRED Printer attribute specifies the maximum number of Per- Printer subscriptions that are supported by multiple Create-Printer- Subscription requests, i.e., the maximum number of un-expired Subscription objects that the Printer supports at a time. A value of 0 Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 27] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 indicates no effective maximum. A Printer MUST support at least 1 Per- Printer subscription. If the number of Per-Printer subscriptions would exceed this number, the Printer rejects the Create-Printer-Subscription request and returns the 'server-error-too-many-subscriptions' (see section 14.2). 5.5.7 notify-lease-time-supported (rangeOfInteger(0:MAX)) This REQUIRED Printer attribute specifies the range of values in seconds that are supported for the "notify-lease-time-requested" operation attribute in a Create-Printer-Subscription or Renew-Printer-Subscription request. When the lease time expires for a Per-Printer Subscription without renewing, the Printer MUST delete the Subscription object. If the client requests a value outside this range, the Printer MUST grant a value that is in this range (see section 5.4.2). A value of 0 indicates an infinite lease, i.e., one that does not expire. 5.5.8 notify-lease-time-default (integer(0:MAX)) This REQUIRED Printer attribute specifies the value of the lease time that the Printer object has been configured to assume if the client does not supply a "notify-lease-time-requested" operation attribute in the Create-Printer-Subscription or Renew-Printer-Subscription requests. 5.5.9 persistent-jobs-supported (boolean) This OPTIONAL Printer attribute indicates whether or not the Printer supports persistent Jobs, i.e., Jobs object that are preserved across power cycles. If Jobs are persistent, then Per-Job Subscriptions MUST also be persistent, since they are part of the Job object. It is RECOMMENDED that Jobs (and Per-Job Subscriptions) be persistent. 5.5.10persistent-subscriptions-supported (boolean) This OPTIONAL Printer attribute indicates whether or not the Printer supports persistent Per-Printer Subscriptions, i.e., Subscription objects that are preserved across power cycles. When this value is 'true' the implementation MAY support some that are persistent and some that are not. If the value is 'false' or the attribute is not supported, Per-Printer Subscriptions MUST NOT be persistent. It is RECOMMENDED that Per-Printer subscriptions be persistent. 5.5.11printer-state-change-time (integer(1:MAX)) This OPTIONAL Printer attribute records the time, i.e., copy of the Printer's "printer-up-time" attribute, that the Printer's "printer- state" attribute was last changed. On power-up, the Printer populates the "printer-state-change-time" from its "printer-up-time" attribute, so that it always has a value. 5.5.12printer-state-change-date-time (dateTime) This OPTIONAL Printer attribute records the date and time, i.e., copy of the Printer's "printer-current-time" attribute, that the Printer's "printer-state" attribute was last changed. On power-up, the Printer populates the "printer-state-change-date-time" from its "printer- current-time" attribute, so that it always has a value. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 28] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 6 Notification Content This section defines the Notification content that is sent to a Notification Recipient when an event occurs. The Notification MAY be sent by the IPP Printer or a third party Notification Service (see section 2.3). There are two notification content types: Machine Consumable and Human Consumable. For most notification delivery methods both content types are defined. Some of the notification delivery methods are defined to support only one content type. A Printer MUST support all content types defined for a notification delivery method, if it supports that notification delivery method. 6.1 Notification content MIME media type formats This section defines the Notification content that the Notification Source sends asynchronously to each Notification Recipient based on the subscription information stored with the subscription. Notifications are generated using the following content formats: 'application/ipp' - Machine Consumable notification content using the 'application/ipp' MIME media type [ipp-mod] using the Get- Job-Attributes response encoding for job events and Get-Printer- Attributes for printer events. The attributes listed in sections 6.2 and 6.3 are sent in an notification for Job events. The attributes listed in sections 6.2 and 6.4 are sent in an notification for Printer events. For any string in any notification, the charset and natural language rules that apply to all IPP operations apply to the notification strings as well, since they are represented as operation responses. The Unsupported Attributes Group in the response is not sent. If the values of any of the attributes sent in an notification content are not known, the value sent in the report content is the out-of-band 'unknown' value, rather than omitting the attribute (see the beginning of [ipp-mod] section 4.1). An implementation MAY extend the contents of the Machine Consumable notification by adding additional attributes. 'text/plain; charset=utf-8' - Human Consumable notification content type [RFC2046]. The text message SHOULD include information about the attributes in sections 6.2 and 6.3 for job events or in sections 6.2 and 6.4 for printer events. This information is localized according to the information about natural language and charset in the subscription. An implementation MAY extend the contents of a Human Consumable notification by adding additional information. 6.2 Notification content attributes common to Job and Printer events This section lists the parameters and attributes that are included in both Job and Printer event Notifications. Some events do not include all of these attributes as shown in Table 6. Each notification content contains a single Job or Printer event, whether that event was subscribed using the Job Submission Subscription mechanism or the Per- Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 29] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Printer subscription mechanism. If either kind of subscription subscribed to both Job and Printer events, then they will be sent as separate Job notification content and Printer notification contents to the same Notification Recipient. Table 6 - Common Job and Printer Notification content attributes Reference Events Attributes 'job- all progress' others R R 1. version-number (integer mod 3.1.1 (0:32767)) R R 2. status-code (integer mod 3.1.1 (0:32767)) 3. request-id (integer (0:MAX)) 5.3.7 & mod R R 3.1.1 4. attributes-charset (charset) 5.3.5 & mod R R 3.1.4 5. attributes-natural-language 5.3.6 & mod R R (naturalLanguage) 3.1.4 R R 6. printer-uri (uri) 5.4.3 R 7. printer-name (name(127)) mod 4.4.4 R R** 8. job-id (integer(1:MAX)) mod 4.3.2 R** 9. job-name (name(MAX)) mod 4.3.5 10.trigger-event (type2 keyword) 5.3.2 R R 11.trigger-time R R (integer(MIN:MAX)) 12.trigger-date-time (dateTime) O 13.subscription-id 5.4.1 R R (integer(1:MAX)) R 14.subscriber-user-name 5.4.4 (name(MAX)) 15.subscriber-user-data 5.3.4 R (octetString(63)) Attribute Notes: "status-code" - a value of 600 for a Job event and 601 for a Printer event. "request-id" - the sequence number for this subscription, starting at 1 for each subscription. "attributes-charset" - the value comes from the "notify-attributes- charset" in the "job-notify" Per-Job Subscription and the "notify- attributes-charset" in the Per-Printer Subscription object. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 30] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 "attributes-natural-language" - the value comes from the "notify- attributes-natural-language" in the "job-notify" Per-Job Subscription and the "notify-attributes-natural-language" in the Per-Printer Subscription object. "printer-uri" - the value comes from the "job-printer-uri" Job attribute for Per-Job subscriptions. **"job-id" and "job-name" - included in Printer event Notifications only for Per-Job subscriptions. "trigger-event" - the event that caused this Notification to be delivered. "trigger-time" - the "printer-up-time" value when the event occurred. "trigger-date-time" - the "printer-current-time" value when the event occurred - OPTIONAL to support. "job-name" - SNMP delivery method can truncate to less than 255 octets, since the Notification needs to fit into 484 octets or so on some transports that SNMP is defined for. "subscription-id" - for Per-Job subscriptions, the value is the index of the "job-notify" collection value, starting with 1 for the first collection value. "subscriber-user-name" - comes from "requesting-user-name" Job attribute for Per-Job subscriptions. SNMP delivery method can truncate to less than 255 octets, since the Notification needs to fit into 484 octets or so on some transports that SNMP is defined for. "subscriber-user-data" - opaque user data that may identify either the Subscriber and/or the ultimate Notification Recipient. 6.3 Additional Notification content attributes for Job events only This section lists the additional attributes that are included only in Job event Notifications. Some events do not include all of these attributes as shown in Table 7. Table 7 - Additional Notification content attributes for Job events only Events Attributes Reference 'job- 'job- all progre complet othe ss' ed' rs 16.job-state (type1 enum) mod 4.3.7 R R 17.job-state-reasons (1setOf type2 mod 4.3.8 R R keyword) 18.job-k-octets-processed mod O O Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 31] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Events Attributes Reference 'job- 'job- all progre complet othe ss' ed' rs (integer(0:MAX)) 4.3.18.1 19.job-impressions-completed mod O O (integer(0:MAX)) 4.3.18.2 20.job-media-sheets-completed mod O O (integer(0:MAX)) 4.3.18.3 21.job-collation-type (type2 enum) [ipp- R prog] 22.sheet-completed-copy-number [ipp- R (integer(-2:MAX)) prog] 23.sheet-completed-document- [ipp- R number(integer(-2:MAX)) prog] 24.impressions-interpreted (integer(- [ipp- R 2:MAX)) prog] 25.impressions-completed-current-copy [ipp- R (integer(-2:MAX)) prog] 6.4 Additional Notification content attributes for Printer events only Table 8 lists the additional attributes that are included only in Printer event Notifications. Table 8 - Additional Notification content attributes for Printer events only Events Attributes Reference all printer events 26.printer-state (type1 enum) mod 4.4.11 R 27.printer-state-reasons (1setOf type2 keyword) mod 4.4.12 R 28.printer-is-accepting-jobs (boolean) mod 4.4.23 R 7 Operations for Per-Job Subscriptions This section defines the REQUIRED operation requests and responses that are related to Per-Job subscriptions. Section 8 defines the REQUIRED operation requests and responses associated with the REQUIRED Per- Printer subscription and its Subscription object. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 32] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 7.1 Job Creation Operations (Create-Job, Print-Job, Print-URI) and Validate-Job 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 Per-Job Subscription, the client supplies the "job-notify (1setOf collection)" operation attribute with the member attributes listed in Table 9 with any of the job creation operations (Create-Job, Print-Job, Print-URI), plus Validate-Job (which doesn't create a job or subscription). If the client does not supply the "job-notify" attribute in the create operation, there is no subscription made (either implicitly or explicitly). If a Printer does not support this notification specification, then it MUST ignore the "job-notify" operation attribute and return it in the response indicated as an attribute that is not supported. See [ipp-mod] section 3.1.7 for details on returning Unsupported Attributes. Table 9 - Member attributes of the "job-notify" collection operation attribute Member attribute of "job-notify" Reference REQUIRED Printer collection in support request notify-recipient (uri) 5.3.1 yes REQUIRED notify-events (1setOf type2 keyword) 5.3.2 no REQUIRED notify-content-type (mimeMediaType) 5.3.3 no REQUIRED subscriber-user-data (octetString(63)) 5.3.4 no REQUIRED notify-attributes-charset (charset) 5.3.5 no OPTIONAL notify-attributes-natural-language 5.3.6 no OPTIONAL (naturalLanguage) See the referenced sections for a definition of these operation attributes, since they are copied to the Job object as the Job Description attributes described in section 5.3. The following rules apply to Per-Job subscriptions: 1.Any subscription can contain job events, printer events, or both. 2.The Job Submission Subscription is only valid while the job is "not- completed". The job is "not-completed" while it is in the 'pending', 'pending-held', 'processing', and 'processing-stopped' states. The job changes from being "not-completed" to "retained" when it is done processing and enters any of the 'completed', 'canceled', or 'aborted' states. The job becomes "not-completed" again when it is restarted using the Restart-Job operation (see [ipp-mod]). 3.Since no job is created for the Validate-Job operation, the only purpose of supplying the subscription operation attributes in the Validate-Job operation is to validate that the values are supported; the Printer object does not establish a notification subscription as a result of the Validate-Job operation. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 33] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 4.Since a Job Submission Subscription is included within a job submission operation, any interest in job events is limited to "this job" only (the Job object created because of this job creation operation). There is no mechanism to subscribe to events for all jobs or specifically some job other than this job in a create operation. But see the Create-Printer-Subscription operation (section 8.1) for an explicit operation to subscribe for job and/or printer events independently of any particular job submission. 5.Event reporting only occurs when a notification recipient has specified a subscription to any event(s). 6.The notification implementation MAY allow an administrator to configure a policy on what events may be dropped. 7.If the OPTIONAL "notify-attributes-charset" attribute is not supported or the supplied value is not supported, the IPP Printer MUST return the attribute in the Unsupported Attributes Group but still accept the operation, as with all Job create operations. In this case, the Printer MUST use the natural language supplied in the "attributes-charset" Job creation operation attribute, if that natural language value is supported by the Printer, else the Printer object MUST use the Printer's "charset-configured" value. See the Print-Job operation in [ipp-mod]. 8.If the OPTIONAL "notify-attributes-natural-language" attribute is not supported or the supplied value is not supported, the IPP Printer MUST return the attribute in the Unsupported Attributes Group but still accept the operation, as with all Job create operations. In this case, the Printer MUST use the natural language supplied in the "attributes-natural-language" Job creation operation attribute, if that natural language value is supported by the Printer, else the Printer object MUST use the Printer's "natural-language-configured" value. See the Print-Job operation in [ipp-mod]. 7.2 Get-Printer-Attributes operation The REQUIRED (by [ipp-mod]) Get-Printer-Attributes can be used to request the additional Printer Description attributes that indicate the notification supported. See section 5.5. 7.3 Get-Job-Attributes operation The REQUIRED (by [ipp-mod]) Get-Job-Attributes can be used to request the additional Job Description attributes that relate to notification. See section 5.5. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 34] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 7.4 Set-Job-Attributes operation The OPTIONAL Set-Job-Attributes operation (see [ipp-set2]) allows a client to change the Job attributes of the Job's Per-Job subscription, including to add them in the first place if they had not been supplied in the Job creation operation and to remove them from the Job object. This operation replaces all the collection values of the supplied "job- notify (1setOf collection) notification attribute. In order to cancel all Per-Job subscriptions, the client supplies the "job-notify" attribute with an out-of-band 'none' value (see [ipp- coll]). Request: Group 1: Operation Attributes Printer support "attributes-charset" (charset) R "attributes-natural-language" R (naturalLanguage) "printer-uri" (uri) R "requesting-user-name" (name(MAX)) RECOMMENDED "job-notify" (1setOf collection) R Response: Group 1: Operation Attributes Printer support "status-code" (type2 enum) R "attributes-charset" (charset) R "attributes-natural-language" R (naturalLanguage) ["status-message" (text(255))] O ["detailed-status-message" (text(MAX))] O Group 2: Unsupported Attributes R The "job-notify" operation attribute is copied to the "job-notify" Job Description attribute. See section 5.1 for a definition of the "job- notify" Job Description attribute. 8 Per-Printer Subscriptions and the Subscription object This section lists the REQUIRED Per-Printer Subscriptions operation requests and responses and the Subscription object that MUST be supported. ISSUE 3 - Are these abbreviated operation definitions ok for understandability and conformance, or should we use the more verbose definition style of the [ipp-mod]? 8.1 Create-Printer-Subscription operation The REQUIRED Create-Printer-Subscription operation creates a Per-Printer subscription by creating a Per-Printer Subscription object which is added to the Printer object. The client can specify one or more job and/or printer events to be delivered as notifications to one Notification Recipient. The job events are for any job submitted to the Printer. The printer events are any events generated by that Printer. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 35] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 The Printer returns a subscription id and the length of time for which it has granted a lease for the subscription. The client must renew the subscription using the Renew-Printer-Subscription operation (see section 8.4) before the lease runs out in order to maintain the subscription. A client can unsubscribe using the Cancel-Printer-Subscription operation (section 8.5) and the subscription id. Two Create-Printer-Subscription operations with the same events and same Notification Recipient MUST be kept as distinct subscriptions and be assigned distinct subscription ids. A Printer MUST allow such duplicate subscriptions such that Cancel-Printer-Subscription doesn't unsubscribe both subscriptions and MUST send the Notifications twice to the Notification Recipient, since the "request-id" is supposed to count monotonically for each subscription. If the Printer has a bounded set of concurrent subscriptions (for the specified events or any events), the printer rejects the operation and returns the 'server-error-too-many-subscriptions' status code. The client SHOULD try again later. Access Rights: The authenticated user (see [IPP-MOD] section 8.3) performing this operation MUST have operator or administrator access rights for the Printer object (see [IPP-MOD] sections 1 and 8.5). Otherwise the IPP object MUST reject the operation and return: client- error-forbidden, client-error-not-authenticated, and client-error-not- authorized as appropriate. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 36] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Request: Group 1: Operation Attributes Printer support "attributes-charset" (charset) R "attributes-natural-language" R (naturalLanguage) "printer-uri" (uri) R ["requesting-user-name" (name(MAX))] RECOMMENDED ["notify-recipient" (uri)] R ["notify-events" (1setOf type2 keyword)] R ["notify-content-type" (mimeMediaType)] R ["subscriber-user-data" (octetString(63))] R ["notify-attributes-charset" (charset)] O ["notify-attributes-natural-language" O (naturalLanguage)] ["notify-lease-time-requested" R (integer(0:MAX))] ["notify-persistence-requested" (boolean)] O Response: Group 1: Operation Attributes Printer Support "status-code" (type2 enum) R "attributes-charset" (charset) R "attributes-natural-language" R (naturalLanguage) ["status-message" (text(255))] O ["detailed-status-message" (text(MAX))] O "subscription-id" (integer(1:MAX)) R "notify-lease-expiration-time" R (integer(0:MAX)) "notify-lease-time-granted" R (integer(0:MAX)) "notify-persistence-granted" (boolean) R Group 2: Unsupported Attributes R Attribute Notes: "notify-recipient" (uri) - the client MUST supply this attribute in order to have a subscription. "notify-lease-time-requested" (integer(0:MAX) - the number of seconds requested for the Per-Printer subscription lease. A value of 0 indicates a request that the Per-Printer Subscription lease never expire. Supplying a 0 value MAY require authentication in order to be used, if 0 is supported at all. If the client does not supply this attribute, the Printer uses its "notify-lease-time-default" value (see section 5.5.8). "notify-persistence-requested" (boolean) - whether or not the Per- Printer Subscription is to be persistent, i.e., saved across power cycles. Note: Persistent trap registrations is a client option in SNMPv3 [RFC2573]. "notify-lease-expiration-time" (integer(0:MAX)) - The Printer Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 37] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 object MUST return this attribute which is the time in the future at which the subscription lease will expire, i.e., the "printer-up- time" value (in time ticks - see [ipp-mod] section 4.4.29) at which the Printer will delete the Subscription. A value of 0 indicates that the lease subscription will never expire. "notify-lease-time-granted" - The Printer object MUST return this attribute which is the number of seconds of time actually granted. The value of "notify-lease-time-granted" may be less than the requester requested in the "notify-lease-time-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 "notify-lease-time-supported" (rangeOfInteger(0:MAX)) attribute. "notify-persistence-granted" - whether or not this Per-Printer Subscription object instance is persistent. This attribute MUST be returned whether "notify-persistence-requested" is supported or not, so that the client knows which. 8.2 Get-Printer-Subscription-Attributes operation The REQUIRED Get-Printer-Subscription-Attributes returns the requested attributes of the identified Per-Printer Subscription object. See sections 5.3 and 5.4. Request: Group 1: Operation Attributes Printer support "attributes-charset" (charset) R "attributes-natural-language" R (naturalLanguage) "printer-uri" (uri) R ["requesting-user-name" (name(MAX))] RECOMMENDED "subscription-id" (integer(1:MAX)) R ["requested-attributes" (1setOf type2 keyword)] R Response: Group 1: Operation Attributes Printer support "status-code" (type2 enum) R "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R ["status-message" (text(255))] O ["detailed-status-message (text(MAX))] O Group 2: Unsupported Attributes R Group 3: This operation is similar to the Get-Printer-Attributes operation. If the client omits the "requested-attributes" operation attribute, the Printer MUST respond as if the client had supplied the 'all' value, i.e., return all of the attributes supported for the Subscription object. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 38] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 8.3 Get-Printer-Subscriptions operation The REQUIRED Get-Printer-Subscriptions operation returns Per-Printer subscriptions, i.e., Subscription objects. Request: Group 1: Operation Attributes Printer support "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R "printer-uri" (uri) R ["requesting-user-name" (name(MAX))] RECOMMENDED ["limit" (integer(1:MAX))] R ["requested-attributes" (1setOf type2 keyword)] R ["my-subscriptions" (boolean)] R Response: Group 1: Operation Attributes Printer support "status-code" (type2 enum) R "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R ["status-message" (text)] O ["detailed-status-message" (text(MAX))] O Group 2: Unsupported Attributes R Group 3 to N: Notes: This operation is similar to the Get-Jobs operation (see [ipp- mod]). If the client wants any attributes returned, including the "subscription-id", it must include the attribute keyword name in the "requested-attributes" operation attribute. If the "requested- attributes operation attribute is omitted, the Printer MUST respond as if the client supplied the value: 'subscription-id'. If the client supplies the "my-subscriptions" with a 'false' value or omits it, the Printer returns all subscriptions, subject to the security policy in force. 8.4 Renew-Printer-Subscription operation The REQUIRED Renew-Printer-Subscription operation permits a client to request the IPP Printer to extend the lease on a Per-Printer Subscription object instance. Access Rights: The authenticated user (see [IPP-MOD] 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 object (see [IPP-MOD] sections 1 and 8.5). Otherwise the IPP object MUST reject the operation and return: client-error-forbidden, client- error-not-authenticated, and client-error-not-authorized as appropriate. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 39] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 Request: Group 1: Operation Attributes Printer support "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R "printer-uri" (uri) R ["requesting-user-name" (name(MAX))] RECOMMENDED "subscription-id" (integer(1:MAX)) R ["notify-lease-time-requested" R (integer(0:MAX))] Response: Group 1: Operation Attributes Printer support "status-code" (type2 enum) R "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R ["status-message" (text(255))] O ["detailed-status-message" (text(MAX))] O "notify-lease-expiration-time" R (integer(0:MAX)) "notify-lease-time-granted" (integer(0:MAX)) R Group 2: Unsupported Attributes R Attribute Notes: "notify-lease-time-requested" (integer(0:MAX) - the number of seconds requested for the Per-Printer subscription lease. Same as Create- Printer-Subscriptions (see section 8.1). "notify-lease-expiration-time" - the time in the future when the subscription will expire. Same as for the Create-Printer- Subscription operation (see section 7.1). "notify-lease-time-granted" - the lease time (number of seconds) actually granted. Same as for the Create-Printer-Subscription operation (see section 7.1). Note: There is no way to change any of the Subscription object attributes, except the "notify-lease-expiration-time" attribute. In order to change other attributes, a client can create a new Subscription object and then use the Cancel-Printer-Subscription operation to cancel the old one (or do this in the other order, in case there is a limit on the number of Subscription object instances, as long as a short window with no Notifications is ok). Note: There is no need to renew a Per-Job Subscription, since it is effectively the time that the Job is active (see section 7.1). 8.5 Cancel-Printer-Subscription operation The REQUIRED Cancel-Printer-Subscription operation allows a client to remove a Per-Printer Subscription object from the Printer. No more Notifications are delivered for that Subscription. Once performed, there is no way to use that Subscription in the future. Subscription- Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 40] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 ids should not be reused immediately, so that a stale reference situation is not created. Same as for Cancel-Job and job-ids. Access Rights: The authenticated user (see [IPP-MOD] 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 object (see [IPP-MOD] sections 1 and 8.5). Otherwise the IPP object MUST reject the operation and return: client-error-forbidden, client- error-not-authenticated, and client-error-not-authorized as appropriate. Request: Group 1: Operation Attributes Printer support "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R "printer-uri" (uri) R ["requesting-user-name" (name(MAX))] RECOMMENDED "subscription-id" (integer(1:MAX)) R Response: Group 1: Operation Attributes Printer support "status-code" (type2 enum) R "attributes-charset" (charset) R "attributes-natural-language" (naturalLanguage) R ["status-message" (text(255))] O ["detailed-status-message" (text(MAX))] O Group 2: Unsupported Attributes R 9 Comparison of Per-Job Submission Subscriptions versus Per-Printer Subscriptions Per-Job and Per-Printer subscriptions are quite similar. However, there are some semantic differences between Per-Job subscriptions and Per- Printer subscriptions. A Per-Job Submission Subscription is established by the client when submitting a job. A Per-Printer Subscription is established between a client and a Printer using the new Create-Printer- Subscription operation. Some specific differences are: 1.Either type of subscription can subscribe to Job events, Printer events, or both. 2.For Per-Job Subscriptions, the subscription is only valid while the job is "not-complete" (see sections 6.2 and 6.3). 3.For the Per-Printer Subscriptions, the subscription is valid until it is explicitly canceled with a Cancel-Printer-Subscription operation or the time (in seconds) that the Printer returned in the "notify- lease-time-granted" operation attribute expires, whichever occurs first. 4.Job Events in a Per-Job Subscription apply only to "one job" (the Job created by the job creation operation). Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 41] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 5.Job Events in a Per-Printer-Subscription apply to ALL jobs contained in the IPP Printer object. 6.Printer Events in both kinds of subscriptions apply no matter which job is being processed, if any. 10 Conformance Requirements This section further enhances the Conformance Requirements detailed in [IPP-MOD] section 5. Extensions made to the events herein must be made such that new events or event attributes are backward compatible to clients who implemented early versions of this notification specification. It is OPTIONAL to implement this Event Notification specification. If implemented, IPP objects MUST support all of the REQUIRED object attributes as defined in this document in the indicated sections. If IPP Notification is implemented, the operations described in this document must be supported as described in Table 10: Table 10 - Conformance Requirements for Operations Attribute Conformance requirements "job-notify" in Job Creation operations (section 7.1) REQUIRED Set-Job-Attributes (see section 7.4) OPTIONAL Create-Printer-Subscription (section 8.1) REQUIRED Get-Printer-Subscription-Attributes (section 8.2) REQUIRED Get-Printer-Subscriptions (section 8.3) REQUIRED Renew-Printer-Subscription (section 8.4) REQUIRED Cancel-Printer-Subscription (section 8.5) REQUIRED 11 IANA Considerations IANA will be called on to register URL schemes for notification delivery for use in the "notification-recipient" attribute, using the same procedures outlined in [ipp-mod]. 12 Internationalization Considerations This IPP notification specification continues the internationalization of [ipp-mod] for attributes containing text strings and names. A subscribing client can specify a different natural language and charset for each Notification content delivered to a Notification Recipient. The Human Consumable Notification content is a 'text/plain; charset=utf- 8' by default where the Notification Sender has localized the text message as requested by the subscriber for the intended Notification Recipient. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 42] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 13 Security Considerations By far the biggest security concern is the abuse of notification: sending unwanted 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 notifications (a traditional fax model). Clients submitting notification requests to the IPP Printer has 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 the HTTP/TLS privacy. The notification access control model should be similar to the IPP access control model for Jobs. Creating a Per-Printer Notification Subscription object is associated with a user. Only the creator or an operator can cancel the subscription. The system may limit the listing of items to only those items owned by the user. Some subscriptions (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 notification delivery. IPP should use the security mechanism of the delivery method used. Some delivery mechanisms are more secure than others. Therefore, sensitive notifications should use the delivery method that has the strongest security. 14 Status Codes The following status codes are defined as extensions for notification: 14.1client-error-uri-notification-scheme-not-supported (0x04??) The scheme of the client-supplied URI in a "notify-recipient" operation attribute in a Create-Printer-Subscription operation is not supported. See [ipp-mod] section 3.1.7. Note: There is no corresponding Per-Job subscription error, since the Printer object MUST ignore any errors in the "job-notify" operation attribute and perform the Job Creation operation (see section 5.1), since the job can still be printed. ISSUE 4 - The client-error-uri-scheme-not-supported is already an IPP/1.1 status code and section 3.1.6.1 indicates that the "document- Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 43] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 uri" attribute NEED NOT be returned in the Unsupported Attributes group, otherwise, we could use that error code and REQUIRE that offending "xxx- uri" attribute(s) to be returned. 14.2server-error-too-many-subscriptions (0x04??) The bounded set of concurrent Per-Printer subscriptions supported by the Printer object would be exceeded if this request were accepted. Note: There is no corresponding Per-Job subscription error, since the Printer object MUST ignore any errors in the "job-notify" operation attribute and perform the Job Creation operation (see section 5.1), since the job can still be printed. 14.3server-error-too-many-events (0x04??) The client supplied more events in the "notify-events" operation attribute in a Create-Printer-Subscription that the Printer supports, as indicated in its "max-events-supported" attribute (see section 5.5.4). Note: There is no corresponding Per-Job subscription error, since the Printer object MUST ignore any errors in the "job-notify" operation attribute and perform the Job Creation operation (see section 5.1), since the job can still be printed. ISSUE 5 - Should the entire "job-notify" operation attribute be ignored, if one of its member attributes has a problem, or should just that member attribute be ignored? If the latter, then is just the member attribute returned in the Unsupported Attributes group? 15 References [ipp-coll] deBry, R., , Hastings, T., Herriot, R., "Internet Printing Protocol/1.0 & 1.1: collection attribute syntax", , work in progress, August 22, 1999. [ipp-mod] deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., "Internet Printing Protocol/1.1: Model and Semantics", < draft- ietf-ipp-model-v11-04.txt>, work in progress, June 23, 1999. [ipp-not-hist] deBry, R., Lewis, H., Hastings, T., "Internet Printing Protocol/1.1: Requirements for IPP Notifications", , work in progress, August 22, 1999. [ipp-not-req] deBry, R., Lewis, H., Hastings, T., "Internet Printing Protocol/1.1: Requirements for IPP Notifications", , work in progress, August 11, 1999. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 44] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 [ipp-set2] Kugler, C., , Hastings, T., "Internet Printing Protocol/1.0 & 1.1: Additional Operations, Set 2", , work in progress, August 22, 1999. [ipp-prog] Hastings, T., Bergman, R., Lewis, H., "Proposed Job Progress Attributes for IPP", work in progress, May 18, 1999. [RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. N. Freed & N. Borenstein. November 1996. (Obsoletes RFC1521, RFC1522, RFC1590), RFC 2046. [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119 , March 1997 [RFC2566] deBry, R., , Hastings, T., Herriot, R., Isaacson, S., Powell, P., "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566, April 1999. 16 Author's Addresses Scott A. Isaacson (Editor) Novell, Inc. 122 E 1700 S Provo, UT 84606 Phone: 801-861-7366 Fax: 801-861-2517 e-mail: sisaacson@novell.com Tom Hastings Xerox Corporation 737 Hawaii St. ESAE 231 El Segundo, CA 90245 Phone: 310-333-6413 Fax: 310-333-5514 e-mail: hastings@cp10.es.xerox.com Roger deBry Utah Valley State College Orem, UT 84058 Phone: (801) 222-8000 EMail: debryro@uvsc.edu Jay Martin Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 45] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 e-mail: jkm@underscore.com Michael Shepherd Xerox Corporation 800 Phillips Road MS 128-51E Webster, NY 14450 Phone: 716-422-2338 Fax: 716-265-8871 e-mail: mshepherd@crt.xerox.com Ron Bergman (Editor) Dataproducts Corp. 1757 Tapo Canyon Road Simi Valley, CA 93063-3394 Phone: 805-578-4421 Fax: 805-578-4001 Email: rbergman@dpc.com A. Appendix - Summary of Notification Attribute Usage This appendix summarizes the usage of Notification attributes in the Job operation attribute collection, Job object, Subscription object, Notification content, Job operations, and Subscriptions operations. ISSUE 6 - Should this appendix be kept in the spec or moved to the Implementer's Guide? 17 Appendix C: Full Copyright Statement Copyright (C) The Internet Society (1998,1999). 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. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 46] Expires January 22, 2000 INTERNET-DRAFT IPP/1.0 & IPP/1.1 Event Notification July 22, 1999 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. Isaacson, Martin, deBry, Hastings, Shepherd, Bergman [page 47] Expires January 22, 2000