Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3380

Internet Printing Protocol (IPP): Job and Printer Set Operations

Pages: 59
Proposed Standard
Errata
Updates:  29102911
Part 1 of 3 – Pages 1 to 21
None   None   Next

Top   ToC   RFC3380 - Page 1
Network Working Group                                        T. Hastings
Request for Comments: 3380                             Xerox Corporation
Updates: 2910, 2911                                           R. Herriot
Category: Standards Track                                     Consultant
                                                               C. Kugler
                                                                H. Lewis
                                                         IBM Corporation
                                                          September 2002


                   Internet Printing Protocol (IPP):
                     Job and Printer Set Operations

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 (2002).  All Rights Reserved.

Abstract

This document is an OPTIONAL extension to the Internet Printing Protocol (IPP/1.0 and IPP/1.1). This document specifies 3 additional OPTIONAL operations for use with the Internet Printing Protocol/1.0 (IPP) and IPP/1.1. The end user, operator, and administrator Set- Job-Attributes and Set-Printer-Attributes operations are used to modify IPP Job objects and Printer objects, respectively. The Get- Printer-Supported-Values administrative operation returns values that the IPP Printer will accept for setting its "xxx-supported" attributes.
Top   ToC   RFC3380 - Page 2

Table of Contents

1 Introduction......................................................4 2 Terminology.......................................................5 2.1 Conformance Terminology.........................................5 2.2 Other terminology...............................................5 3 Requirements and Use Cases........................................5 4 Definition of the Set operations..................................6 4.1 Set-Printer-Attributes Operation................................7 4.1.1 Settable and READ-ONLY Printer Description attributes.........9 4.1.2 Set-Printer-Attributes Request...............................10 4.1.3 Set-Printer-Attributes Response..............................12 4.2 Set-Job-Attributes Operation...................................13 4.2.1 Settable and READ-ONLY Job Description attributes............16 4.2.2 Set-Job-Attributes Request...................................17 4.2.3 Set-Job-Attributes Response..................................18 4.3 Get-Printer-Supported-Values Operation.........................19 4.3.1 Definition of the usage of the 'admin-define' out-of-band attribute value..............................................20 5 New Operation attributes.........................................22 5.1 printer-message-from-operator (text(127))......................22 5.2 job-message-from-operator (text(127))..........................23 6 New Printer Description Attributes...............................24 6.1 printer-settable-attributes-supported (1setOf type2 keyword)...24 6.2 job-settable-attributes-supported (1setOf type2 keyword).......25 6.3 document-format-varying-attributes (1setOf type2 keyword)......25 6.4 printer-message-time (integer(MIN:MAX))........................25 6.5 printer-message-date-time (dateTime)...........................26 6.6 printer-xri-supported (1setOf collection)......................26 6.7 xri-uri-scheme-supported (1setOf uriScheme)....................28 6.8 xri-authentication-supported (1setOf type2 keyword)............29 6.9 xri-security-supported (1setOf type2 keyword)..................29 7 Additional status codes..........................................29 7.1 client-error-attributes-not-settable (0x0413)..................29 8 Additional out-of-band values....................................30 8.1 'not-settable' out-of-band value...............................30 8.1.1 Encoding of the 'not-settable' out-of-band attribute value...30 8.2 'delete-attribute' out-of-band value...........................30 8.2.1 Encoding of the 'delete-attribute' out-of-band value.........31 8.3 'admin-define' out-of-band attribute value.....................31 8.3.1 Encoding of the 'admin-define' out-of-band attribute value...32 9 New Values for Existing Printer Description Attributes...........33 9.1 operations-supported (1setOf type2 enum).......................33 10 Conformance Requirements........................................33 11 IANA Considerations.............................................34 11.1 Operation Registrations.......................................35 11.2 Additional Enum Attribute Value Registrations for the "operations-supported" Printer Attribute......................35
Top   ToC   RFC3380 - Page 3
   11.3 Keyword attribute value registrations.........................36
   11.4 Attribute Registrations.......................................37
   11.5 Status code Registrations.....................................37
   11.6 Out-of-band Attribute Value Registrations.....................37
   12 Internationalization Considerations.............................37
   13 Security Considerations.........................................37
   14 References......................................................38
   14.1 Normative References..........................................38
   14.2 Informative References........................................38
   Appendix A: Allowed Values for Set-Printer-Attributes and Set-Job-
               Attributes requests (Normative)........................39
   Appendix B: Attributes returned from Get-Printer-Supported-Values
               (Normative)............................................50
   Appendix C: Description of the Base IPP Documents (Informative)....55
   Authors' Addresses.................................................56
   Full Copyright Statement...........................................58

