Tech-invite  3GPPspecsRELsGlossariesSIPRFCs
8887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100

in Index   Prev   Next

RFC 3995

Internet Printing Protocol (IPP): Event Notifications and Subscriptions

Pages: 95
Proposed Standard
Updates:  29112910
Part 3 of 4 – Pages 50 to 75
First   Prev   Next

Top   ToC   RFC3995 - Page 50   prevText

10. Delivery Methods

A Delivery Method is the mechanism, i.e., protocol, by which the Printer delivers an Event Notification to a Notification Recipient. There are several potential Delivery Methods for Event Notifications, standardized, as well as proprietary. This specification REQUIRES that the 'ippget' Pull Delivery Method [RFC3996] be supported. Conforming implementations MAY support additional Push or Pull Delivery Methods as well. This document does not define any of these delivery mechanisms. Each Delivery Method MUST be defined in a Delivery Method Document that is separate from this document. New Delivery Methods will be created as needed using an extension to the registration procedures defined in [RFC2911]. Such documents are registered with IANA (see section 23.7.3). The following sorts of Delivery Methods are possible: - The Notification Recipient polls for Event Notifications at intervals directed by the Printer - The Printer delivers Event Notifications to the Notification Recipient using http as the transport. - The Printer delivers an email message. This section specifies how to define a Delivery Method Document and what to put in such a document. A Delivery Method Document MUST contain an exact copy of the following paragraph, caption and table. In addition, column 2 of the table in the Delivery Method Document MUST contain answers to questions in column 1 for the Delivery Method. Also, the Delivery Method document MUST contain a reference to this document and call that reference [RFC3995] because the table contains an [RFC3995] reference. If a Printer supports this Delivery Method, the following are its characteristics.
Top   ToC   RFC3995 - Page 51
   Table 15 - Information about the Delivery Method

   Document Method Conformance Requirement     Delivery Method
                                               Realization

   1.  What is the URL scheme name for the Push Delivery Method or the
       keyword method name for the Pull Delivery Method?

   2.  Is the Delivery Method REQUIRED, RECOMMENDED, or OPTIONAL for an
       IPP Printer to support?

   3.  What transport and delivery protocols does the Printer use to
       deliver the Event Notification Content, i.e., what is the entire
       network stack?

   4.  Can several Event Notifications be combined into a Compound Event
       Notification?

   5.  Is the Delivery Method initiated by the Notification Recipient
       (pull), or by the Printer (push)?

   6.  Is the Event Notification content Machine Consumable or Human
       Consumable?

   7.  What section in this document answers the following question?
       For a Machine Consumable Event Notification, what is the
       representation and encoding of values defined in section 9.1 of
       [RFC3995] and the conformance requirements thereof?  For a Human
       Consumable Event Notification, what is the representation and
       encoding of pieces of information defined in section 9.2 of
       [RFC3995] and the conformance requirements thereof?

   8.  What are the latency and reliability of the transport and
       delivery protocol?

   9.  What are the security aspects of the transport and delivery
       protocol, e.g., how it is handled in firewalls?

   10.  What are the content length restrictions?

   11.  What are the additional values or pieces of information that a
        Printer delivers in an Event Notification content and the
        conformance requirements thereof?

   12.  What are the additional Subscription Template and/or
        Subscription Description attributes and the conformance
        requirements thereof?
Top   ToC   RFC3995 - Page 52
   13.  What are the additional Printer Description attributes and the
        conformance requirements thereof?

11. Operations for Notification

This section defines all of the operations for Notification. Section 7.1 assigns the "operation-id" for each operation. The following two sub-sections define Subscription Creation Operations, and other operations.

11.1. Subscription Creation Operations

This section defines the Subscription Creation Operations. The first section on Create-Job-Subscriptions gives most of the information. The other Subscription Creation Operations refer to the section on Create-Job-Subscriptions, even though the Create-Job-Subscriptions operation is the only OPTIONAL operation in this document (see section 12). A Printer MUST support Create-Printer-Subscriptions and the Subscription Template Attributes Group in Job Creation operations. It MAY support Create-Job-Subscriptions operations.

11.1.1. Create-Job-Subscriptions Operation

The operation creates one or more Per-Job Subscription Objects. The client supplies one or more Subscription Template Attributes Groups each containing one or more of Subscription Template Attributes (defined in section 5.3). Except for errors, the Printer MUST create exactly one Per-Job Subscription Object from each Subscription Template Attributes Group in the request, even if the newly created Subscription Object would have identical behavior to some existing Subscription Object. The Printer MUST associate each newly created Per-Job Subscription Object with the target Job, which is specified by the "notify-job-id" operation attribute. The Printer MUST accept the request in any of the target job's 'not- completed' states, i.e., 'pending', 'pending-held', 'processing', or 'processing-stopped'. The Printer MUST NOT change the job's "job- state" attribute because of this operation. If the target job is in any of the 'completed' states, i.e., 'completed', 'canceled', or 'aborted, then the Printer MUST reject the request and return the 'client-error-not-possible' status code; the response MUST NOT contain any Subscription Attribute Groups.
Top   ToC   RFC3995 - Page 53
   Access Rights:  To create Per-Job Subscription Objects, the
   authenticated user (see [RFC2911] section 8.3) performing this
   operation MUST (1) be the job owner, (2) have Operator or
   Administrator access rights for this Printer (see [RFC2911] sections
   1 and 8.5), or (3) be otherwise authorized by the Printer's
   administrator-configured security policy to create Per-Job
   Subscription Objects for the target job.  Otherwise the Printer MUST
   reject the operation and return: the 'client-error-forbidden',
   'client-error-not-authenticated', or 'client-error-not-authorized'
   status code as appropriate.

