Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3995

Internet Printing Protocol (IPP): Event Notifications and Subscriptions

Pages: 95
Proposed Standard
Errata
Updates:  29112910
Part 1 of 4 – Pages 1 to 18
None   None   Next

Top   ToC   RFC3995 - Page 1
Network Working Group                                         R. Herriot
Request for Comments: 3995                     Global Workflow Solutions
Category: Standards Track                                    T. Hastings
Updates: 2911, 2910                                    Xerox Corporation
                                                              March 2005


                   Internet Printing Protocol (IPP):
                 Event Notifications and Subscriptions

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2005).

Abstract

This document describes an OPTIONAL extension to the Internet Printing Protocol/1.1: Model and Semantics (RFC 2911, RFC 2910). This extension allows a client to subscribe to printing related Events. Subscriptions are modeled as Subscription Objects. The Subscription Object specifies that when one of the specified Events occurs, the Printer delivers an asynchronous Event Notification to the specified Notification Recipient via the specified Push or Pull Delivery Method (i.e., protocol). A client associates Subscription Objects with a particular Job by performing the Create-Job-Subscriptions operation or by submitting a Job with subscription information. A client associates Subscription Objects with the Printer by performing a Create-Printer-Subscriptions operation. Four other operations are defined for Subscription Objects: Get-Subscriptions-Attributes, Get-Subscriptions, Renew- Subscription, and Cancel-Subscription.
Top   ToC   RFC3995 - Page 2

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.1. Notification Overview. . . . . . . . . . . . . . . . . . 5 2. Models for Notification. . . . . . . . . . . . . . . . . . . . 8 2.1. Model for Simple Notification (Normative). . . . . . . . 8 2.2. Additional Models for Notification (Informative) . . . . 9 3. Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Conformance Terminology. . . . . . . . . . . . . . . . . 9 3.2. Other Terminology. . . . . . . . . . . . . . . . . . . . 10 4. Object Relationships . . . . . . . . . . . . . . . . . . . . . 12 4.1. Printer and Per-Printer Subscription Objects . . . . . . 13 4.2. Printer, Job and Per-Job Subscription Objects. . . . . . 13 5. Subscription Object. . . . . . . . . . . . . . . . . . . . . . 13 5.1. Rules for Support of Subscription Template Attributes. . 14 5.2. Rules for Processing Subscription Template Attributes. . 15 5.3. Subscription Template Attributes . . . . . . . . . . . . 18 5.3.1. notify-recipient-uri (uri) . . . . . . . . . . . 20 5.3.2. notify-pull-method (type2 keyword) . . . . . . . 21 5.3.3. notify-events (1setOf type2 keyword) . . . . . . 22 5.3.4. notify-attributes (1setOf type2 keyword) . . . . 29 5.3.5. notify-user-data (octetString(63)) . . . . . . . 30 5.3.6. notify-charset (charset) . . . . . . . . . . . . 31 5.3.7. notify-natural-language (naturalLanguage). . . . 31 5.3.8. notify-lease-duration (integer(0:67108863)). . . 32 5.3.9. notify-time-interval (integer(0:MAX)). . . . . . 33 5.4. Subscription Description Attributes. . . . . . . . . . . 34 5.4.1. notify-subscription-id (integer (1:MAX)). . . . 35 5.4.2. notify-sequence-number (integer (0:MAX)) . . . . 35 5.4.3. notify-lease-expiration-time (integer(0:MAX)). . 36 5.4.4. notify-printer-up-time (integer(1:MAX)). . . . . 37 5.4.5. notify-printer-uri (uri) . . . . . . . . . . . . 37 5.4.6. notify-job-id (integer(1:MAX)) . . . . . . . . . 37 5.4.7. notify-subscriber-user-name (name(MAX)). . . . . 38 6. Printer Description Attributes Related to Notification . . . . 38 6.1. printer-state-change-time (integer(1:MAX)) . . . . . . . 39 6.2. printer-state-change-date-time (dateTime). . . . . . . . 39 7. New Values for Existing Printer Description Attributes . . . . 39 7.1. operations-supported (1setOf type2 enum) . . . . . . . . 40 8. Attributes Only in Event Notifications . . . . . . . . . . . . 40 8.1. notify-subscribed-event (type2 keyword). . . . . . . . . 40 8.2. notify-text (text(MAX)). . . . . . . . . . . . . . . . . 41 9. Event Notification Content . . . . . . . . . . . . . . . . . . 41 9.1. Content of Machine Consumable Event Notifications. . . . 44 9.1.1. Event Notification Content Common to All Events. 44 9.1.2. Additional Event Notification Content for Job Events . . . . . . . . . . . . . . . . . . . . . 45
Top   ToC   RFC3995 - Page 3
             9.1.3.  Additional Event Notification Content for
                     Printer Events . . . . . . . . . . . . . . . . . 46
       9.2.  Content of Human Consumable Event Notification . . . . . 46
             9.2.1.  Event Notification Content Common to All Events. 47
             9.2.2.  Additional Event Notification Content for Job
                     Events . . . . . . . . . . . . . . . . . . . . . 49
             9.2.3.  Additional Event Notification Content for
                     Printer Events . . . . . . . . . . . . . . . . . 49
   10. Delivery Methods . . . . . . . . . . . . . . . . . . . . . . . 50
   11. Operations for Notification. . . . . . . . . . . . . . . . . . 52
       11.1. Subscription Creation Operations . . . . . . . . . . . . 52
             11.1.1. Create-Job-Subscriptions Operation . . . . . . . 52
             11.1.2. Create-Printer-Subscriptions operation . . . . . 55
             11.1.3. Job Creation Operations - Extensions for
                     Notification . . . . . . . . . . . . . . . . . . 56
       11.2. Other Operations . . . . . . . . . . . . . . . . . . . . 58
             11.2.1. Restart-Job Operation - Extensions for
                     Notification . . . . . . . . . . . . . . . . . . 58
             11.2.2. Validate-Job Operation - Extensions for
                     Notification . . . . . . . . . . . . . . . . . . 59
             11.2.3. Get-Printer-Attributes - Extensions for
                     Notification . . . . . . . . . . . . . . . . . . 59
             11.2.4. Get-Subscription-Attributes operation. . . . . . 60
             11.2.5. Get-Subscriptions operation. . . . . . . . . . . 63
             11.2.6. Renew-Subscription operation . . . . . . . . . . 66
             11.2.7. Cancel-Subscription operation. . . . . . . . . . 68
   12. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . 70
       12.1. successful-ok-ignored-subscriptions (0x0003) . . . . . . 70
       12.2. client-error-ignored-all-subscriptions (0x0414). . . . . 71
   13. Status Codes in Subscription Attributes Groups . . . . . . . . 71
       13.1. client-error-uri-scheme-not-supported (0x040C) . . . . . 71
       13.2. client-error-attributes-or-values-not-supported (0x040B) 71
       13.3. client-error-too-many-subscriptions (0x0415) . . . . . . 72
       13.4. successful-ok-too-many-events (0x0005) . . . . . . . . . 72
       13.5. successful-ok-ignored-or-substituted-attributes (0x0001) 72
   14. Encodings of Additional Attribute Tags . . . . . . . . . . . . 72
   15. Conformance Requirements . . . . . . . . . . . . . . . . . . . 72
       15.1. Conformance requirements for clients . . . . . . . . . . 73
       15.2. Conformance requirements for Printers. . . . . . . . . . 73
   16. Model for Notification with Cascading Printers (Informative) . 74
   17. Distributed Model for Notification (Informative) . . . . . . . 75
   18. Extended Notification Recipient (Informative). . . . . . . . . 76
   19. Object Model for Notification (Normative). . . . . . . . . . . 77
       19.1. Object relationships . . . . . . . . . . . . . . . . . . 78
       19.2. Printer Object and Per-Printer Subscription Objects. . . 79
       19.3. Job Object and Per-Job Subscription Objects. . . . . . . 79
   20. Per-Job versus Per-Printer Subscription Objects (Normative). . 79
   21. Normative References . . . . . . . . . . . . . . . . . . . . . 80