Table of Tables

   Table 1 -  Operation-Id assignments.................................7
   Table 2 -  Job State Transition Table for the Set-Job-Attributes
              operation ..............................................15
   Table 3 -  Member attributes of "printer-xri-supported" (1setOf
              collection) ............................................27
   Table 4 -  Operation-id assignments................................33
   Table 5 -  Validation rules for 'Any of "xxx-supported" '..........40
   Table 6 -  Validation rules for 'From Get-Printer-Supported-Values'41
   Table 7 -  Values allowed for Job Template Attributes in the Set-Job-
              Attributes Operation ...................................42
   Table 8 -  Values allowed for Job Description Attributes in the Set-
              Job-Attributes Operation ...............................43
   Table 9 -  Values allowed for Printer Job Template Attributes in the
              Set-Printer-Attributes Operation .......................44
   Table 10 - Values allowed for Printer Description Attributes in the
              Set-Printer-Attributes Operation .......................47
   Table 11 - Printer Job Template Attributes returned from Get-Printer-
              Supported-Values .......................................51
   Table 12 - Printer Job Template Attributes returned from Get-Printer-
              Supported-Values .......................................51
   Table 13 - Printer Description Attributes returned from Get-Printer-
              Supported-Values .......................................51
   Table 14 - Printer Job Template Attributes returned from Get-Printer-
              Supported-Values .......................................52
   Table 15 - Printer Job Template Attributes returned from Get-Printer-
              Supported-Values .......................................52
   Table 16 - Printer Description Attributes returned from Get-Printer-
              Supported-Values .......................................53
Top   ToC   RFC3380 - Page 4

1 Introduction

This document is an OPTIONAL extension to IPP/1.0 [RFC2565, RFC2566] and IPP/1.1 [RFC2911, RFC2910]. For a description of the base IPP documents see Appendix C. The Internet Printing Protocol (IPP) is an application level protocol that can be used for distributed printing using Internet tools and technologies. IPP version 1.1 [RFC2911, RFC2910] focuses on end user functionality with a few administrative operations included. This document defines additional OPTIONAL end user, operator, and administrator Set-Job-Attributes and Set-Printer-Attributes operations used to modify IPP Job objects and Printer objects, respectively. It also defines a third Get-Printer-Supported-Values administrator operation that returns values that the IPP Printer will accept for setting its "xxx-supported" attributes. The Get-Printer- Supported-Values operation MUST be supported, if the implementation supports setting any "xxx-supported" Printer attributes using the Set-Printer-Attributes operation. Nine Printer Description attributes are defined: printer-settable-attributes-supported (1setOf type2 keyword) job-settable-attributes-supported (1setOf type2 keyword) document-format-varying-attributes (1setOf type2 keyword) printer-message-time (integer(MIN:MAX)) printer-message-date-time (dateTime) printer-xri-supported (1setOf collection) xri-uri-scheme-supported (1setOf uriScheme) xri-authentication-supported (1setOf type2 keyword) xri-security-supported (1setOf type2 keyword) Three out-of-band values are defined for use with these three operations: 'delete-attribute' for deleting Job attributes with the Set-Job-Attributes request, 'not-settable' for use in either the Set-Job-Attributes or Set-Printer-Attributes responses, and 'admin- define' for use in the Get-Printer-Supported-Values response. Two operation attributes: "printer-message-from-operator" (text) and "job-message-from-operator" (text) are defined to set the corresponding IPP/1.1 Printer and Job Description attributes with the same names. These operation attributes may be used with any operation that affect the Printer or Job object for which an operation might want to indicate a message. For the Set-Job- Attributes and Set-Printer-Attributes operations, the client MUST explicitly set them, rather than using these operation attributes.
Top   ToC   RFC3380 - Page 5
   A Printer implementation can make the value of some attributes
   dependent on the document-format, e.g., "resolution-supported".

2 Terminology

This section defines terminology used throughout this document.

2.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 BCP 14, 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.

2.2 Other terminology

This document uses terms such as Job object (or Job), IPP Printer object (or Printer), "operation", "request", response", "attributes", "keywords", and "support". These terms have special meaning and are defined in the model terminology [RFC2911], section 12.2. The following additional terms are introduced in this document: READ-ONLY: used in an attribute definition document to indicate that the attribute MUST NOT be settable using an IPP protocol Set operation. In other words, the attribute is not settable by definition. not-settable: an implementation does not support setting an attribute (whether or not the attribute's definition is READ-ONLY).

3 Requirements and Use Cases