11.1.1.1. Create-Job-Subscriptions Request
The following groups of attributes are part of the Create-Job- Subscriptions Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.1. Target: The "printer-uri" attribute which defines the target for this operation as described in [RFC2911] section 3.1.5. Requesting User Name: The "requesting-user-name" attribute SHOULD be supplied by the client as described in [RFC2911] section 8.3.
11.1.1.1.1. notify-job-id (integer(1:MAX))
The client MUST supply this attribute and it MUST specify the Job object to associate the Per-Job Subscription with. The value of "notify-job-id" MUST be the value of the "job-id" of the associated Job object. If the client does not supply this attribute, the Printer MUST reject this request with a 'client-error-bad-request' status code. Group 2-N: Subscription Template Attributes For each occurrence of this group: The client MUST supply one or more Subscription Template Attributes in any order. See section 5.3 for a description of each such attribute. See section 5.2 for details on processing these attributes.
Top   ToC   RFC3995 - Page 54
11.1.1.2. Create-Job-Subscriptions Response
The Printer MUST return to the client the following sets of attributes as part of a Create-Job-Subscriptions response: Group 1: Operation Attributes Status Message: In addition to the REQUIRED status code returned in every response, the response OPTIONALLY includes a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in [RFC2911] sections 13 and 3.1.6. In this group, the Printer can return any status codes defined in [RFC2911] and section 12. The following is a description of the important status codes: successful-ok: the Printer created all Subscription Objects requested (see [RFC2911]). successful-ok-ignored-subscriptions: the Printer created some Subscription Objects requested but some failed. The Subscription Attributes Groups with a "notify-status-code" attribute are the ones that failed (see section 12.1). client-error-ignored-all-subscriptions: the Printer created no Subscription Objects requested and all failed. The Subscription Attributes Groups with a "notify-status-code" attribute are the ones that failed (see section 12.2). client-error-not-possible: For this operation and other Per-Job Subscription operations, this error can occur because the specified Job has already completed (see [RFC2911], whether or not the Job is retained in the Job Retention and/or Job History phases (see [RFC2911] section 4.3.7.1). Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.2. Group 2: Unsupported Attributes See [RFC2911] section 3.1.7 for details on returning Unsupported Attributes. This group does not contain any unsupported Subscription Template Attributes; they are returned in the Subscription Attributes Group (see below).
Top   ToC   RFC3995 - Page 55
   Group 3-N: Subscription Attributes

      These groups MUST be returned unless the Printer is unable to
      interpret the entire request, e.g., the "status-code" parameter
      returned in Group 1 has the value: 'client-error-bad-request'.

      "notify-status-code" (type2 enum):
         Indicates the status of this subscription (see section 13 for
         the status code definitions).  Section 5.2 defines when this
         attribute MUST be present in this group.

      See section 5.2 for details on the contents of each occurrence of
      this group.

11.1.2. Create-Printer-Subscriptions operation

The operation is identical to Create-Job-Subscriptions with exceptions noted in this section. The operation creates Per-Printer Subscription Objects instead of Per-Job Subscription Objects, and associates each newly created Per- Printer Subscription Object with the Printer specified by the operation target rather than with a specific Job. The Printer MUST accept the request in any of its states, i.e., 'idle', 'processing', or 'stopped'. The Printer MUST NOT change its "printer-state" attribute because of this operation. Access Rights: To create Per-Printer Subscription Objects, the authenticated user (see [RFC2911] section 8.3) performing this operation MUST have (1) Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise authorized by the Printer's administrator-configured security policy to create Per-Printer Subscription Objects for this Printer. Otherwise, the Printer MUST reject the operation and return: the 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' status code as appropriate.
11.1.2.1. Create-Printer-Subscriptions Request
The groups are identical to the Create-Job-Subscriptions (see section 11.1.1.1) except that the Operation Attributes group MUST NOT contain the "notify-job-id" attribute. If the client does supply the "notify-job-id" attribute, then the Printer MUST treat it as any other unsupported Operation attribute and MUST return it in the Unsupported Attributes group.
Top   ToC   RFC3995 - Page 56
11.1.2.2. Create-Printer-Subscriptions Response
The groups are identical to the Create-Job-Subscriptions (see section 11.1.1.2).

11.1.3. Job Creation Operations - Extensions for Notification

This document extends the Job Creation operations (see section 3.2) to create Subscription Objects as a part of the operation. The Job Creation operations are identical to Create-Job-Subscriptions operation with exceptions noted in this section. Unlike the Create-Job-Subscriptions operation, a Job Creation operation associates the newly created Subscription Objects with the Job object created by this operation. The operation succeeds if and only if the Job creation succeeds. If the Printer does not create some or all of the requested Subscription Objects, the Printer MUST return a 'successful-ok-ignored-subscriptions' status-code instead of a 'successful-ok' status-code, but the Printer MUST NOT reject the operation because of a failure to create Subscription Objects. If the Job Creation operation includes a Job Template group, the client MUST supply it after the Operation Attributes group and before the first Subscription Template Attributes Group. If a Printer does not support this Notification specification, then it MUST treat the Subscription Attributes Group like an unknown group and ignore it (see [RFC2911] section 5.2.2). Because the Printer ignores the Subscription Attributes Group, it doesn't return them in the response either, thus indicating to the client that the Printer doesn't support Notification. After completion of a successful Job Creation operation, the Printer generates a 'job-created' event (see section 5.3.3.4.3). Access Rights: To create Per-Job Subscription Objects, the authenticated user (see [RFC2911] section 8.3) performing this operation MUST either have permission to create Jobs on the Printer or have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5). Otherwise the Printer MUST reject the operation and return: the 'client-error-forbidden', 'client-error- not-authenticated', or 'client-error-not-authorized' status code as appropriate.
Top   ToC   RFC3995 - Page 57
11.1.3.1. Job Creation Request
The groups for this operation are sufficiently different from the Create-Job-Subscriptions operation that they are all presented here. The following groups of attributes are supplied as part of a Job Creation Request: Group 1: Operation Attributes Same as defined in [RFC2911] for Print-Job, Print-URI, and Create-Job requests. Group 2: Job Template Attributes The client OPTIONALLY supplies a set of Job Template attributes as defined in [RFC2911] section 4.2. Group 3 to N: Subscription Template Attributes The same as Group 2-N in Create-Job-Subscriptions. See section 11.1.1.1. Group N+1: Document Content (Print-Job only) The client MUST supply the document data to be processed.
11.1.3.2. Job Creation Response
The Printer MUST return to the client the following sets of attributes as part of a Print-Job, Print-URI, and Create-Job Response: Group 1: Operation Attributes Status Message: As defined in [RFC2911] for Print-Job, Print-URI, and Create- Job requests. In this group, the Printer can return any status codes defined in [RFC2911] and section 12. The following is a description of the important status codes: successful-ok: the Printer created the Job and all Subscription Objects requested (see [RFC2911]. successful-ok-ignored-subscriptions: the Printer created the Job and not all of the Subscription Objects requested
Top   ToC   RFC3995 - Page 58
            (see section 12.1).  This status-code hides 'successful-ok-
            xxx' status-codes that could reveal problems in Job
            creation.  The Printer MUST NOT return the 'client-error-
            ignored-all-subscriptions' status code for Job Creation
            operations because the Printer returns an error status-code
            only when it fails to create a Job.

         Natural Language and Character Set:
            The "attributes-charset" and "attributes-natural-language"
            attributes as described in [RFC2911] section 3.1.4.2.

   Group 2: Unsupported Attributes

      See [RFC2911] section 3.1.7 for details on returning Unsupported
      Attributes.  This group does not contain any unsupported
      Subscription Template Attributes; they are returned in the
      Subscription Attributes Group (see below).

   Group 3: Job Object Attributes

      The "job-id" of the Job Object just created, etc., as defined in
      [RFC2911] for Print-Job, Print-URI, and Create-Job requests.

   Group 4 to N: Subscription Attributes

      These groups MUST be returned if and only if the client supplied
      Subscription Template Attributes and the operation was accepted.

      See section 5.2 for details on the contents of each occurrence of
      this group.

11.2. Other Operations

This section defines other operations on Subscription objects.

11.2.1. Restart-Job Operation - Extensions for Notification

The Restart-Job operation [RFC2911] is neither a Job Creation operation nor a Subscription Creation operation (see section 3.2). For the Restart-Job operation, the client MUST NOT supply any Job Subscription Attributes Groups. The Printer MUST treat any supplied Job Subscription Attributes as unsupported attributes. For this operation, the Printer does not return a job-id or any Subscription Attributes groups because the Printer reuses the existing Job object with the same job-id and the existing Per-Job Subscription Objects with the same subscription-ids. However, after
Top   ToC   RFC3995 - Page 59
   successful completion of this operation, the Printer generates a
   'job-created' event (see section 5.3.3.4.3).

11.2.2. Validate-Job Operation - Extensions for Notification

A client can test whether one or more Subscription Objects could be created using the Validate-Job operation. The client supplies one or more Subscription Template Attributes Groups (defined in section 5.3), just as in a Job Creation request. A Printer MUST support this extension to this operation. The Printer MUST accept requests that are identical to the Job Creation request defined in section 11.1.3.1, except that the request MUST NOT contain document data. The Printer MUST return the same groups and attributes as the Print- Job operation (section 11.1.3.1) with the following exceptions. The Printer MUST NOT return a Job Object Attributes Group because no Job is created. The Printer MUST NOT return the "notify-subscription-id" attribute in any Subscription Attribute Group because no Subscription Object is created. If the Printer would succeed in creating a Subscription Object, the corresponding Subscription Attributes Group either has no 'status- code' attribute or a 'status-code' attribute with a value of 'successful-ok-too-many-events' or 'successful-ok-ignored-or- substituted-attributes' (see sections 5.2 and 13). The status-codes have the same meaning as in Job Creation except the results state what "would happen". The Printer MUST validate Subscription Template Attributes Groups in the same manner as the Job Creation operations.

11.2.3. Get-Printer-Attributes - Extensions for Notification

This operation is extended so that it returns Printer attributes defined in this document. A Printer MUST support this extension to this operation. In addition to the requirements of [RFC2911] section 3.2.5, a Printer MUST support the following additional values for the "requested- attributes" Operation attribute in this operation and return such attributes in the Printer Object Attributes group of its response. 1. Subscription Template Attributes: Each supported attribute in column 2 of Table 1.
Top   ToC   RFC3995 - Page 60
   2. New Printer Description Attributes: Each supported attribute in
      section 6.

   3. New Group Name: The 'subscription-template' group name, which
      names all supported Subscription Template Attribute in column 2 of
      Table 1.  This group name is also used in the Get-Subscription-
      Attributes and Get-Subscriptions operation with an analogous
      meaning.

   4. Extended Group Name: The 'all' group name, which names all Printer
      attributes according to [RFC2911] section 3.2.5.  In this
      extension 'all' names all attributes specified in [RFC2911] plus
      those named in items 1 and 2 of this list.

11.2.4. Get-Subscription-Attributes operation

This operation allows a client to request the values of the attributes of a Subscription Object. A Printer MUST support this operation. This operation is almost identical to the Get-Job-Attributes operation (see [RFC2911] section 3.3.4). The only differences are that the operation is directed at a Subscription Object rather than a Job object, and the returned attribute group contains Subscription Object attributes rather than Job object attributes. Access Rights: The authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. Otherwise the Printer MUST reject the operation and return: the 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' status code as appropriate. Furthermore, the Printer's security policy MAY limit which attributes are returned, in a manner similar to the Get-Job-Attributes operation (see [RFC2911] end of section 3.3.4.2).
11.2.4.1. Get-Subscription-Attributes Request
The following groups of attributes are part of the Get-Subscription- Attributes request: Group 1: Operation Attributes Natural Language and Character Set:
Top   ToC   RFC3995 - Page 61
      The "attributes-charset" and "attributes-natural-language"
      attributes as described in section [RFC2911] 3.1.4.1.

   Target:
      The "printer-uri" attribute which defines the target for this
      operation as described in [RFC2911] section 3.1.5.

   Requesting User Name:
      The "requesting-user-name" attribute SHOULD be supplied by the
      client as described in [RFC2911] section 8.3.

11.2.4.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this attribute. This attribute specifies the Subscription Object from which the client is requesting attributes. If the client omits this attribute, the Printer MUST reject this request with the 'client- error-bad-request' status code.
11.2.4.1.2. "requested-attributes" (1setOf keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST support this attribute. This attribute specifies the attributes of the specified Subscription Object that the Printer MUST return in the response. Each value of this attribute is either an attribute name (defined in sections 5.3 and 5.4) or an attribute group name. The attribute group names are: - 'subscription-template': all attributes that are both defined in section 5.3 and present on the specified Subscription Object (column 1 of Table 1). - 'subscription-description': all attributes that are both defined in section 5.4 and present on the specified Subscription Object (Table 2). - 'all': all attributes that are present on the specified Subscription Object. A Printer MUST support all these group names. If the client omits this attribute, the Printer MUST respond as if this attribute had been supplied with a value of 'all'.
11.2.4.2. Get-Subscription-Attributes Response
The Printer returns the following sets of attributes as part of the Get-Subscription-Attributes Response:
Top   ToC   RFC3995 - Page 62
   Group 1: Operation Attributes

   Status Message:
      Same as [RFC2911].

   Natural Language and Character Set:
      The "attributes-charset" and "attributes-natural-language"
      attributes as described in [RFC2911] section 3.1.4.2.  The
      "attributes-natural-language" MAY be the natural language of the
      Subscription Object, rather than the one requested.

   Group 2: Unsupported Attributes

      See [RFC2911] section 3.1.7 and section 3.2.5.2 for details on
      returning Unsupported Attributes.

      The response NEED NOT contain the "requested-attributes" operation
      attribute with any supplied keyword values that were requested by
      the client but are not supported by the IPP object.  If the
      Printer object does return unsupported attributes referenced in
      the "requested-attributes" operation attribute, the values of the
      "requested-attributes" attribute returned MUST include only the
      unsupported keywords that were requested by the client.  If the
      client had requested a group name, such as 'all', the resulting
      unsupported attributes returned MUST NOT include attribute keyword
      names described in the standard but not supported by the
      implementation.

   Group 3: Subscription Attributes

      This group contains a set of attributes with their current values.
      Each attribute returned in this group:

   a) MUST be specified by the "requested-attributes" attribute in the
      request, AND

   b) MUST be present on the specified Subscription Object AND

   c) MUST  NOT be restricted by the security policy in force.  For
      example, a Printer MAY prohibit a client who is not the creator of
      a Subscription Object from seeing some or all of its attributes.
      See [RFC2911] end of section 3.3.4.2 and section 8.

      The Printer can return the attributes of the Subscription Object
      in any order.  The client MUST accept the attributes in any order.