Top   ToC   RFC3995 - Page 4
   22. Informative References . . . . . . . . . . . . . . . . . . . . 80
   23. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 81
       23.1. Attribute Registrations. . . . . . . . . . . . . . . . . 82
       23.2. Additional Enum Attribute Value Registrations within
             the IPP registry . . . . . . . . . . . . . . . . . . . . 83
       23.3. Operation Registrations. . . . . . . . . . . . . . . . . 83
       23.4. Status code Registrations. . . . . . . . . . . . . . . . 83
       23.5. Attribute Group tag Registrations. . . . . . . . . . . . 84
       23.6. Registration of Events . . . . . . . . . . . . . . . . . 84
       23.7. Registration of Event Notification Delivery Methods. . . 85
             23.7.1. Requirements for Registration of Event
                     Notification Delivery Methods. . . . . . . . . . 85
             23.7.2. Registration Procedure . . . . . . . . . . . . . 86
             23.7.3. Delivery Method Document Registrations . . . . . 87
             23.7.4. Registration Template. . . . . . . . . . . . . . 88
   24. Internationalization Considerations. . . . . . . . . . . . . . 89
   25. Security Considerations. . . . . . . . . . . . . . . . . . . . 89
       25.1. Client access rights . . . . . . . . . . . . . . . . . . 89
       25.2. Printer security threats . . . . . . . . . . . . . . . . 91
       25.3. Notification Recipient security threats. . . . . . . . . 91
   26. Description of the base IPP documents (Informative). . . . . . 92
   27. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 93
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 94
   Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 95