The following requirements and usage are intended to be met by the specification in this document. 1. The end-user and the operator need a way to modify a Job that is in the 'pending' or 'pending-held' state. Usage: The end-user discovers that he/she forgot to include a print instruction, such as "finishings" = 'staple' after submitting a job. Rather than canceling the job and resubmitting it to the same IPP Printer, the end-user is able to modify the job on the IPP Printer.
Top   ToC   RFC3380 - Page 6
      The operator needs to modify a job because it is requesting a
      particular kind of media for which there is no more, but the
      policy is to print the job on a comparable medium.

   2. The system administrator needs a way to re-configure or change the
      policy of the IPP Printer remotely.

      Usage: The system administrator is adding additional named media
      to the supported media list (setting 'name' values to the "media-
      supported" Printer attribute).

      The system administrator is reducing the capability of the IPP
      Printer by removing one of the operations from the supported
      operations list, such as Cancel-Job, because the policy is to run
      the IPP Printer like a public facsimile machine.  After having
      removed Cancel-Job from the list of supported operations, an
      administrative client needs to be able to display to an
      administrator that the implementation is capable of being
      reconfigured to support Cancel-Job once again.

      The system administrator is remotely configuring the IPP Printer
      after installing it, and so is replacing the Printer Description
      attributes that have the out-of-band 'no-value' value (see
      [RFC2911], section 4.1) with the proper values.

      The operator is changing the media loaded in the input tray, and
      so is replacing the "media-ready" Job Template Printer attribute
      value with the proper values.

4 Definition of the Set operations

The Set-Printer-Attributes operations (as are all Printer operations) are directed at Printer objects. A client MUST always supply the "printer-uri" operation attribute in order to identify the correct target of the operation. These descriptions assume all of the common semantics of the IPP/1.1 Model and Semantics document [RFC2911], section 3.1. The Set-Job-Attributes operations (as are all Job operations) are directed at Job objects. A client MUST always supply some means of identifying the Job object in order to identify the correct target of the operation. That job identification MAY either be a single Job URI or a combination of a Printer URI with a Job ID, as defined in [RFC2911]. The IPP object implementation MUST support both forms of identification for every job. If possible, a client SHOULD use the Printer URI with a Job ID rather than a Job URI, since the 32-bit
Top   ToC   RFC3380 - Page 7
   "job-id" is more readily translated to and from other print protocols
   that MAY be serving as gateways into or out of the IPP
   implementation.

   The Set Printer operations are summarized in Table 1:

                     Table 1 - Operation-Id assignments

      Operation Name      Operation  Brief description
                          -Id

      Set-Printer-        0x0013     Sets attribute values of the target
      Attributes                     Printer object

      Set-Job-Attributes  0x0014     Sets attribute values of the target
                                     Job object

      Get-Printer-        0x0015     Gets values that are valid for
      Supported-Values               setting "xxx-supported" attributes
                                     using the Set-Printer-Attributes
                                     operation

4.1 Set-Printer-Attributes Operation

This OPTIONAL operation allows a client to set the values of the attributes of a Printer object. In the request, the client supplies the set of Printer keyword attribute names and values that are to be set. In the response, the Printer object returns success or rejects the entire request with indications of which attribute or attributes could not be set. The Printer object validates the client-supplied attributes in the Set-Printer-Attributes request. For an attribute to validate, it MUST meet all of the following rules: 1. The number of attributes supplied by the client MUST NOT exceed the maximum number that the Printer supports in a Set-Printer- Attributes request. A Printer MUST accept at least one attribute, but SHOULD accept a reasonable number in a single Set-Printer- Attributes request. Note: There is no way for the client to determine the maximum number of attributes that the Printer supports in a Set-Printer- Attributes request, except to try a reasonable number. 2. The Printer MUST support the attribute.
Top   ToC   RFC3380 - Page 8
   3. The attribute MUST NOT be READ-ONLY, i.e., the definition of the
      attribute MUST NOT indicate that the attribute is READ-ONLY (see
      Appendix A for an indication of which IPP/1.1 attributes are
      READ-ONLY).

   4. The attribute MUST be settable in this implementation.

   5. The Printer MUST support the value, according to the rules defined
      in Appendix A, i.e., each value of each supplied "xxx" attribute
      MUST be validated against the value of a corresponding "xxx-
      supported" Printer attribute.  One of those rules permits an
      administrator to set arbitrary 'name' values to those "xxx-
      supported" Printer attributes that include the 'name' attribute
      syntax if the implementation supports the 'admin-define' out-of-
      band value for that "xxx-supported" attribute (see section 8.3 and
      Appendix A).

   6. The attribute's values MUST NOT conflict with the values of other
      Printer attributes, including ones being set in this same
      operation.

   If any of the supplied attributes are not validate, the Printer
   object MUST reject the entire operation; the Printer object MUST NOT
   partially set some of the supplied attributes.  In other words, after
   the operation, all the supplied attributes MUST be set or none of
   them MUST be set, thus making the Set-Printer-Attributes an atomic
   operation.

   The Printer MUST accept this operation when its READ-ONLY "printer-
   state" attribute (see [RFC2911], section 4.4.11) is 'idle' or
   'stopped', and SHOULD accept it when the value is 'processing'.  The
   Printer MUST accept this operation for any of the values of the
   Printer object's READ-ONLY "printer-state-reasons" and "printer-is-
   accepting-jobs" attributes, unless explicitly defined otherwise in
   the definition of these attributes' values.

   This operation MUST NOT change the value of attributes not specified
   in the operation unless the definition of the attribute explicitly
   specifies such side-effects.  For example, this document explicitly
   specifies that when this operation sets "printer-message-from-
   operator", the Printer also MUST set the READ-ONLY "printer-message-
   time" and READ-ONLY "printer-message-date-time" attributes to the
   time of the operation as a side effect.  In particular, if this
   operation changes an "xxx-default" attribute, the new value MUST be
   in the "xxx-supported" attributes or the request MUST contain a new
   value for "xxx-supported", which contains the new value for the
   "xxx-default".  Otherwise, the Printer MUST reject the operation.  In
   general, Printer attribute definitions that are settable will not
Top   ToC   RFC3380 - Page 9
   define side-effects on other attributes that are settable, only side
   effects on READ-ONLY attributes, if any.

4.1.1 Settable and READ-ONLY Printer Description attributes

If the Printer supports the Set-Printer-Attributes operation, then it SHOULD support the setting of: all Job Template Default ("xxx-default") attributes all Job Template Supported ("xxx-supported") attributes all Job Template Ready ("xxx-ready") attributes that the implementation supports (see [RFC2911] section 4.2 and extensions). Some Printer Description attributes (see [RFC2911] section 4.4) MUST NOT be settable, i.e., they are defined to be READ-ONLY. An attribute marked as "READ-ONLY" in the Printer Description attribute table in Appendix A is such an attribute. The Printer attributes that are not marked as "READ-ONLY" MAY be settable using the Set- Printer-Attributes operation, depending on implementation. Note: From now on, all extensions that define new object attributes will indicate whether or not the attributes are READ-ONLY, by including the "READ-ONLY" adjective in their descriptions and/or explicitly stating whether they MAY be settable. The current values of each "xxx-supported" Printer attribute MUST reflect the current policy for support of the corresponding "xxx" attribute. If an "xxx-supported" Printer attribute is settable in an implementation, then its value(s) MUST affect the behavior of the implementation. If an "xxx-supported" Printer attribute is defined to be READ-ONLY or is not-settable in an implementation, then its values MUST NOT be settable using the Set-Printer-Attributes operation. Consider the following examples: For example, if the "operations-supported" Printer Description attribute (see [RFC2911] section 4.4.15) is settable in a particular implementation, then changing its value with a Set- Printer-Attributes operation MUST affect the operations that the implementation accepts or rejects. Such an implementation will need to be able to reject values for operations that it contains no code support for (see section 4.3). If the "operations- supported" Printer Description attribute is not settable in a particular implementation, then that implementation MUST reject an attempt to set it with a Set-Printer-Attributes operation, return the 'client-error-attributes-not-settable' status code (see section 7.1), and return the "operations-supported" attribute,
Top   ToC   RFC3380 - Page 10
      with the out-of-band 'not-settable' value in the Unsupported
      Attributes Group.

      As another example, consider an implementation in which the
      "media-default" and "media-supported" are settable.  If a client
      supplies a Set-Printer-Attributes request that contains the
      "media-default" attribute with a value that is not a member of the
      Printer's "media-supported" attribute, the Printer MUST reject the
      request and return the "client-error-conflicting-attributes"
      status code with the "media-default" and "media-supported"
      attributes and their values (see [RFC2911] section 3.1.7).

      As a third example, if a client supplies a Set-Printer-Attributes
      request that contains both the "media-default" and the "media-
      supported" attributes, but includes a value in the "media-default"
      that is not a member of the supplied "media-supported" attribute,
      the Printer MUST reject the request and return the "client-error-
      conflicting-attributes" status code with the "media-default" and
      "media-supported" attributes and their values (see [RFC2911]
      section 3.1.7).

   Access Rights: The authenticated user (see [RFC2911] section 8.3)
   performing this operation must be an operator or administrator of the
   Printer object (see [RFC2911] Sections 1 and 8.5).  Most Printer
   attributes will require administrator access rights to set, such as
   "xxx-supported", while some will require operator access rights only,
   such as "media-ready" and "printer-message-from-operator".  Which
   attributes require which access rights depends on implementation, and
   MAY depend on site policy.

4.1.2 Set-Printer-Attributes Request

The following sets of attributes are part of the Set-Printer- Attributes 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" (uri) operation attribute, which is the target for this operation, as described in [RFC2911], section 3.1.5.
Top   ToC   RFC3380 - Page 11
      Requesting User Name:
         The "requesting-user-name" (name(MAX)) attribute SHOULD be
         supplied by the client, as described in [RFC2911], section 8.3.

      "document-format" (mimeMediaType):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.  This attribute is useful
         for a client to select the document-format to which the
         attribute modification should be applied.  A Printer
         implementation MAY allow some attributes to have different
         values for each document format that it supports.  See
         [RFC2911], section 3.2.5.1 "Get-Printer-Attributes Request".

         If the client includes this attribute, the Printer MUST change
         the supplied attributes for the document format specified by
         this attribute.  If a supplied attribute is a member of the
         "document-format-varying-attributes" (i.e., the attribute
         varies by document format, see section 6.3), the Printer MUST
         change the supplied attribute for the document format specified
         by this attribute, but not for other document formats.  If a
         supplied attribute isn't a member of the "document-format-
         varying-attributes" (i.e., it doesn't vary by document format),
         the Printer MUST change the supplied attribute for all document
         formats.

         If the client omits this attribute, the Printer MUST change the
         supplied attributes for all document formats, whether or not
         they vary by document-format.

         If the client supplies a value for the "document-format"
         Operation attribute, that is either 'application/octet-stream'
         or not supported by the Printer, i.e., is not among the values
         of the Printer object's "document-format-supported" attribute,
         the Printer object MUST reject the operation and return the
         'client-error-document-format-not-supported' status code.
         Note: the document-format 'application/octet-stream' is the
         union of several document-formats (see [RFC2911] section
         3.2.5.1, Get-Printer-Attributes) and is not a true document-
         format.

   Group 2: Printer Attributes

      The client MUST supply a set of Printer attributes with one or
      more values (including explicitly allowed out-of-band values) as
      defined in [RFC2911] section 4.2 Job Template Attributes ("xxx-
      default", "xxx-supported", and "xxx-ready" attributes), section
      4.4 Printer Description Attributes, and any attribute extensions
      supported by the Printer.  The value(s) of each Printer attribute
Top   ToC   RFC3380 - Page 12
      supplied in Group 2 replaces the value(s) of the corresponding
      Printer attribute on the target Printer object.  For attributes
      that can have multiple values (1setOf), all values supplied by the
      client replace all values of the corresponding Printer object
      attribute.  If a Printer object attribute had not yet been
      configured, and so assumed the 'no-value' out-of-band value (see
      [RFC2911] section 4.1), the supplied value(s) replaces the 'no-
      value' value.

4.1.3 Set-Printer-Attributes Response

The Printer object returns the following sets of attributes as part of the Get-Printer-Attributes 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 3.1.6 and 13. 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. If some of the attributes in the operation fail to validate, the Printer MUST reject the operation, MUST NOT change any Printer attributes, and MUST return the indicated status code below. In this group, the Printer MUST also return all attributes that fail to validate. The following are the reasons that an attribute fails to validate and the value returns for the attribute, along with the indicated status code and order of detection: 1. The number of attributes supplied by the client exceeds the maximum number that the Printer supports in a Set-Printer- Attributes request: return the 'client-error-request-entity- too-large' (see [RFC2911], section 13.1.4.9).
Top   ToC   RFC3380 - Page 13
      2. The Printer doesn't support the attribute: return the attribute
         with the "out-of-band" value 'unsupported' (see [RFC2911]
         section 3.1.7 and [RFC2910]) and the 'client-error-attributes-
         or-values-not-supported (see [RFC2911], section 13.1.4.12).

      3. The attribute is either READ-ONLY (in its definition) or is
         not-settable in this implementation: return the attribute with
         the "out-of-band" value 'not-settable' (see section 8.1) and
         the 'client-error-attributes-not-settable' status code (see
         section 7.1).

      4. The Printer doesn't support the value: if the attribute in the
         operation has a single value, return it.  If the attribute in
         the operation is multi-valued, return only those values in a
         1setOf that are not supported.  Return the 'client-error-
         attributes-or-values-not-supported' status code (see [RFC2911],
         section 13.1.4.12).

      5. The values of some of the supplied attributes conflict with one
         another and/or other Printer attribute values not being set: if
         the conflicting attribute in the operation has a single value,
         return the attribute and the value.  If the attribute in the
         operation is multi-valued, return only the attribute and those
         values in a 1setOf that are conflicting with other attributes.
         Return the 'client-error-conflicting-attributes' status code
         (see [RFC2911], section 13.1.4.15).

4.2 Set-Job-Attributes Operation

This OPTIONAL operation allows a client to set the values of the attributes of a Job object. In the request, the client supplies the set of Job keyword attribute names and values that are to be set. In the response, the IPP object returns success or rejects the entire request with indications of which attribute or attributes could not be set. This operation is almost identical to the Set-Printer-Attributes operation and follows the same rules for validation (see section 4.1). The only differences are that the Set-Job-Attributes operation is directed at a Job object rather than a Printer object, there is no "document-format" operation attribute used when setting a Job object, the operation can add an attribute to the (Job) object, the 'delete- attributes' out-of-band value is permitted to remove an attribute, and the validation is the same as the Job Creation operations (Print-Job, Print-URI, and Create-Job), i.e., depends on the "xxx- supported" Printer Description attributes (see [RFC2911] section 3.1). Using the Set-Printer-Attributes operation, the administrator can set arbitrary 'name' values to those "xxx-supported" Printer
Top   ToC   RFC3380 - Page 14
   attributes, that include the 'name' attribute syntax, if the
   implementation supports the 'admin-define' out-of-band value for that
   "xxx-supported" attribute (see section 8.3 and Appendix A).  However,
   the Set-Job-Attributes cannot be used to add unsupported names to the
   Job object.

   If a client supplies a job attribute in a Set-Job-Attributes request
   that the Printer supports, and the job was originally submitted
   without supplying that attribute, the Printer adds the attribute to
   the Job object.

   If the client supplies a job attribute with the "out-of-band" value
   'delete-attribute' (see section 8.2), then the Printer MUST remove
   the attribute and all of its values from the Job object, if present.
   The semantic effect of the client supplying the 'delete-attribute'
   value in a Set-Job-Attributes operation MUST be the same as if the
   attribute had not been supplied with the Job object in the Job
   Creation operation, i.e., the Printer applies its default attribute
   or behavior with lower precedence that the PDL (see the beginning of
   [RFC2911] section 4.2 and [RFC2911] 3.2.1.1).  Any subsequent query
   of the Job object using Get-Job-Attributes or Get-Jobs, MUST NOT
   return any attribute that has been deleted using the 'delete-
   attribute' out-of-band value.  However, a client can re-establish
   such a deleted Job attribute with any supported value(s), using a
   subsequent Set-Job-Attributes operation.

   If the client supplies an attribute in a Set-Job-Attributes request
   with the 'delete-attribute' value and that attribute is not present
   on the Job object, the Printer ignores that supplied attribute in the
   request, does not return the attribute in the Unsupported Attributes
   group, and returns the 'successful-ok' status code, if there are no
   other problems with the request.

   The validation of the Set-Job-Attributes request is performed by the
   Printer as if the job had been submitted originally with the new
   attribute values (and the deleted attributes removed) and with "ipp-
   attribute-fidelity" set to 'true', i.e., all modified attributes Job
   attributes and values MUST be supported in combination with the Job
   attributes not modified.  If such a Job Creation operation would have
   been accepted, then the Set-Job-Attributes MUST be accepted.  If such
   a Job Creation operation would have been rejected, then the Set-Job-
   Attributes MUST be rejected and the Job MUST be unchanged.  In
   addition, if any of the supplied attributes are not supported, are
   not settable, or the values are not supported, the Printer object
   MUST reject the entire operation; the Printer object MUST NOT
   partially set some of the supplied attributes.  In other words, after
Top   ToC   RFC3380 - Page 15
   the operation, all the supplied attributes MUST be set or none of
   them MUST be set, thus making the Set-Job-Attributes an atomic
   operation.

   The IPP object MUST accept or reject this operation when the Job's
   READ-ONLY "job-state" attribute has the values shown in Table 2.  The
   job's current state MUST affect whether the IPP object accepts or
   rejects the request.  For example, in the case where the operation
   creates a request for unavailable resources, the Job transitions to a
   new state.  Table 2 shows the allowed behaviors in each job state and
   the transitions.

       Table 2 - Job State Transition Table for the Set-Job-Attributes
                                  operation

    Current          New             IPP object's response status code
     "job-state"      "job-state"     and "action":


    'pending'        'pending'       'successful-ok'

    'pending'        'pending-held'  'successful-ok' - needed resources
                                     are not ready

    'pending-held'   'pending-held'  'successful-ok'

    'pending-held'   'pending'       'successful-ok' - needed resources
                                     are ready

    'processing'     'processing'    'successful-ok'  or 'client-error-
                                     not-possible' depending on
                                     implementation, including the
                                     attributes being set, whether the
                                     job has started marking media,
                                     etc.

    'processing-     'processing-    'successful-ok'  or 'client-error-
    stopped'         stopped'        not-possible' depending on
                                     implementation, including the
                                     attributes being set, whether the
                                     job has started marking media,
                                     etc.

    'completed'      'completed'     'client-error-not-possible'

    'canceled'       'canceled'      'client-error-not-possible'

    'aborted'        'aborted'       'client-error-not-possible'
Top   ToC   RFC3380 - Page 16
   This operation MUST NOT change the value of attributes not specified
   in the operation unless the definition of the attribute explicitly
   specifies such side-effects.  In general, Job attribute definitions
   that are settable will not define side-effects on other attributes
   that are settable, only side effects on READ-ONLY attributes, if any.

4.2.1 Settable and READ-ONLY Job Description attributes

If the Printer supports the "job-message-from-operator" Job Description attribute (see [RFC2911] section 4.3.16) and the client explicitly supplies a new value for the "job-message-from-operator" Job Description attribute in Group 2 in the Set-Job-Attributes request, then the Printer MUST set the "job-message-from-operator" Job Description attribute to this new value. If the Printer supports the Set-Job-Attributes operation, then it SHOULD support the setting of: all Job Template job ("xxx") attributes that the implementation supports (see [RFC2911] section 4.2 and extensions). Some Job Description attributes (see [RFC2911] section 4.3) MUST NOT be settable, i.e., they are defined to be READ-ONLY. An attribute marked as "READ-ONLY" in the Job Description attribute table in Appendix A is such an attribute. The Job attributes not marked as "READ-ONLY" MAY be settable using the Set-Job-Attributes operation, depending on implementation. Note: From now on, all extensions that define new object attributes will indicate whether or not the attributes are READ-ONLY, by including the "READ-ONLY" adjective in their descriptions and/or explicitly stating whether they MAY be settable. Access Rights: The authenticated user (see [RFC2911] section 8.3) performing this operation must either be the job owner (as determined in the Job Creation operation) or an operator or administrator of the Printer object (see [RFC2911] Sections 1 and 8.5).
Top   ToC   RFC3380 - Page 17

4.2.2 Set-Job-Attributes Request

The following sets of attributes are part of the Set-Job-Attributes 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: Either (1) the "printer-uri" (uri) plus "job-id" (integer(1:MAX)) or (2) the "job-uri" (uri) operation attribute(s), which defines the target for this operation as described in [RFC2911], section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client, as described in [RFC2911], section 8.3. Group 2: Job Attributes The client MUST supply a set of Job attributes with one or more values (including explicitly allowed out-of-band values) as defined in [RFC2911], section 4.2, Job Template Attributes ("xxx" attributes), section 4.3, Job Description Attributes, and any attribute extensions supported by the Printer. The value(s) of each Job attribute supplied in Group 2 replaces the value(s) of the corresponding Job attribute on the target Job object. For attributes that can have multiple values (1setOf), all values supplied by the client replace all values of the corresponding Job object attribute. If the client supplies an "xxx" attribute with the 'delete- attribute' out-of-band value (see section 8.2), the Printer MUST remove the "xxx" attribute from the Job object, if present.
Top   ToC   RFC3380 - Page 18

4.2.3 Set-Job-Attributes Response

The IPP object returns the following sets of attributes as part of the Set-Job-Attributes 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 3.1.6 and 13. 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. If some of the attributes in the operation fail to validate, the Printer MUST reject the operation, MUST NOT change any Job attributes, and MUST return the indicated status code below. In this group, the Printer MUST also return all attributes that fail to validate. The following are the reasons that an attribute fails to validate and the value returns for the attribute, along with the indicated status code and order of detection: 1. The number of attributes supplied by the client exceeds the maximum number that the Printer supports in a Set-Printer- Attributes request: return the 'client-error-request-entity- too-large' (see [RFC2911], section 13.1.4.9). 2. The Printer doesn't support the attribute: return the attribute with the 'unsupported' out-of-band attribute value (see [RFC2911], section 3.1.7 and [RFC2910]) and the 'client-error- attributes-or-values-not-supported (see [RFC2911], section 13.1.4.12). 3. The attribute is READ-ONLY (in its definition) or is not- settable in this implementation: return the attribute with the 'not-settable' out-of-band attribute value (see section 8.1) and the 'client-error-attributes-not-settable' status code (see section 7.1).
Top   ToC   RFC3380 - Page 19
      4. The Printer doesn't support the value: if the attribute in the
         operation has a single value return it.  If the attribute in
         the operation is multi-valued, return only those values in a
         1setOf that are not supported.  Return the 'client-error-
         attributes-or-values-not-supported' status code (see [RFC2911],
         section 13.1.4.12).

      5. The values of some of the supplied attributes conflict with one
         another and/or other Job attribute values not being set:  if
         the conflicting attribute in the operation has a single value,
         return the attribute and the value.  If the attribute in the
         operation is multi-valued, return only the attribute and those
         values in a 1setOf that are conflicting with other attributes.
         Return the 'client-error-conflicting-attributes' status code
         (see [RFC2911],y section 13.1.4.15).