Top   ToC   RFC3995 - Page 63

11.2.5. Get-Subscriptions operation

This operation allows a client to retrieve the values of attributes of all Subscription Objects belonging to a Job or Printer. A Printer MUST supported this operation. This operation is similar to the Get-Subscription-Attributes operation, except that this Get-Subscriptions operation returns attributes from possibly more than one object. This operation is similar to the Get-Jobs operation (see [RFC2911] section 3.2.6), except that the operation returns Subscription Objects rather than Job objects. Access Rights: To query Per-Job Subscription Objects of the specified job (client supplied the "notify-job-id" operation attribute - see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the Subscription Object owner, (2) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to query the Subscription Object for the target job. To query Per-Printer Subscription Objects of the Printer (client omits the "notify-job-id" operation attribute - see section 11.2.5.1.1), the authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) have Operator or Administrator access rights for this Printer (see [RFC2911] sections 1 and 8.5), or (2) be otherwise authorized by the Printer's administrator-configured security policy to query Per-Printer Subscription Objects for the target Printer. Otherwise the Printer MUST reject the operation and return: the 'client-error-forbidden', 'client-error-not- authenticated', or 'client-error-not-authorized' status code as appropriate. Furthermore, the Printer's security policy MAY limit which attributes are returned, in a manner similar to the Get-Jobs and Get-Printer-Attributes operations (see [RFC2911] end of sections 3.2.6.2 and 3.2.5.2).
11.2.5.1. Get-Subscriptions Request
The following groups of attributes are part of the Get-Subscriptions request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.1.
Top   ToC   RFC3995 - Page 64
   Target:
      The "printer-uri" attribute which defines the target for this
      operation as described in [RFC2911] section 3.1.5.

   Requesting User Name:
      The "requesting-user-name" attribute SHOULD be supplied by the
      client as described in [RFC2911] section 8.3.