Tables

   Table 1  - Subscription Template Attributes. . . . . . . . . . . . 20
   Table 2  - Subscription Description Attributes . . . . . . . . . . 35
   Table 3  - Printer Description Attributes Associated with
              Notification. . . . . . . . . . . . . . . . . . . . . . 39
   Table 4  - Operation-id assignments. . . . . . . . . . . . . . . . 40
   Table 5  - Attributes in Event Notification Content. . . . . . . . 45
   Table 6  - Additional Event Notification Content for Job Events. . 46
   Table 7  - Combinations of Events and Subscribed Events for
              "job-impressions-completed" . . . . . . . . . . . . . . 46
   Table 8  - Additional Event Notification Content for Printer
              Events. . . . . . . . . . . . . . . . . . . . . . . . . 46
   Table 9  - Printer Name in Event Notification Content. . . . . . . 48
   Table 10 - Event Name in Event Notification Content. . . . . . . . 48
   Table 11 - Event Time in Event Notification Content. . . . . . . . 48
   Table 12 - Job Name in Event Notification Content. . . . . . . . . 49
   Table 13 - Job State in Event Notification Content . . . . . . . . 49
   Table 14 - Printer State in Event Notification Content . . . . . . 50
   Table 15 - Information about the Delivery Method . . . . . . . . . 51
   Table 16 - Printer Conformance Requirements for Operations . . . . 74
Top   ToC   RFC3995 - Page 5
Figures

   Figure 1 - Model for Notification. . . . . . . . . . . . . . . . .  9
   Figure 2 - Model for Notification with Cascading Printers. . . . . 75
   Figure 3 - Opaque Use of a Notification Server Transparent to the
              Client. . . . . . . . . . . . . . . . . . . . . . . . . 76
   Figure 4 - Use of an Extended Notification Recipient transparent
              to the Printer. . . . . . . . . . . . . . . . . . . . . 77
   Figure 5 - Object Model for Notification . . . . . . . . . . . . . 78

1. Introduction

This IPP notification specification is an OPTIONAL extension to Internet Printing Protocol/1.1: Model and Semantics [RFC2911, RFC2910]. See Appendix 29 for a description of the base IPP documents. This document in combination with the following documents is intended to meet the most important notification requirements described in [RFC3997]: Internet Printing Protocol (IPP): "Job Progress Attributes" [RFC3381] Internet Printing Protocol (IPP): "The 'ippget' Delivery Method for Event Notifications" [RFC3996] This specification REQUIRES that clients and Printers support the 'ippget' Pull Delivery Method [RFC3996]. Conforming client and Printer implementations MAY support additional Push or Pull Delivery Methods as well. Note: this document does not define any Delivery Methods itself, but it does define the rules for conformance for Delivery Method Documents and their registration with IANA (see section 23.7.3). Refer to the Table of Contents for the layout of this document.

1.1. Notification Overview

This document defines operations that a client can perform in order to create Subscription Objects in a Printer and carry out other operations on them. A Subscription Object represents a Subscription abstraction. The Subscription Object specifies that when one of the specified Events occurs, the Printer delivers an asynchronous Event Notification to the specified Notification Recipient via the specified Delivery Method (i.e., protocol). When a client (called a Subscribing Client) performs an operation that creates a Subscription Object, the operation contains one or more Subscription Template Attributes Groups. Each such group holds
Top   ToC   RFC3995 - Page 6
   information used by the Printer to initialize a newly created
   Subscription Object.  The Printer creates one Subscription Object for
   each Subscription Template Attributes Group in the operation.  This
   group is like the Job Template Attributes group defined in [RFC2911].
   The following is an example of the information included in a
   Subscription Template Attributes Group (see section 5 for details on
   the Subscription Object attributes):

   1. The names of Subscribed Events that are of interest to the
      Notification Recipient.

   2. The address (URL) of one Notification Recipient for a Push
      Delivery Method or the method for a Pull Delivery Method.

   3. The Delivery Method (i.e., the protocol) which the Printer uses to
      deliver the Event Notification.

   4. Some opaque data that the Printer delivers to the Notification
      Recipient in the Event Notification.  For example, the
      Notification Recipient might use this opaque data as a forwarding
      address for the Event Notification.

   5. The charset to use in text fields within an Event Notification

   6. The natural language to use in the text fields of the Event
      Notification

   7. The requested lease time in seconds for the Subscription Object

   An operation that creates a Subscription Object is called a
   Subscription Creation Operation.  These operations include the
   following operations (see section 11.1 for further details):

      -  Job Creation operation: When a client performs such an
         operation (Print-Job, Print-URI, and Create-Job), a client can
         include zero or more Subscription Template Attributes Groups in
         the request.  The Printer creates one Subscription Object for
         each Subscription Template Attributes Group in the request, and
         the Printer associates each such Subscription Object with the
         newly created Job.  This document extends these operations'
         definitions in [RFC2911] by adding Subscription Template
         Attributes Groups in the request and Subscription Attributes
         Groups in the response.

      -  Create-Job-Subscriptions operation: A client can include one or
         more Subscription Template Attributes Groups in the request.
         The Printer creates one Subscription Object for each