4.3 Get-Printer-Supported-Values Operation

This OPTIONAL operation allows a client to request the values that the Printer allows in the Set-Printer-Attributes operation for "xxx- supported" attributes. If the Printer supports the Set-Printer- Attributes operation AND some of its "xxx-supported" Printer attributes are settable, then the Printer MUST also support this operation. The Printer MUST return in the Get-Printer-Supported-Values response, those, and only those, "xxx-supported" Printer attributes that it supports setting with the Set-Printer-Attributes operation. Furthermore, if a client requests the value of an attribute that is not settable or is not supported (as in the Get-Printer-Attributes response), the Unsupported Attributes Group of the response NEED NOT contain the "requested-attributes" operation attribute with any such requested (attribute keyword) values. This operation has identical request/response attributes to the Get- Printer-Attributes operation in IPP/1.1 [RFC2911]. The operation also behaves identically to the Get-Printer-Attributes operation in IPP/1.1 [RFC2911], with the following exceptions: 1. The Get-Printer-Supported-Values operation supports only "xxx- supported" attributes. 2. The Get-Printer-Attributes operation returns the few "xxx- supported" attributes that are defined to be single valued, such as "page-ranges-supported" (boolean) or "pdl-override-supported" (type2 keyword), as single values, while Get-Printer-Supported-
Top   ToC   RFC3380 - Page 20
      Values returns the possible values that can be set as a 1setOf of
      the same attribute syntax type (See Appendix B: Attributes
      returned from Get-Printer-Supported-Values).

   3. The Get-Printer-Attributes operation returns the current values of
      requested attributes, while the Get-Printer-Supported-Values
      operation returns the values that are inherently supported by the
      implementation code, i.e., the values that an administrative
      client can set in a Set-Printer-Attributes request.

   4. The Get-Printer-Attributes operation returns the current values of
      requested "xxx-supported" attributes that the Printer is
      configured to accept in Job Creation operations, including
      additional values defined by the administrator, while the Get-
      Printer-Supported-Values operation returns only the values of
      "xxx-supported" attributes that are inherently supported by the
      implementation and does not return any additional values defined
      by the administrator, where the implementation supports the
      'admin-define' out-of-band value.

   5. The Get-Printer-Attributes never returns the 'admin-define' out-
      of-band attribute value, while the Get-Printer-Supported-
      Attributes operation does, if the implementation allows the
      administrator to define name values by setting that "xxx-
      supported" attribute with any 'name' value(s).

   6. The Get-Printer-Attributes operation only requires end-user access
      rights, while the Get-Printer-Supported-Values requires
      administrator access rights.

   Access Rights: The authenticated user (see [RFC2911], section 8.3)
   performing this operation must be an administrator of the Printer
   object (see [RFC2911], Sections 1 and 8.5).