11.2.5.1.1. "notify-job-id" (integer(1:MAX))
If the client specifies this attribute, the Printer returns the specified attributes of all Per-Job Subscription Objects associated with the Job whose "job-id" attribute value equals the value of this attribute. If the client does not specify this attribute, the Printer returns the specified attributes of all Per-Printer Subscription Objects. Note: there is no way to get all Per-Job Subscriptions known to the Printer in a single operation. A Get-Jobs operation followed by a Get-Subscriptions operation for each Job will return all Per-Job Subscriptions.
11.2.5.1.2. "limit" (integer(1:MAX))
The client OPTIONALLY supplies this attribute. The Printer MUST support this attribute. It is an integer value that determines the maximum number of Subscription Objects that a client will receive from the Printer even if the "my-subscriptions" attribute constrains which Subscription Objects are returned. The limit is a "stateless limit" in that if the value supplied by the client is 'N', then only the first 'N' Subscription Objects are returned in the Get- Subscriptions Response. There is no mechanism to allow for the next 'M' Subscription Objects after the first 'N' Subscription Objects. If the client does not supply this attribute, the Printer responds with all applicable Subscription Objects.
11.2.5.1.3. "requested-attributes" (1setOf type2 keyword)
The client OPTIONALLY supplies this attribute. The Printer MUST support this attribute. This attribute specifies the attributes of the specified Subscription Objects that the Printer MUST return in the response. Each value of this attribute is either an attribute name (defined in sections 5.3 and 5.4) or an attribute group name (defined in section 11.2.4.1). If the client omits this attribute, the Printer MUST respond as if the client had supplied this attribute with the one value: 'notify-subscription-id'.
Top   ToC   RFC3995 - Page 65
11.2.5.1.4. "my-subscriptions" (boolean)
The client OPTIONALLY supplies this attribute. The Printer MUST support this attribute. If the value is 'false', the Printer MUST consider the Subscription Objects from all users as candidates. If the value is 'true', the Printer MUST return the Subscription Objects created by the requesting user of this request. If the client does not supply this attribute, the Printer MUST respond as if the client had supplied the attribute with a value of 'false'. The means for authenticating the requesting user and matching the Subscription Objects is similar to that for Jobs which is described in [RFC2911] section 8.
11.2.5.2 Get-Subscriptions Response
The Printer returns the following sets of attributes as part of the Get-Subscriptions Response: Group 1: Operation Attributes Status Message: Same as [RFC2911]. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.2. Group 2: Unsupported Attributes Same as for Get-Subscription-Attributes. Groups 3 to N: Subscription Attributes The Printer responds with one Subscription Attributes Group for each requested Subscription Object (see the "notify-job-id" attribute in the Operation Attributes Group of this operation). The Printer returns Subscription Objects in any order. If the "limit" attribute is present in the Operation Attributes group of the request, the number of Subscription Attributes Groups in the response MUST NOT exceed the value of the "limit" attribute. It there are no Subscription Objects associated with the specified Job or Printer, the Printer MUST return zero Subscription Attributes Groups and it MUST NOT treat this case as an error,
Top   ToC   RFC3995 - Page 66
      i.e., the status-code MUST be 'successful-ok' unless something
      else causes the status code to have some other value.

      See the Group 3 response (Subscription Attributes Group) of the
      Get-Subscription-Attributes operation (section 11.2.4.2) for the
      attributes that a Printer returns in this group.