Top   ToC   RFC3995 - Page 7
         Subscription Template Attributes Group and associates each with
         the job that is the target of this operation.

      -  Create-Printer-Subscriptions operation: A client can include
         one or more Subscription Template Attributes Groups in the
         request.  The Printer creates one Subscription Object for each
         Subscription Template Attributes Group and associates each with
         the Printer that is the target of this operation.

   For each of the above operations:

      -  the Printer associates a Subscription Object with the Printer
         or a specific Job.  When a Subscription Object is associated
         with a Job Object, it is called a Per-Job Subscription Object.
         When a Subscription Object is associated with a Printer Object,
         it is called a Per-Printer Subscription Object.

      -  the response contains one Subscription Attributes Group for
         each Subscription Template Attributes Group in the request and
         in the same order.  When the Printer successfully creates a
         Subscription Object, its corresponding Subscription Attributes
         Group contains the "notify-subscription-id" attribute.  This
         attribute uniquely identifies the Subscription Object and is
         analogous to a "job-id" for a Job object.  Some operations
         described below use the "notify-subscription-id" to identify
         the target Subscription Object.

   This document defines the following additional operations (see
   section 11.2 for further details):

   -  Restart-Job operation: When a client performs the Restart-Job
      operation [RFC2911], the Printer re-uses the same Job and its
      Subscription Objects.

   -  Validate-Job operation: When a client performs this operation, a
      client can include zero or more Subscription Template Attributes
      Groups in the request.  The Printer determines if it could create
      one Subscription Object for each Subscription Template Attributes
      Group in the request.  This document extends this operation's
      definition in [RFC2911] by adding Subscription Template Attributes
      Groups in the request and Subscription Attributes Groups in the
      response.

   -  Get-Subscription-Attributes operation: This operation allows a
      client to obtain the specified attributes of a target Subscription
      Object.
Top   ToC   RFC3995 - Page 8
   -  Get-Subscriptions operation: This operation allows a client to
      obtain the specified attributes of all Subscription Objects
      associated with the Printer or a specified Job.

   -  Renew-Subscription operation: This operation renews the lease on
      the target Per-Printer Subscription Object before it expires.  A
      newly created Per-Printer Subscription Object receives an initial
      lease.  It is the duty of the client to use this operation
      frequently enough to preserve a Per-Printer Subscription Object.
      The Printer deletes a Per-Printer Subscription Object when its
      lease expires.  A Per-Job Subscription Object last exactly as long
      as its associated Job Object and thus doesn't have a lease.

   -  Cancel-Subscription operation: This operation (1) cancels the
      lease on the specified Per-Printer Subscription Object and thereby
      deletes the Per-Printer Subscription Object or (2) deletes the
      Per-Job Subscription Object.

   When an Event occurs, the Printer finds all Subscription Objects
   listening for the Event (see section 9 for details on finding such
   Subscription Objects).  For each such Subscription Object, the
   Printer:

   a) generates an Event Notification with information specified in
      section 9, AND

   b) either:

      i)  If the Delivery Method is a Push Delivery Method as indicated
          by the presence of the Subscription Object's "notify-
          recipient-uri" attribute, delivers the Event Notification
          using the Delivery Method and target address identified in the
          Subscription Object's "notify-recipient-uri" attribute, OR

      ii) If the Delivery Method is a Pull Delivery Method as indicated
          by the presence of the Subscription Object's "notify-pull-
          method" attribute, saves Event Notification for a time period
          called the Event Life defined by the Delivery Method, i.e.,
          the Notification Recipient is expected to fetch the Event
          Notifications.