4.3.1 Definition of the usage of the 'admin-define' out-of-band attribute value

If the Set-Printer-Attributes operation allows the System Administrator to define arbitrary 'name' values for an "xxx- supported" attribute, then the Get-Printer-Supported-Values operation MUST return the 'admin-define' out-of-band attribute value (see section 8.3) as one of the values of the "xxx-supported" attribute. In other words, the 'admin-define' out-of-band attribute value indicates that the Printer implementation supports clients setting arbitrary 'name' attribute syntax values for that "xxx-supported" attribute using the Set-Printer-Attributes operation, as long as the attribute is defined with the 'name' attribute syntax.
Top   ToC   RFC3380 - Page 21
   For example, if the Get-Printer-Supported-Values operation returns
   several keywords as the value of the "media-supported" attribute,
   then the Set-Printer-Attributes operation MUST accept any of these
   keywords as values for the "media-supported" attribute.  If the Get-
   Printer-Supported-Values operation returns an 'admin-define' out-of-
   band attribute value as one of the values of the "media-supported"
   attribute, then the Set-Printer-Attributes operation MUST accept any
   value whose attribute syntax is 'name', as a value for the "media-
   supported" attribute (provided that the user is properly
   authenticated to use the Set-Printer-Attributes operation, e.g., has
   administrative access rights).

   The Get-Printer-Supported-Values MAY return the 'admin-define' out-
   of-band attribute value for any IPP/1.1 or extension Job Template
   attribute if the implementation supports allowing the System
   Administrator to add values to the "xxx-supported" attribute using
   the Set-Printer-Attributes operation.  In this case, the Printer MUST
   accept any 'name' value of the correct attribute syntax in a Set-
   Printer-Attributes operation that is setting that attribute.  For
   "xxx-supported" attributes that are defined with a choice of
   attribute syntaxes, such as 'keyword | name', it is the 'name'
   attribute syntax that the System Administrator can use to add new
   values, not the 'keyword' attribute syntax.  For IPP/1.1, this
   requirement includes the following Job Template attributes:

      media-supported
      job-hold-until-supported
      job-sheets-supported

   Implementations that support additional Job Template attributes that
   include the 'name' attribute syntax, MAY use the 'admin-define' out-
   of-band value with them.

   If the 'admin-define' out-of-band attribute value is not one of the
   values of an "xxx-supported" attribute returned in a Get-Printer-
   Supported-Values response, then the Printer MUST NOT allow the Set-
   Printer-Attributes operation for that attribute to contain a value
   that is not one of the explicit 'keyword' or 'name' values returned
   in a Get-Printer-Supported-Values response.

   See Appendix B: Attributes returned from Get-Printer-Supported-Values
   for a full list of values returned by this operation.


(next page on part 2)

Next Section