11.2.6. Renew-Subscription operation

This operation allows a client to request the Printer to extend the lease on a Per-Printer Subscription Object. The Printer MUST support this operation. The Printer MUST accept this request for a Per-Printer Subscription Object in any of the target Printer's states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change the Printer's "printer-state" attribute. The Printer MUST reject this request for a Per-Job Subscription Object because it has no lease (see section 5.4.3). The status code returned MUST be 'client-error-not-possible'. Access Rights: The authenticated user (see [RFC2911] section 8.3) performing this operation MUST (1) be the owner of the Per-Printer Subscription Object, (2) have Operator or Administrator access rights for the Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise authorized by the Printer's administrator-configured security policy to renew Per-Printer Subscription Objects for the target Printer. Otherwise, the Printer MUST reject the operation and return: the 'client-error-forbidden', 'client-error-not- authenticated', or 'client-error-not-authorized' status code as appropriate.
11.2.6.1. Renew-Subscription Request
The following groups of attributes are part of the Renew-Subscription Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.1. Target: The "printer-uri" attribute which defines the target for this operation as described in [RFC2911] section 3.1.5.
Top   ToC   RFC3995 - Page 67
   Requesting User Name:
      The "requesting-user-name" (name(MAX)) attribute SHOULD be
      supplied by the client as described in [RFC2911] section 8.3.