2. Models for Notification

2.1. Model for Simple Notification (Normative)

As part of a Subscription Creation Operation, an IPP Printer (i.e., located in an output device or a server) creates one or more Subscription Objects. In a Subscription Creation Operation, the
Top   ToC   RFC3995 - Page 9
   client specifies the Notification Recipient to which the Printer is
   to deliver Event Notifications.  A Notification Recipient can be the
   Subscribing Client or a third party.

   Figure 1 shows the Notification model for a simple Client-Printer
   relationship.

   embedded printer:

                                        output device or server
   PDA, desktop, or server                 +---------------+
        +--------+                         |  ###########  |
        | client |-----Subscription ---------># Printer #  |
        +--------+  Creation Operation     |  # Object  #  |
     +------------+                        |  #####|#####  |
     |Notification|                        +-------|-------+
     |Recipient   |<----IPP Event Notifications----+
     +------------+    (Job and/or Printer Events)

                  Figure 1 - Model for Notification

2.2. Additional Models for Notification (Informative)

Additional models have been proposed (see Appendices 16, 17, and 18).

3. Terminology

This section defines terminology used throughout this document. Other terminology is defined in [RFC2911].

3.1. Conformance Terminology

Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to conformance as defined in RFC 2119 [RFC2119] and [RFC2911] section 12.1. If an implementation supports the extension defined in this document, then these terms apply; otherwise, they do not. These terms define conformance to this document only; they do not affect conformance to other documents, unless explicitly stated otherwise. Note: a feature that is OPTIONAL in this document becomes REQUIRED if the Printer implements a Delivery Method that REQUIRES the feature. READ-ONLY - an adjective used in an attribute definition to indicate that an IPP Printer MUST NOT allow the attribute's value to be modified.
Top   ToC   RFC3995 - Page 10

3.2. Other Terminology

This document uses the same terminology as [RFC2911], such as "client", "Printer", "attribute", "attribute value", "keyword", "operation", "request", "response", "administrator", "operator", and "support". In addition, the following terms are defined for use in this document and the Delivery Method Documents: Compound Event Notification - two or more Event Notifications that a Printer delivers together as a single request or response. The Delivery Method Document specifies whether the Delivery Method supports Compound Event Notifications. Delivery Method - the mechanism by which the Printer delivers an Event Notification. Delivery Method Document - a document, separate from this document, that defines a Delivery Method. Event - some occurrence (either expected or unexpected) within the printing system of a change of state, condition, or configuration of a Job or Printer object. An Event occurs only at one instant in time and does not span the time the physical Event takes place. For example, jam-occurred and jam-cleared are two distinct, instantaneous Events, even though the jam may last for a while. Event Life - For a Pull Delivery Method, the length of time in seconds after an Event occurs during which the Printer will retain that Event for delivery in an Event Notification. After the Event Life expires, the Printer will no longer deliver an Event Notification for that Event in such a response. Event Notification - the information about an Event that the Printer delivers when an Event occurs. Event Notification Attributes Group - The attributes group which is used to deliver an Event Notification in a request (Push Delivery Methods) or a response (Pull Delivery Methods). Human Consumable Event Notification - localized text for human consumption only. There is no standardized format and thus programs should not try to parse this text. Job Creation operation - One of the operations that creates a Job object: Print-Job, Print-URI and Create-Job. The Restart-Job operation [RFC2911] is not considered a Job Creation operation, since the Printer re-uses the existing Job object. The Validate-Job operation is not considered a Job Creation operation because no Job
Top   ToC   RFC3995 - Page 11
   object is created.  Therefore, when a statement also applies to
   either the Restart-Job and/or the Validate-Job operation, they are
   mentioned explicitly.

   Job Event - an Event caused by some change in a particular job on the
   Printer, e.g., 'job-completed'.

   Machine Consumable Event Notification - bytes for program
   consumption.  The bytes are formatted according to the Delivery
   Method document.

   Notification - when not in the phrases 'Event Notification' and
   'Notification Recipient' - the concepts of this specification, i.e.,
   Events, Subscription Objects, and Event Notifications.

   Notification Recipient - the entity to which the Printer delivers an
   Event Notification.  For Push Delivery Methods, the IPP Printer sends
   the Notifications to a Notification Recipient.  For Pull Delivery
   Methods, the Notification Recipient is acting in the role of an IPP
   client and requests Event Notifications and so the terms "client" and

   "Notification Recipient" are used interchangeably with such Delivery
   Methods.  For example, see [RFC3996].

   Per-Job Subscription Object - A Subscription Object that is
   associated with a single Job.  The Create-Job-Subscriptions operation
   and Job Creation operations create such an object.

   Per-Printer Subscription Object - A Subscription Object that is
   associated with the Printer as a whole.  The Create-Printer-
   Subscriptions operation creates such an object.

   Printer Event - an Event caused by some change in the Printer that is
   not specific to a job, e.g., 'printer-state-changed'.

   Pull Delivery Method - The Printer saves Event Notifications for some
   event life time and expects the Notification Recipient to request
   Event Notifications.  The Printer delivers the Event Notifications in
   a response to such a request.

   Push Delivery Method -The Printer delivers the Event Notification
   shortly after an Event occurs.

   Subscribed Event - an Event that the Subscribing Client expresses
   interest in by making it a value of the "notify-events" attribute on
   a Subscription Object.

   Subscribed Job Event - a Subscribed Event that is a Job Event.