11.2.6.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this attribute. This attribute specifies the Per-Printer Subscription Object whose lease the Printer MUST renew. If the client omits this attribute, the Printer MUST reject this request with the 'client- error-bad-request' status code. Group 2: Subscription Template Attributes
11.2.6.1.2. "notify-lease-duration" (integer(0:MAX))
The client MAY supply this attribute. It indicates the number of seconds to renew the lease for the specified Subscription Object. A value of 0 requests an infinite lease (which MAY require Operator access rights). If the client omits this attribute, the Printer MUST use the value of the Printer's "notify-lease-duration-default" attribute. See section 5.3.8 for more details.
11.2.6.2. Renew-Subscription Response
The Printer returns the following sets of attributes as part of the Renew-Subscription Response: Group 1: Operation Attributes Status Message: Same as [RFC2911]. The following are some of the status codes returned (see [RFC2911]: successful-ok: The operation successfully renewed the lease on the Subscription Object for the requested duration. successful-ok-ignored-or-substituted-attributes: The operation successfully renewed the lease on the Subscription Object for some duration other than the amount requested. client-error-not-possible: The operation failed because the "notify-subscription-id" Operation attribute identified a Per-Job Subscription Object.
Top   ToC   RFC3995 - Page 68
         client-error-not-found: The operation failed because the
            "notify-subscription-id" Operation attribute identified a
            non-existent Subscription Object.

   Natural Language and Character Set:
      The "attributes-charset" and "attributes-natural-language"
      attributes as described in [RFC2911] section 3.1.4.2.  The
      "attributes-natural-language" MAY be the natural language of the
      Subscription Object, rather than the one requested.

   Group 2: Unsupported Attributes

      See [RFC2911] section 3.1.7 for details on returning Unsupported
      Attributes.

   Group 3: Subscription Attributes

      The Printer MUST return the following Subscription Attribute:

11.2.6.2.1. "notify-lease-duration" (integer(0:MAX))
The value of this attribute MUST be the number of seconds that the Printer has granted for the lease of the Subscription Object (see section 5.3.8 for details, such as the value of this attribute when the Printer doesn't support the requested value).

11.2.7. Cancel-Subscription operation

This operation allows a client to delete a Subscription Object and stop the Printer from delivering more Event Notifications. Once performed, there is no way to reference the Subscription Object. A Printer MUST supported this operation. The Printer MUST accept this request in any of the target Printer's states, i.e., 'idle', 'processing', or 'stopped', but MUST NOT change the Printer's "printer-state" attribute. If the specified Subscription Object is a Per-Job Subscription Object, the Printer MUST accept this request in any of the target Job's states, but MUST NOT change the Job's "job-state" attribute or affect the Job. Note: There is no way to change any attributes on a Subscription Object, except the "notify-lease-duration" attribute (using the Renew-Subscription operation). In order to change other attributes, a client performs a Subscription Creation Operation and Cancel- Subscription operation on the old Subscription Object. If the client
Top   ToC   RFC3995 - Page 69
   wants to avoid missing Event Notifications, it performs the
   Subscription Creation Operation first.  If this order would create
   too many Subscription Objects on the Printer, the client reverses the
   order.

   Access Rights: The authenticated user (see [RFC2911] section 8.3)
   performing this operation MUST (1) be the owner of the Subscription
   Object, (2) have Operator or Administrator access rights for the
   Printer (see [RFC2911] sections 1 and 8.5), or (3) be otherwise
   authorized by the Printer's administrator-configured security policy
   to cancel the target Subscription Object.  Otherwise, the Printer
   MUST reject the operation and return: the 'client-error-forbidden',
   'client-error-not-authenticated', or 'client-error-not-authorized'
   status code as appropriate.

11.2.7.1. Cancel-Subscription Request
The following groups of attributes are part of the Cancel- Subscription Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.1. Target: The "printer-uri" attribute which defines the target for this operation as described in [RFC2911] section 3.1.5. Requesting User Name: The "requesting-user-name" attribute SHOULD be supplied by the client as described in [RFC2911] section 8.3.
11.2.7.1.1. "notify-subscription-id" (integer (1:MAX))
The client MUST supply this attribute. The Printer MUST support this attribute. This attribute specifies the Subscription Object that the Printer MUST cancel. If the client omits this attribute, the Printer MUST reject this request with the 'client-error-bad-request' status code.
Top   ToC   RFC3995 - Page 70
11.2.7.2. Cancel-Subscription Response
The Printer returns the following sets of attributes as part of the Cancel-Subscription Response: Group 1: Operation Attributes Status Message: Same as [RFC2911]. The following are some of the status codes returned (see [RFC2911]: successful-ok: The operation successfully canceled (deleted) the Subscription Object. client-error-not-found: The operation failed because the "notify-subscription-id" Operation attribute identified a non-existent Subscription Object. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in [RFC2911] section 3.1.4.2. The "attributes-natural-language" MAY be the natural language of the Subscription Object, rather than the one requested. Group 2: Unsupported Attributes See [RFC2911] section 3.1.7 for details on returning Unsupported Attributes.

12. Status Codes

The following status codes are defined as extensions for Notification and are returned as the value of the "status-code" parameter in the Operation Attributes Group of a response (see [RFC2911] section 3.1.6.1). Operations in this document can also return the status codes defined in section 13 of [RFC2911]. The 'successful-ok' status code is an example of such a status code.

12.1. successful-ok-ignored-subscriptions (0x0003)

The Subscription Creation Operation was unable to create all requested Subscription Objects. For a Create-Job-Subscriptions or Create-Printer-Subscriptions operation, this status code means that the Printer created one or
Top   ToC   RFC3995 - Page 71
   more Subscription Objects, but not all requested Subscription
   Objects.

   For a Job Creation operation, this status code means that the Printer
   created the Job along with zero or more Subscription Objects.  The
   Printer returns this status code even if other job attributes are
   unsupported or in conflict.  That is, if an IPP Printer finds a
   warning that would allow it to return 'successful-ok-ignored-
   subscriptions' and either 'successful-ok-ignored-or-substituted-
   attributes' and/or 'successful-ok-conflicting-attributes', it MUST
   return 'successful-ok-ignored-subscriptions'.

12.2. client-error-ignored-all-subscriptions (0x0414)

This status code is the same as 'successful-ok-ignored-subscriptions' except that only the Create-Job-Subscriptions and Create-Printer- Subscriptions operation return it. They return this status code only when the Printer creates zero Subscription Objects.

13. Status Codes in Subscription Attributes Groups

This section contains values of the "notify-status-code" (type2 enum) attribute that the Printer returns in a Subscription Attributes Group in a response when the corresponding Subscription Object: 1. is not created or 2. is created and some of the client-supplied attributes are not supported. The following sections are ordered in decreasing order of importance of the status-codes.

13.1. client-error-uri-scheme-not-supported (0x040C)

This status code is defined in [RFC2911]. This document extends its meaning and allows it to be in a Subscription Attributes Group of a response. The scheme of the client-supplied URI in a "notify-recipient-uri" Subscription Template Attribute in a Subscription Creation Operation is not supported. See section 5.3.1.

13.2. client-error-attributes-or-values-not-supported (0x040B)

This status code is defined in [RFC2911]. This document extends its meaning and allows it to be in a Subscription Attributes Group of a response.
Top   ToC   RFC3995 - Page 72
   The method of the client-supplied keyword in a "notify-pull-method"
   Subscription Template Attribute in a Subscription Creation Operation
   is not supported.  See section 5.3.2.

13.3. client-error-too-many-subscriptions (0x0415)

The number of Subscription Objects supported by the Printer would be exceeded if this Subscription Object were created (see section 5.2).

13.4. successful-ok-too-many-events (0x0005)

The client supplied more Events in the "notify-events" operation attribute of a Subscription Creation Operation than the Printer supports, as indicated in its "notify-max-events-supported" Printer attribute (see section 5.3.3).

13.5. successful-ok-ignored-or-substituted-attributes (0x0001)

This status code is defined in [RFC2911]. This document extends its meaning to include unsupported Subscription Template Attributes and it can appear in a Subscription Attributes Group.

14. Encodings of Additional Attribute Tags

This section assigns values to two attributes tags as extensions to the encoding defined in [RFC2910]). The "subscription-attributes-tag" delimits Subscription Template Attributes Groups in requests and Subscription Attributes Groups in responses. The "event-notification-attributes-tag" delimits Event Notifications in Delivery Methods that use an IPP-like encoding. The following table specifies the values for the delimiter tags: Tag Value (Hex) Meaning 0x06 "subscription-attributes-tag" 0x07 "event-notification-attributes-tag"

15. Conformance Requirements

It is OPTIONAL for IPP clients and Printers to implement this Event Notification specification.
Top   ToC   RFC3995 - Page 73

15.1. Conformance requirements for clients

If this Event Notification specification is implemented by a client, the client MUST support the 'ippget' Pull Delivery Method and meet the conformance requirements as defined in [RFC3996] for clients. A client MAY support additional Delivery Methods.

15.2. Conformance requirements for Printers

If this Event Notification specification is implemented by a Printer, the Printer MUST: - meet the Conformance Requirements detailed in section 5 of [RFC2911]. - support the Subscription Template Attributes Group in requests and the Subscription Attributes Group in responses. - support all of the following attributes: a. REQUIRED Subscription Object attributes in section 5. b. REQUIRED Printer Description object attributes in section 6. c. REQUIRED attributes in Event Notification content in section 8. - support the 'ippget' Pull Delivery Method and meet the conformance requirements as defined in [RFC3996] for Printers. The Printer MAY support additional Push and Pull Delivery Methods. - deliver Event Notifications that conform to the requirements of section 9 and the requirements of the Delivery Method Document for each supported Delivery Method (the conformance requirements for Delivery Method Documents is specified in section 10). - for all of the Job Creation Operations that the Printer supports, MUST support the REQUIRED extensions for notification defined in section 11.1.3. - meet the conformance requirements for operations as described in Table 16 and meet the requirements for Printers as specified in the indicated sub-sections of section 11:
Top   ToC   RFC3995 - Page 74
   Table 16 - Printer Conformance Requirements for Operations

   Operation                                         Printer
                                                     Conformance
                                                     Requirements

   Create-Printer-Subscriptions (section 11.1.2)     REQUIRED
   Create-Job-Subscriptions (section 11.1.1)         OPTIONAL
   Get-Subscription-Attributes (section 11.2.3)      REQUIRED
   Get-Subscriptions (section 11.2.5)                REQUIRED
   Renew-Subscription (section 11.2.6)               REQUIRED
   Cancel-Subscription (section 11.2.7)              REQUIRED

16. Model for Notification with Cascading Printers (Informative)

With this model (see Figure 2 below), there is an intervening Print server between the human user and the output-device. So the system effectively has two Printer objects. There are two cases to consider. 1. When the Printer 1 (in the server) generates Events, the system behaves like the client and Printer in Figure 1. In this case, Printer 1 delivers Event Notifications that are shown as Event Notifications (A) of Figure 2. 2. When the Printer 2 (in the output-device) generates Events, there are two possible system configurations: a) Printer 1 forwards the client-supplied Subscription Creation Operations to the downstream Printer 2 and lets Printer 2 deliver the Event Notifications directly to the Notification Recipients supplied by the Client (Event Notifications(C) in the diagram). b) Printer 1 performs the client-supplied Subscription Creation Operations and also forwards the Subscription Creation Operations to Printer 2 with the Notification Recipient changed to be the Printer 1. When an Event occurs in Printer 2, Printer 2 delivers the Event Notification (B) to Notification Recipient of Printer 1, which relays the received Event Notification (B) to the client-supplied Notification Recipient (as Event Notifications(A) in the diagram). Note, when a client performs a Subscription Creation Operation, Printer 1 need not forward the Subscription Creation Operation to Printer 2 if it would create a duplicate Subscription Object on Printer 2.
Top   ToC   RFC3995 - Page 75
   Note: when Printer 1 is forwarding Subscription Creation Operations
   to Printer 2, it may request Printer 2 to create additional
   Subscription Objects (called "piggy-backing").  Piggy-backing is
   useful when:

   -  Device A is configured to accept (IPP or non-IPP) requests from
      other servers.

   -  Server S wants to receive Job Events that the client didn't
      request and Server S wants these Events for jobs it submits and
      not for other jobs.

                              server S                       device A
                           +------------+                 +------------+
                           |            |                 |            |
   +--------+ Subscription | ###########|                 | ###########|
   | client |--Creation ----># Printer #|  Subscription   | # Printer #|
   +--------+  Operation   | # Object 1#|---Creation------|># Object 2#|
                           | ###|#######|   Operation     | ####|#|####|
                           +----|---^---+                 +-----|-|----+
   +--------+     Event         |   |                           | |
   |Notific-|<-Notifications(A)-+   +-- Event Notifications(B)--+ |
   |ation Re|<-------------Event Notifications(C)-----------------+
   |cipient |
   +--------+

         Figure 2 - Model for Notification with Cascading Printers



(page 75 continued on part 4)

Next Section