Top   ToC   RFC3995 - Page 12
   Subscribed Printer Event - a Subscribed Event that is a Printer
   Event.

   Subscribing Client - The client that creates the Subscription Object.

   Subscription Attributes Group - The attributes group in a response
   that contains Subscription Object attributes.

   Subscription Creation Operation - An operation that creates a
   Subscription Object:  Job Creation operations, Create-Job-
   Subscriptions operation, Create-Printer-Subscriptions operation.  In
   the context of a Job Creation operation, a Subscription Creation
   Operation is the part of the Job Creation operation that creates one
   or more Subscription objects.  The Restart-Job operation [RFC2911] is
   not considered a Subscription Creation Operation, since the Printer
   re-uses the Job's existing Subscription Objects, rather than creating
   any new Subscription Objects.

   Subscription Creation Request - The request portion of a Subscription
   Creation Operation.

   Subscription Description Attributes - Subscription Object attributes
   that a Printer supplies during a Subscription Creation Operation.

   Subscription Object - An object containing a set of attributes that
   indicate:  the Notification Recipient (for Push Delivery Method
   only), the Delivery Method, the Subscribed Events that cause the
   Printer to deliver an Event Notification, and the information to
   include in an Event Notification.

   Subscription Template Attributes - Subscription Object attributes
   that a client can supply in a Subscription Creation Operation and
   associated Printer Object attributes that specify supported and
   default values for the Subscription Object attributes.

   Subscription Template Attributes Group - The attributes group in a
   request that contains Subscription Object attributes that are
   Subscription Template Attributes.

4. Object Relationships

This section defines the object relationships between the Printer, Job, and Subscription Objects. It does not define the implementation. For an illustration of these relationships, see Appendix 19.
Top   ToC   RFC3995 - Page 13

4.1. Printer and Per-Printer Subscription Objects

1. A Printer object can be associated with zero or more Per-Printer Subscription Objects. 2. Each Per-Printer Subscription Object is associated with exactly one Printer object.

4.2. Printer, Job and Per-Job Subscription Objects

1. A Printer object is associated with zero or more Job objects. 2. Each Job object is associated with exactly one Printer object. 3. A Job object is associated with zero or more Per-Job Subscription Objects. 4. Each Per-Job Subscription Object is associated with exactly one Job object.

5. Subscription Object

A Subscribing Client creates a Subscription Object with a Subscription Creation Operation in order to indicate its interest in certain Events. See section 11 for a description of these operations. When an Event occurs, the Subscription Object specifies to the Printer where to deliver Event Notifications for Push Delivery Methods only, how to deliver them, and what to include in them. See section 9 for details on the contents of an Event Notification. Using the IPP Job Template attributes as a model (see [RFC2911] section 4.2), the attributes of a Subscription Object are divided into two categories: Subscription Template Attributes and Subscription Description Attributes. Subscription Template attributes are, in turn, like the Job Template attributes, divided into 1. Subscription Object attributes that a client can supply in a Subscription Creation Request and 2. their associated Printer Object attributes that specify supported and default values for the Subscription Object attributes The remainder of this section specifies general rules for Subscription Template Attributes and describes each attribute in a Subscription Object.
Top   ToC   RFC3995 - Page 14

5.1. Rules for Support of Subscription Template Attributes

Subscription Template Attributes are fundamental to the Notification model described in this specification. The client supplies these attributes in Subscription Creation Operations and the Printer uses these attributes to populate a newly created Subscription Object. Subscription Objects attributes that are Subscription Template Attributes conform to the following rules: 1. Each attribute's name starts with the prefix string "notify-" and this document calls such attributes "notify-xxx". 2. For each "notify-xxx" Subscription Object attribute defined in column 1 of Table 1 in section 5.3, Table 1 specifies corresponding Printer attributes: "notify-xxx-default", "notify- xxx-supported", "yyy-supported" and "notify-max-xxx-supported" defined in column 2 of Table 1. Note "xxx" stands for the same string in each case and "yyy" stands for some other string. 3. If a Printer supports "notify-xxx" in column 1 of Table 1, then the Printer MUST support all associated attributes specified in column 2 of Table 1. For example, Table 1 shows that if the Printer supports "notify-events", it MUST support "notify-events- default", "notify-events-supported" and "notify-max-events- supported". 4. If a Printer does not support "notify-xxx" in column 1 of Table 1, then the Printer MUST NOT support any associated "notify-yyy" attributes specified in column 2 of Table 1. For example, Table 1 shows that if the Printer doesn't support "notify-events", it MUST NOT support "notify-events-default", "notify-events-supported" and "notify-max-events-supported". Note this rule does not apply to attributes whose names do not start with the string "notify-" and are thus defined in another object and used by other attributes. 5. Most "notify-xxx" attributes have a corresponding "yyy-supported" attribute that specifies the supported values for "notify-xxx". Column 2 of Table 1 specifies the name of each "yyy-supported" attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used when "yyy-supported" is "notify-xxx-supported". 6. Some "notify-xxx" attributes have a corresponding "notify-xxx- default" attribute that specifies the value for "notify-xxx" if the client does not supply it. Column 2 of Table 1 specifies the name of each "notify-xxx-default" attribute. The naming rules of IPP/1.1 (see [RFC2911]) are used.
Top   ToC   RFC3995 - Page 15
   If a client wishes to present an end user with a list of supported
   values from which to choose, the client SHOULD query the Printer for
   its supported value attributes.  The client SHOULD also query the
   default value attributes.  If the client then limits selectable
   values to only those values that are supported, the client can
   guarantee that the values supplied by the client in the create
   request all fall within the set of supported values at the Printer.
   When querying the Printer, the client MAY enumerate each attribute by
   name in the Get-Printer-Attributes Request, or the client MAY just
   supply the 'subscription-template' group name in order to get the
   complete set of supported attributes (both supported and default
   attributes - see section 11.2.3).

5.2. Rules for Processing Subscription Template Attributes

This section defines a detailed set of rules that a Printer follows when it processes Subscription Template Attributes in a Subscription Creation Request. These rules are similar to the rules for processing Operation attributes in [RFC2911]. That is, the Printer may or may not support an attribute and a client may or may not supply the attribute. Some combinations of these cases are OK. Others return warnings or errors, and perhaps a list of unsupported attributes. A Printer MUST implement the following behavior for processing Subscription Template Attributes in a Subscription Creation Request: 1. If a client supplies a "notify-xxx" attribute from column 1 of Table 1 and the Printer supports it and its value, the Printer MUST populate the attribute on the created Subscription Object. 2. If a client supplies a "notify-xxx" attribute from column 1 of Table 1 and the Printer doesn't support it or its value, the Printer MUST NOT populate the attribute on the created Subscription Object with it. The Printer MUST do one of the following: a) If the value of the "notify-xxx" attribute is unsupported, the Printer MUST return the attribute with its value in the Subscription Attributes Group of the response. b) If "notify-xxx" is an unsupported attribute, the Printer MUST return the attribute in the Subscription Attributes Group of the response with the 'unsupported' out-of-band value. Note: The rules of this step are the same as for Unsupported Attributes [RFC2911] section 3.1.7. except that the unsupported attributes are returned in the Subscription Attributes Group
Top   ToC   RFC3995 - Page 16
      rather than the Unsupported Attributes Group because Subscription
      Creation Operations can create more than one Subscription Object).

   3. If a client is REQUIRED to supply a "notify-xxx" attribute from
      column 1 of Table 1 and the Printer doesn't support the supplied
      value, the Printer MUST NOT create a Subscription Object.  The
      rules for Unsupported Attributes in step #2 still apply.

   4. If a client does not supply a "notify-xxx" attribute from column 1
      of Table 1 and the attribute is REQUIRED for the client to supply,
      the Printer MUST reject the Subscription Creation Operation
      (including Job Creation operations) without creating a
      Subscription Object, and MUST return in the response:

      a) the status code 'client-error-bad-request' AND

      b) no Subscription Attribute Groups.

   5. If a client does not supply a "notify-xxx" attribute from column 1
      of Table 1 that is OPTIONAL for the client to supply, and column 2
      of Table 1 either:

      a) specifies a "notify-xxx-default" attribute, the Printer MUST
         behave as if the client had supplied the "notify-xxx-default"
         attribute (see step #1) and populate the Subscription object
         with the value of the "notify-xxx-default" attribute as part of
         the Subscription Creation operation (unlike Job Template
         attributes where the Printer does not populate the Job object
         with defaults - see [RFC2911]) OR

      b) does not specify a "notify-xxx-default" attribute, the Printer
         MUST populate the "notify-xxx" attribute on the Subscription
         Object according to the definition of the "notify-xxx"
         attribute in a section 5.3.  For some attributes, the "notify-
         xxx" is populated with the value of some other attribute, and
         for others, the "notify-xxx" is NOT populated on the
         Subscription object at all.

   6. A Printer MUST create a Subscription Object for each Subscription
      Template Attributes group in a request unless the Printer:

      a) encounters some attributes in a Subscription Template
         Attributes Group that require the Printer not to create the
         Subscription Object OR

      b) would create a Per-Job Subscription Object when it doesn't have
         space for another Per-Job Subscription Object OR
Top   ToC   RFC3995 - Page 17
      c) would create a Per-Printer Subscription Object when it doesn't
         have space for another Per-Printer Subscription Object.

   7. A response MUST contain one Subscription Attributes Group for each
      Subscription Template Attributes Group in the request (and in the
      same order) whether the Printer creates a Subscription Object from
      the Subscription Template Attributes Group or not.  However, the
      attributes in each Subscription Attributes Group can be in any
      order.

   8. The Printer MUST populate each Subscription Attributes Group of
      the response such that each contains:

      a) the "notify-subscription-id" attribute (see section 5.4.1), if
         and only if the Printer creates a Subscription Object.

      b) the "notify-lease-duration" attribute (see section 5.3.8), if
         and only if the Printer creates a Per-Printer Subscription
         Object.  The value of this attribute is the value of the
         Subscription Object's "notify-lease-duration" attribute.  This
         value MAY be different from the client-supplied value (see
         section 5.3.8).  If a client supplies this attribute in the
         creation of a Per-Job Subscription Object, it MUST appear in
         this group with the out-of-band value 'unsupported' to indicate
         that the Printer doesn't support it in this context.

      c) all of the unsupported Subscription Template Attributes from
         step #2.  Note, they are not returned in the Unsupported
         Attributes Group in order to separate the unsupported
         attributes for each Subscription Object.

      d) the "notify-status-code" attribute if the Printer does not
         create the Subscription Object or if there are unsupported
         attributes from step #2.  The possible values of the "notify-
         status-code" attribute are shown below (see section 13 for more
         details).  The Printer returns the first value in the list
         below that describes the status.

         'client-error-uri-scheme-not-supported':  the Subscription
            Object was not created because the scheme of the "notify-
            recipient-uri" attribute is not supported.  See section 13.1
            for more details about this status code.  See step #3 in
            this section for the case that causes this error, and the
            resulting step #6a) that causes the Printer not to create
            the Subscription Object.
Top   ToC   RFC3995 - Page 18
         'client-error-attributes-or-values-not-supported':  the
            Subscription Object was not created because the method of
            the "notify-pull-method" attribute is not supported.  See
            section 13.1 for more details about this status code.  See
            step #3 in this section for the case that causes this error,
            and the resulting step #6a) that causes the Printer not to
            create the Subscription Object.

         'client-error-too-many-subscriptions':  the Subscription
            Object was not created because the Printer has no space for
            additional Subscription Objects.  The client MAY try again
            later.  See section 13.3 for more details about this status
            code.  See steps #6b) and #6c) in this section for the cases
            that causes this error.

         'successful-ok-too-many-events':  the Subscription Object was
            created without the "notify-events" values included in this
            Subscription Attributes Group because the "notify-events"
            attribute contains too many values.  See section 13.4 for
            more details about this status code.  See step #2 in this
            section and section 5.3.3 for the cases that cause this
            status code.

         'successful-ok-ignored-or-substituted-attributes':  the
            Subscription Object was created but some supplied
            Subscription Template Attributes are unsupported.  These
            unsupported attributes are also in the Subscription
            Attributes Group.  See section 13.5 for more details about
            this status code.  See step #2 in this section for the cases
            that cause this status code.

   9. The Printer MUST validate all Subscription Template Attributes and
      MUST return all unsupported attributes and values in the
      corresponding Subscription Attributes Group of the response (see
      step #2) unless it determines that it could not create additional
      Subscription Objects because of condition #6b) or condition #6c).
      Then, the Printer NEED NOT validate these additional Subscription
      Template Attributes and the client MUST NOT expect to find
      unsupported attributes from step #2 in such additional
      Subscription Attribute Groups.



(page 18 continued on part 2)

Next Section