Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 2911

Internet Printing Protocol/1.1: Model and Semantics

Pages: 224
Obsoletes:  2566
Obsoleted by:  8011
Updated by:  33803382399639957472
Part 3 of 9 – Pages 41 to 65
First   Prev   Next

ToP   noToC   RFC2911 - Page 41   prevText

3.2 Printer Operations

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.

3.2.1 Print-Job Operation

This REQUIRED operation allows a client to submit a print job with only one document and supply the document data (rather than just a reference to the data). See Section 15 for the suggested steps for processing create operations and their Operation and Job Template attributes.
3.2.1.1 Print-Job Request
The following groups of attributes are supplied as part of the Print-Job Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. The Printer object MUST copy these values to the corresponding Job Description attributes described in sections 4.3.19 and 4.3.20. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3. "job-name" (name(MAX)): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It contains the client supplied Job name. If this attribute is supplied by the client, its value is used for the "job-name" attribute of the newly created Job object. The client MAY automatically include any information that will help the end-user distinguish amongst his/her jobs, such as the name of the application program along with information from the document, such as the document name, document subject, or source file name. If this attribute is not supplied by the client, the Printer generates a name to use in the "job-name" attribute of the newly created Job object (see Section 4.3.5).
ToP   noToC   RFC2911 - Page 42
      "ipp-attribute-fidelity" (boolean):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.  The value 'true' indicates
         that total fidelity to client supplied Job Template attributes
         and values is required, else the Printer object MUST reject the
         Print-Job request.  The value 'false' indicates that a
         reasonable attempt to print the Job object is acceptable and
         the Printer object MUST accept the Print-Job request. If not
         supplied, the Printer object assumes the value is 'false'.  All
         Printer objects MUST support both types of job processing.  See
         section 15 for a full description of "ipp-attribute-fidelity"
         and its relationship to other attributes, especially the
         Printer object's "pdl-override-supported" attribute.

      "document-name" (name(MAX)):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.   It contains the client
         supplied document name.  The document name MAY be different
         than the Job name.  Typically, the client software
         automatically supplies the document name on behalf of the end
         user by using a file name or an application generated name.  If
         this attribute is supplied, its value can be used in a manner
         defined by each implementation.  Examples include: printed
         along with the Job (job start sheet, page adornments, etc.),
         used by accounting or resource tracking management tools, or
         even stored along with the document as a document level
         attribute.  IPP/1.1 does not support the concept of document
         level attributes.

      "compression" (type3 keyword):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute and the "compression-
         supported" attribute (see section 4.4.32).  The client supplied
         "compression" operation attribute identifies the compression
         algorithm used on the document data. The following cases exist:

         a) If the client omits this attribute, the Printer object MUST
            assume that the data is not compressed   (i.e. the Printer
            follows the rules below as if the client supplied the
            "compression" attribute with a value of 'none').
         b) If the client supplies this attribute, but the value is not
            supported by the Printer object, i.e., the value is not one
            of the values of the Printer object's "compression-
            supported" attribute, the Printer object MUST reject the
            request, and return the 'client-error-compression-not-
            supported' status code. See section 3.1.7 for returning
            unsupported attributes and values.
ToP   noToC   RFC2911 - Page 43
         c) If the client supplies the attribute and the Printer object
            supports the attribute value, the Printer object uses the
            corresponding decompression algorithm on the document data.
         d) If the decompression algorithm fails before the Printer
            returns an operation response, the Printer object MUST
            reject the request and return the 'client-error-
            compression-error' status code.
         e) If the decompression algorithm fails after the Printer
            returns an operation response, the Printer object MUST abort
            the job and add the 'compression-error' value to the job's
            "job-state-reasons" attribute.
         f) If the decompression algorithm succeeds, the document data
            MUST then have the format specified by the job's "document-
            format" attribute, if supplied (see "document-format"
            operation attribute definition below).

      "document-format" (mimeMediaType):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.  The value of this
         attribute identifies the format of the supplied document data.
         The following cases exist:

         a) If the client does not supply this attribute, the Printer
            object assumes that the document data is in the format
            defined by the Printer object's "document-format-default"
            attribute. (i.e. the Printer follows the rules below as if
            the client supplied the "document-format" attribute with a
            value equal to the printer's default value).
         b) If the client supplies this attribute, but the value is not
            supported by the Printer object, i.e., the value is not one
            of the values of the Printer object's "document-format-
            supported" attribute, the Printer object MUST reject the
            request and return the 'client-error-document-format-not-
            supported' status code.
         c) If the client supplies this attribute and its value is
            'application/octet-stream' (i.e. to be auto-sensed, see
            Section 4.1.9.1), and the format is not one of the
            document-formats that the Printer can auto-sense, and this
            check occurs before the Printer returns an operation
            response, then the Printer MUST reject the request and
            return the  'client-error-document-format-not-supported'
            status code.
         d) If the client supplies this attribute, and the value is
            supported by the Printer object, the Printer is capable of
            interpreting the document data.
ToP   noToC   RFC2911 - Page 44
         e) If interpreting of the document data fails before the
            Printer returns an operation response, the Printer object
            MUST reject the request and return the 'client-error-
            document-format-error' status code.
         f) If interpreting of the document data fails after the Printer
            returns an operation response, the Printer object MUST abort
            the job and add the 'document-format-error' value to the
            job's "job-state-reasons" attribute.

      "document-natural-language" (naturalLanguage):
         The client OPTIONALLY supplies this attribute.  The Printer
         object OPTIONALLY supports this attribute. This attribute
         specifies the natural language of the document for those
         document-formats that require a specification of the natural
         language in order to image the document unambiguously. There
         are no particular values required for the Printer object to
         support.

      "job-k-octets" (integer(0:MAX)):
         The client OPTIONALLY supplies this attribute.  The Printer
         object OPTIONALLY supports this attribute and the "job-k-
         octets-supported" attribute (see section 4.4.33).  The client
         supplied "job-k-octets" operation attribute identifies the
         total size of the document(s) in K octets being submitted (see
         section 4.3.17.1 for the complete semantics).  If the client
         supplies the attribute and the Printer object supports the
         attribute, the value of the attribute is used to populate the
         Job object's "job-k-octets" Job Description attribute.

         For this attribute and the following two attributes ("job-
         impressions", and "job-media-sheets"), if the client supplies
         the attribute, but the Printer object does not support the
         attribute, the Printer object ignores the client-supplied
         value.  If the client supplies the attribute and the Printer
         supports the attribute, and the value is within the range of
         the corresponding Printer object's "xxx-supported" attribute,
         the Printer object MUST use the value to populate the Job
         object's "xxx" attribute.  If the client supplies the attribute
         and the Printer supports the attribute, but the value is
         outside the range of the corresponding Printer object's "xxx-
         supported" attribute, the Printer object MUST copy the
         attribute and its value to the Unsupported Attributes response
         group, reject the request, and return the 'client-error-
         attributes-or-values-not-supported' status code.  If the client
         does not supply the attribute, the Printer object MAY choose to
         populate the corresponding Job object attribute depending on
         whether the Printer object supports the attribute and is able
         to calculate or discern the correct value.
ToP   noToC   RFC2911 - Page 45
      "job-impressions" (integer(0:MAX)):
         The client OPTIONALLY supplies this attribute.  The Printer
         object OPTIONALLY supports this attribute and the "job-
         impressions-supported" attribute (see section 4.4.34).  The
         client supplied "job-impressions" operation attribute
         identifies the total size in number of impressions of the
         document(s) being submitted (see section 4.3.17.2 for the
         complete semantics).

         See last paragraph under "job-k-octets".

      "job-media-sheets" (integer(0:MAX)):
         The client OPTIONALLY supplies this attribute.  The Printer
         object OPTIONALLY supports this attribute and the "job-media-
         sheets-supported" attribute (see section 4.4.35).  The client
         supplied "job-media-sheets" operation attribute identifies the
         total number of media sheets to be produced for this job (see
         section 4.3.17.3 for the complete semantics).

         See last paragraph under "job-k-octets".

   Group 2: Job Template Attributes

      The client OPTIONALLY supplies a set of Job Template attributes as
      defined in section 4.2.  If the client is not supplying any Job
      Template attributes in the request, the client SHOULD omit Group 2
      rather than sending an empty group.  However, a Printer object
      MUST be able to accept an empty group.

   Group 3: Document Content

      The client MUST supply the document data to be processed.

      In addition to the MANDATORY parameters required for every
      operation request, the simplest Print-Job Request consists of just
      the "attributes-charset" and "attributes-natural-language"
      operation attributes; the "printer-uri" target operation
      attribute; the Document Content and nothing else.  In this simple
      case, the Printer object:

      - creates a new Job object (the Job object contains a single
        document),
      - stores a generated Job name in the "job-name" attribute in the
        natural language and charset requested (see Section 3.1.4.1) (if
        those are supported, otherwise using the Printer object's
        default natural language and charset), and
ToP   noToC   RFC2911 - Page 46
      - at job processing time, uses its corresponding default value
        attributes for the supported Job Template attributes that were
        not supplied by the client as IPP attribute or embedded
        instructions in the document data.

3.2.1.2 Print-Job Response
The Printer object MUST return to the client the following sets of attributes as part of the Print-Job 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 sections 13 and 3.1.6. If the client supplies unsupported or conflicting Job Template attributes or values, the Printer object MUST reject or accept the Print-Job request depending on the whether the client supplied a 'true' or 'false' value for the "ipp-attribute- fidelity" operation attribute. See the Implementer's Guide [IPP-IIG] for a complete description of the suggested steps for processing a create request. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. The value of the "ipp-attribute-fidelity" supplied by the client does not affect what attributes the Printer object returns in this group. The value of "ipp-attribute-fidelity" only affects whether the Print-Job operation is accepted or rejected. If the job is accepted, the client may query the job using the Get-Job- Attributes operation requesting the unsupported attributes that were returned in the create response to see which attributes were ignored (not stored on the Job object) and which attributes were stored with other (substituted) values.
ToP   noToC   RFC2911 - Page 47
   Group 3: Job Object Attributes

      "job-uri" (uri):
         The Printer object MUST return the Job object's URI by
         returning the contents of the REQUIRED "job-uri" Job object
         attribute.  The client uses the Job object's URI when directing
         operations at the Job object.  The Printer object always uses
         its configured security policy when creating the new URI.
         However, if the Printer object supports more than one URI, the
         Printer object also uses information about which URI was used
         in the Print-Job Request to generated the new URI so that the
         new URI references the correct access channel.  In other words,
         if the Print-Job Request comes in over a secure channel, the
         Printer object MUST generate a Job URI that uses the secure
         channel as well.

      "job-id" (integer(1:MAX)):
         The Printer object MUST return the Job object's Job ID by
         returning the REQUIRED  "job-id" Job object attribute.  The
         client uses this "job-id" attribute in conjunction with the
         "printer-uri" attribute used in the Print-Job Request when
         directing Job operations at the Printer object.

      "job-state" (type1 enum):
         The Printer object MUST return the Job object's REQUIRED "job-
         state" attribute. The value of this attribute (along with the
         value of the next attribute:  "job-state-reasons") is taken
         from a "snapshot" of the new Job object at some meaningful
         point in time (implementation defined) between when the Printer
         object receives the Print-Job Request and when the Printer
         object returns the response.

      "job-state-reasons" (1setOf type2 keyword):
         The Printer object MUST return the Job object's REQUIRED "job-
         state-reasons" attribute.

      "job-state-message" (text(MAX)):
         The Printer object OPTIONALLY returns the Job object's OPTIONAL
         "job-state-message" attribute.  If the Printer object supports
         this attribute then it MUST be returned in the response.  If
         this attribute is not returned in the response, the client can
         assume that the "job-state-message" attribute is not supported
         and will not be returned in a subsequent Job object query.

      "number-of-intervening-jobs" (integer(0:MAX)):
         The Printer object OPTIONALLY returns the Job object's OPTIONAL
         "number-of-intervening-jobs" attribute.  If the Printer object
         supports this attribute then it MUST be returned in the
ToP   noToC   RFC2911 - Page 48
         response.  If this attribute is not returned in the response,
         the client can assume that the "number-of-intervening-jobs"
         attribute is not supported and will not be returned in a
         subsequent Job object query.

         Note: Since any printer state information which affects a job's
         state is reflected in the "job-state" and "job-state-reasons"
         attributes, it is sufficient to return only these attributes
         and no specific printer status attributes.

   Note: In addition to the MANDATORY parameters required for every
   operation response, the simplest response consists of the just the
   "attributes-charset" and "attributes-natural-language" operation
   attributes and the "job-uri", "job-id", and "job-state" Job Object
   Attributes.  In this simplest case, the status code is 'successful-
   ok' and there is no "status-message" or "detailed-status-message"
   operation attribute.

3.2.2 Print-URI Operation

This OPTIONAL operation is identical to the Print-Job operation (section 3.2.1) except that a client supplies a URI reference to the document data using the "document-uri" (uri) operation attribute (in Group 1) rather than including the document data itself. Before returning the response, the Printer MUST validate that the Printer supports the retrieval method (e.g., http, ftp, etc.) implied by the URI, and MUST check for valid URI syntax. If the client-supplied URI scheme is not supported, i.e. the value is not in the Printer object's "referenced-uri-scheme-supported" attribute, the Printer object MUST reject the request and return the 'client-error-uri- scheme-not-supported' status code. The IPP Printer MAY validate the accessibility of the document as part of the operation or subsequently. If the Printer determines an accessibility problem before returning an operation response, it rejects the request and returns the 'client-error-document-access- error' status code. The Printer MAY also return a specific document access error code using the "document-access-error" operation attribute (see section 3.1.6.4). If the Printer determines this document accessibility problem after accepting the request and returning an operation response with one of the successful status codes, the Printer adds the 'document-access- error' value to the job's "job-state-reasons" attribute and MAY populate the job's "job-document-access-errors" Job Description attribute (see section 4.3.11). See The Implementer's Guide [IPP- IIG] for suggested additional checks.
ToP   noToC   RFC2911 - Page 49
   If the Printer object supports this operation, it MUST support the
   "reference-uri-schemes-supported" Printer attribute (see section
   4.4.27).

   It is up to the IPP object to interpret the URI and subsequently
   "pull" the document from the source referenced by the URI string.

3.2.3 Validate-Job Operation

This REQUIRED operation is similar to the Print-Job operation (section 3.2.1) except that a client supplies no document data and the Printer allocates no resources (i.e., it does not create a new Job object). This operation is used only to verify capabilities of a printer object against whatever attributes are supplied by the client in the Validate-Job request. By using the Validate-Job operation a client can validate that an identical Print-Job operation (with the document data) would be accepted. The Validate-Job operation also performs the same security negotiation as the Print-Job operation (see section 8), so that a client can check that the client and Printer object security requirements can be met before performing a Print-Job operation. The Validate-Job operation does not accept a "document-uri" attribute in order to allow a client to check that the same Print-URI operation will be accepted, since the client doesn't send the data with the Print-URI operation. The client SHOULD just issue the Print-URI request. The Printer object returns the same status codes, Operation Attributes (Group 1) and Unsupported Attributes (Group 2) as the Print-Job operation. However, no Job Object Attributes (Group 3) are returned, since no Job object is created.

3.2.4 Create-Job Operation

This OPTIONAL operation is similar to the Print-Job operation (section 3.2.1) except that in the Create-Job request, a client does not supply document data or any reference to document data. Also, the client does not supply any of the "document-name", "document- format", "compression", or "document-natural-language" operation attributes. This operation is followed by one or more Send-Document or Send-URI operations. In each of those operation requests, the client OPTIONALLY supplies the "document-name", "document-format", and "document-natural-language" attributes for each document in the multi-document Job object.
ToP   noToC   RFC2911 - Page 50
   If a Printer object supports the Create-Job operation, it MUST also
   support the Send-Document operation and also MAY support the Send-URI
   operation.

   If the Printer object supports this operation, it MUST support the
   "multiple-operation-time-out" Printer attribute (see section 4.4.31).

   If the Printer object supports this operation, then it MUST support
   the "multiple-document-jobs-supported" Printer Description attribute
   (see section 4.4.16) and indicate whether or not it supports
   multiple-document jobs.

   If the Printer object supports this operation and supports multiple
   documents in a job, then it MUST support the "multiple-document-
   handling" Job Template job attribute with at least one value (see
   section 4.2.4) and the associated "multiple-document-handling-
   default" and "multiple-document-handling-supported" Job Template
   Printer attributes (see section 4.2).

   After the Create-Job operation has completed, the value of the "job-
   state" attribute is similar to the "job-state" after a Print-Job,
   even though no document-data has arrived.  A Printer MAY set the
   'job-data-insufficient' value of the job's "job-state-reason"
   attribute to indicate that processing cannot begin until sufficient
   data has arrived and set the "job-state" to either 'pending' or
   'pending-held'.  A non-spooling printer that doesn't implement the
   'pending' job state may even set the "job-state" to 'processing',
   even though there is not yet any data to process.  See sections 4.3.7
   and 4.3.8.

3.2.5 Get-Printer-Attributes Operation

This REQUIRED operation allows a client to request the values of the attributes of a Printer object. In the request, the client supplies the set of Printer attribute names and/or attribute group names in which the requester is interested. In the response, the Printer object returns a corresponding attribute set with the appropriate attribute values filled in. For Printer objects, the possible names of attribute groups are: - 'job-template': the subset of the Job Template attributes that apply to a Printer object (the last two columns of the table in Section 4.2) that the implementation supports for Printer objects. - 'printer-description': the subset of the attributes specified in Section 4.4 that the implementation supports for Printer objects.
ToP   noToC   RFC2911 - Page 51
      - 'all': the special group 'all' that includes all attributes that
        the implementation supports for Printer objects.

   Since a client MAY request specific attributes or named groups, there
   is a potential that there is some overlap.  For example, if a client
   requests, 'printer-name' and 'all', the client is actually requesting
   the "printer-name" attribute twice: once by naming it explicitly, and
   once by inclusion in the 'all' group.  In such cases, the Printer
   object NEED NOT return each attribute only once in the response even
   if it is requested multiple times.  The client SHOULD NOT request the
   same attribute in multiple ways.

   It is NOT REQUIRED that a Printer object support all attributes
   belonging to a group (since some attributes are OPTIONAL).  However,
   it is REQUIRED that each Printer object support all group names.

3.2.5.1 Get-Printer-Attributes Request
The following sets of attributes are part of the Get-Printer- Attributes Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3. "requested-attributes" (1setOf keyword): The client OPTIONALLY supplies a set of attribute names and/or attribute group names in whose values the requester is interested. The Printer object MUST support this attribute. If the client omits this attribute, the Printer MUST respond as if this attribute had been supplied with a value of 'all'. "document-format" (mimeMediaType): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. This attribute is useful for a Printer object to determine the set of supported attribute values that relate to the requested document format. The Printer object MUST return the attributes and values that
ToP   noToC   RFC2911 - Page 52
         it uses to validate a job on a create or Validate-Job operation
         in which this document format is supplied. The Printer object
         SHOULD return only (1) those attributes that are supported for
         the specified format and (2) the attribute values that are
         supported for the specified document format.  By specifying the
         document format, the client can get the Printer object to
         eliminate the attributes and values that are not supported for
         a specific document format.  For example, a Printer object
         might have multiple interpreters to support both
         'application/postscript' (for PostScript) and 'text/plain' (for
         text) documents.  However, for only one of those interpreters
         might the Printer object be able to support "number-up" with
         values of '1', '2', and '4'.  For the other interpreter it
         might be able to only support "number-up" with a value of '1'.
         Thus a client can use the Get-Printer-Attributes operation to
         obtain the attributes and values that will be used to
         accept/reject a create job operation.

         If the Printer object does not distinguish between different
         sets of supported values for each different document format
         when validating jobs in the create and Validate-Job operations,
         it MUST NOT distinguish between different document formats in
         the Get-Printer-Attributes operation. If the Printer object
         does distinguish between different sets of supported values for
         each different document format specified by the client, this
         specialization applies only to the following Printer object
         attributes:

      - Printer attributes that are Job Template attributes ("xxx-
        default" "xxx-supported", and "xxx-ready" in the Table in
        Section 4.2),
      - "pdl-override-supported",
      - "compression-supported",
      - "job-k-octets-supported",
      - "job-impressions-supported",
      - "job-media-sheets-supported",
      - "printer-driver-installer",
      - "color-supported", and
      - "reference-uri-schemes-supported"

      The values of all other Printer object attributes (including
      "document-format-supported") remain invariant with respect to the
      client supplied document format (except for new Printer
      description attribute as registered according to section 6.2).

      If the client omits this "document-format" operation attribute,
      the Printer object MUST respond as if the attribute had been
      supplied with the value of the Printer object's "document-format-
ToP   noToC   RFC2911 - Page 53
      default" attribute.  It is RECOMMENDED that the client always
      supply a value for "document-format", since the Printer object's
      "document-format-default" may be 'application/octet-stream', in
      which case the returned attributes and values are for the union of
      the document formats that the Printer can automatically sense.
      For more details, see the description of the 'mimeMediaType'
      attribute syntax in section 4.1.9.

      If the client supplies a value for the "document-format" Operation
      attribute that is 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.

3.2.5.2 Get-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 sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. The response NEED NOT contain the "requested-attributes" operation attribute with any supplied values (attribute keywords) 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 and that attribute included group names, such as 'all', the unsupported attributes MUST NOT include attributes described in the standard but not supported by the implementation.
ToP   noToC   RFC2911 - Page 54
   Group 3: Printer Object Attributes

      This is the set of requested attributes and their current values.
      The Printer object ignores (does not respond with) any requested
      attribute which is not supported.  The Printer object MAY respond
      with a subset of the supported attributes and values, depending on
      the security policy in force.  However, the Printer object MUST
      respond with the 'unknown' value for any supported attribute
      (including all REQUIRED attributes) for which the Printer object
      does not know the value.  Also the Printer object MUST respond
      with the 'no-value' for any supported attribute (including all
      REQUIRED attributes) for which the system administrator has not
      configured a value.  See the description of the "out-of-band"
      values in the beginning of Section 4.1.

3.2.6 Get-Jobs Operation

This REQUIRED operation allows a client to retrieve the list of Job objects belonging to the target Printer object. The client may also supply a list of Job attribute names and/or attribute group names. A group of Job object attributes will be returned for each Job object that is returned. This operation is similar to the Get-Job-Attributes operation, except that this Get-Jobs operation returns attributes from possibly more than one object.
3.2.6.1 Get-Jobs Request
The client submits the Get-Jobs request to a Printer object. The following groups of attributes are part of the Get-Jobs Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3.
ToP   noToC   RFC2911 - Page 55
      "limit" (integer(1:MAX)):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute. It is an integer value that
         determines the maximum number of jobs that a client will
         receive from the Printer even if "which-jobs" or "my-jobs"
         constrain which jobs are returned.  The limit is a "stateless
         limit" in that if the value supplied by the client is 'N', then
         only the first 'N' jobs are returned in the Get-Jobs Response.
         There is no mechanism to allow for the next 'M' jobs after the
         first 'N' jobs.  If the client does not supply this attribute,
         the Printer object responds with all applicable jobs.

      "requested-attributes" (1setOf type2 keyword):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.  It is a set of Job
         attribute names and/or attribute groups names in whose values
         the requester is interested.  This set of attributes is
         returned for each Job object that is returned.  The allowed
         attribute group names are the same as those defined in the
         Get-Job-Attributes operation in section 3.3.4.  If the client
         does not supply this attribute, the Printer MUST respond as if
         the client had supplied this attribute with two values: 'job-
         uri' and 'job-id'.

      "which-jobs" (type2 keyword):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.  It indicates which Job
         objects MUST be returned by the Printer object. The values for
         this attribute are:

      'completed': This includes any Job object whose state is
         'completed', 'canceled', or 'aborted'.
      'not-completed': This includes any Job object whose state is
         'pending', 'processing', 'processing-stopped', or 'pending-
         held'.

         A Printer object MUST support both values.  However, if the
         implementation does not keep jobs in the 'completed',
         'canceled', and 'aborted' states, then it returns no jobs when
         the 'completed' value is supplied.

         If a client supplies some other value, the Printer object MUST
         copy the attribute and the unsupported value to the Unsupported
         Attributes response group, reject the request, and return the
         'client-error-attributes-or-values-not-supported' status code.
ToP   noToC   RFC2911 - Page 56
         If the client does not supply this attribute, the Printer
         object MUST respond as if the client had supplied the attribute
         with a value of 'not-completed'.

      "my-jobs" (boolean):
         The client OPTIONALLY supplies this attribute.  The Printer
         object MUST support this attribute.  It indicates whether jobs
         from all users or just the jobs submitted by the requesting
         user of this request MUST be considered as candidate jobs to be
         returned by the Printer object.  If the client does not supply
         this attribute, the Printer object MUST respond as if the
         client had supplied the attribute with a value of 'false',
         i.e., jobs from all users.  The means for authenticating the
         requesting user and matching the jobs is described in section
         8.

3.2.6.2 Get-Jobs Response
The Printer object returns all of the Job objects up to the number specified by the "limit" attribute that match the criteria as defined by the attribute values supplied by the client in the request. It is possible that no Job objects are returned since there may literally be no Job objects at the Printer, or there may be no Job objects that match the criteria supplied by the client. If the client requests any Job attributes at all, there is a set of Job Object Attributes returned for each Job object. It is not an error for the Printer to return 0 jobs. If the response returns 0 jobs because there are no jobs matching the criteria, and the request would have returned 1 or more jobs with a status code of 'successful-ok' if there had been jobs matching the criteria, then the status code for 0 jobs MUST be 'successful-ok'. 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 sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2.
ToP   noToC   RFC2911 - Page 57
   Group 2: Unsupported Attributes

      See section 3.1.7 for details on returning Unsupported Attributes.

      The response NEED NOT contain the "requested-attributes" operation
      attribute with any supplied values (attribute keywords) 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 and
      that attribute included group names, such as 'all', the
      unsupported attributes MUST NOT include attributes described in
      the standard but not supported by the implementation.

   Groups 3 to N: Job Object Attributes

      The Printer object responds with one set of Job Object Attributes
      for each returned Job object.  The Printer object ignores (does
      not respond with) any requested attribute or value which is not
      supported or which is restricted by the security policy in force,
      including whether the requesting user is the user that submitted
      the job (job originating user) or not (see section 8).  However,
      the Printer object MUST respond with the 'unknown' value for any
      supported attribute (including all REQUIRED attributes) for which
      the Printer object does not know the value, unless it would
      violate the security policy.  See the description of the "out-of-
      band" values in the beginning of Section 4.1.

      Jobs are returned in the following order:

      - If the client requests all 'completed' Jobs (Jobs in the
        'completed', 'aborted', or 'canceled' states), then the Jobs are
        returned newest to oldest (with respect to actual completion
        time)
      - If the client requests all 'not-completed' Jobs (Jobs in the
        'pending', 'processing', 'pending-held', and 'processing-
        stopped' states), then Jobs are returned in relative
        chronological order of expected time to complete (based on
        whatever scheduling algorithm is configured for the Printer
        object).

3.2.7 Pause-Printer Operation

This OPTIONAL operation allows a client to stop the Printer object from scheduling jobs on all its devices. Depending on implementation, the Pause-Printer operation MAY also stop the Printer from processing the current job or jobs. Any job that is currently being printed is either stopped as soon as the implementation permits
ToP   noToC   RFC2911 - Page 58
   or is completed, depending on implementation.  The Printer object
   MUST still accept create operations to create new jobs, but MUST
   prevent any jobs from entering the 'processing' state.

   If the Pause-Printer operation is supported, then the Resume-Printer
   operation MUST be supported, and vice-versa.

   The IPP Printer stops the current job(s) on its device(s) that were
   in the 'processing' or 'processing-stopped' states as soon as the
   implementation permits.  If the implementation will take appreciable
   time to stop, the IPP Printer adds the 'moving-to-paused' value to
   the Printer object's "printer-state-reasons" attribute (see section
   4.4.12).  When the device(s) have all stopped, the IPP Printer
   transitions the Printer object to the 'stopped' state, removes the
   'moving-to-paused' value, if present, and adds the 'paused' value to
   the Printer object's "printer-state-reasons" attribute.

   When the current job(s) complete that were in the 'processing' state,
   the IPP Printer transitions them to the 'completed' state.  When the
   current job(s) stop in mid processing that were in the 'processing'
   state, the IPP Printer transitions them to the 'processing-stopped'
   state and adds the 'printer-stopped' value to the job's "job-state-
   reasons" attribute.

   For any jobs that are 'pending' or 'pending-held', the 'printer-
   stopped' value of the jobs' "job-state-reasons" attribute also
   applies.  However, the IPP Printer NEED NOT update those jobs' "job-
   state-reasons" attributes and only need return the 'printer-stopped'
   value when those jobs are queried (so-called "lazy evaluation").

   Whether the Pause-Printer operation affects jobs that were submitted
   to the device from other sources than the IPP Printer object in the
   same way that the Pause-Printer operation affects jobs that were
   submitted to the IPP Printer object using IPP, depends on
   implementation, i.e., on whether the IPP protocol is being used as a
   universal management protocol or just to manage IPP jobs,
   respectively.

   The IPP Printer MUST accept the request in any state and transition
   the Printer to the indicated new "printer-state" before returning as
   follows:
ToP   noToC   RFC2911 - Page 59
     Current        New      "printer   IPP Printer's response status
    "printer-    "printer-   -state-          code and action:
     state"       state"    reasons"

  'idle'       'stopped'    'paused'  'successful-ok'
  'processing' 'processing' 'moving-  OPTION 1: 'successful-ok';
                              to-       Later, when all output has
                              paused'   stopped, the "printer-state"
                                        becomes 'stopped', and the
                                        'paused' value replaces the
                                        'moving-to-paused' value in the
                                        "printer-state-reasons"
                                        attribute
  'processing' 'stopped'    'paused'  OPTION 2: 'successful-ok';
                                        all device output stopped
                                        immediately
  'stopped'    'stopped'    'paused'  'successful-ok'

   Access Rights: The authenticated user (see section 8.3) performing
   this operation must be an operator or administrator of the Printer
   object (see Sections 1 and 8.5).   Otherwise, the IPP Printer MUST
   reject the operation and return:  'client-error-forbidden', 'client-
   error-not-authenticated', or 'client-error-not-authorized' as
   appropriate.

3.2.7.1 Pause-Printer Request
The following groups of attributes are part of the Pause-Printer Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.1. Target: The "printer-uri" (uri) operation attribute which is the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3.
ToP   noToC   RFC2911 - Page 60
3.2.7.2 Pause-Printer Response
The following groups of attributes are part of the Pause-Printer 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 sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes.

3.2.8 Resume-Printer Operation

This operation allows a client to resume the Printer object scheduling jobs on all its devices. The Printer object MUST remove the 'paused' and 'moving-to-paused' values from the Printer object's "printer-state-reasons" attribute, if present. If there are no other reasons to keep a device paused (such as media-jam), the IPP Printer is free to transition itself to the 'processing' or 'idle' states, depending on whether there are jobs to be processed or not, respectively, and the device(s) resume processing jobs. If the Pause-Printer operation is supported, then the Resume-Printer operation MUST be supported, and vice-versa. The IPP Printer removes the 'printer-stopped' value from any job's "job-state-reasons" attributes contained in that Printer. The IPP Printer MUST accept the request in any state, transition the Printer object to the indicated new state as follows:
ToP   noToC   RFC2911 - Page 61
     Current    New "printer-  IPP Printer's response status code and
    "printer-      state"                     action:
      state"

   'idle'       'idle'         'successful-ok'
   'processing' 'processing'   'successful-ok'

   'stopped'    'processing'   'successful-ok';
                               when there are jobs to be processed
   'stopped'    'idle'         'successful-ok';
                               when there are no jobs to be processed.

   Access Rights: The authenticated user (see section 8.3) performing
   this operation must be an operator or administrator of the Printer
   object (see Sections 1 and 8.5).  Otherwise, the IPP Printer MUST
   reject the operation and return:  'client-error-forbidden', 'client-
   error-not-authenticated', or 'client-error-not-authorized' as
   appropriate.

   The Resume-Printer Request and Resume-Printer Response have the same
   attribute groups and attributes as the Pause-Printer operation (see
   sections 3.2.7.1 and 3.2.7.2).

3.2.9 Purge-Jobs Operation

This OPTIONAL operation allows a client to remove all jobs from an IPP Printer object, regardless of their job states, including jobs in the Printer object's Job History (see Section 4.3.7.2). After a Purge-Jobs operation has been performed, a Printer object MUST return no jobs in subsequent Get-Job-Attributes and Get-Jobs responses (until new jobs are submitted). Whether the Purge-Jobs (and Get-Jobs) operation affects jobs that were submitted to the device from other sources than the IPP Printer object in the same way that the Purge-Jobs operation affects jobs that were submitted to the IPP Printer object using IPP, depends on implementation, i.e., on whether the IPP protocol is being used as a universal management protocol or just to manage IPP jobs, respectively. Note: if an operator wants to cancel all jobs without clearing out the Job History, the operator uses the Cancel-Job operation on each job instead of using the Purge-Jobs operation. The Printer object MUST accept this operation in any state and transition the Printer object to the 'idle' state.
ToP   noToC   RFC2911 - Page 62
   Access Rights: The authenticated user (see section 8.3) performing
   this operation must be an operator or administrator of the Printer
   object (see Sections 1 and 8.5).  Otherwise, the IPP object MUST
   reject the operation and return: client-error-forbidden, client-
   error-not-authenticated, and client-error-not-authorized as
   appropriate.

   The Purge-Jobs Request and Purge-Jobs Response have the same
   attribute groups and attributes as the Pause-Printer operation (see
   sections 3.2.7.1 and 3.2.7.2).

3.3 Job Operations

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. The IPP object implementation MUST support both forms of identification for every job.

3.3.1 Send-Document Operation

This OPTIONAL operation allows a client to create a multi-document Job object that is initially "empty" (contains no documents). In the Create-Job response, the Printer object returns the Job object's URI (the "job-uri" attribute) and the Job object's 32-bit identifier (the "job-id" attribute). For each new document that the client desires to add, the client uses a Send-Document operation. Each Send- Document Request contains the entire stream of document data for one document. If the Printer supports this operation but does not support multiple documents per job, the Printer MUST reject subsequent Send-Document operations supplied with data and return the 'server-error-multiple- document-jobs-not-supported'. However, the Printer MUST accept the first document with a 'true' or 'false' value for the "last-document" operation attribute (see below), so that clients MAY always submit one document jobs with a 'false' value for "last-document" in the first Send-Document and a 'true' for "last-document" in the second Send-Document (with no data). Since the Create-Job and the send operations (Send-Document or Send- URI operations) that follow could occur over an arbitrarily long period of time for a particular job, a client MUST send another send operation within an IPP Printer defined minimum time interval after the receipt of the previous request for the job. If a Printer object supports the Create-Job and Send-Document operations, the Printer object MUST support the "multiple-operation-time-out" attribute (see
ToP   noToC   RFC2911 - Page 63
   section 4.4.31).  This attribute indicates the minimum number of
   seconds the Printer object will wait for the next send operation
   before taking some recovery action.

   An IPP object MUST recover from an errant client that does not supply
   a send operation, sometime after the minimum time interval specified
   by the Printer object's "multiple-operation-time-out" attribute.
   Such recovery MAY include any of the following or other recovery
   actions:

      1. Assume that the Job is an invalid job, start the process of
         changing the job state to 'aborted', add the 'aborted-by-
         system' value to the job's "job-state-reasons" attribute (see
         section 4.3.8), and clean up all resources associated with the
         Job.  In this case, if another send operation is finally
         received, the Printer responds with an "client-error-not-
         possible" or "client-error-not-found" depending on whether or
         not the Job object is still around when the send operation
         finally arrives.
      2. Assume that the last send operation received was in fact the
         last document (as if the "last-document" flag had been set to
         'true'), close the Job object, and proceed to process it (i.e.,
         move the Job's state to 'pending').
      3. Assume that the last send operation received was in fact the
         last document, close the Job, but move it to the 'pending-held'
         and add the 'submission-interrupted' value to the job's "job-
         state-reasons" attribute (see section 4.3.8).  This action
         allows the user or an operator to determine whether to continue
         processing the Job by moving it back to the 'pending' state
         using the Release-Job operation (see section 3.3.6) or to
         cancel the job using the Cancel-Job operation (see section
         3.3.3).

   Each implementation is free to decide the "best" action to take
   depending on local policy, whether any documents have been added,
   whether the implementation spools jobs or not,  and/or any other
   piece of information available to it.  If the choice is to abort the
   Job object, it is possible that the Job object may already have been
   processed to the point that some media sheet pages have been printed.

   Access Rights: The authenticated user (see section 8.3) performing
   this operation must either be the job owner (as determined in the
   Create-Job operation) or an operator or administrator of the Printer
   object (see Sections 1 and 8.5).  Otherwise, the IPP object MUST
   reject the operation and return: 'client-error-forbidden', 'client-
   error-not-authenticated', or 'client-error-not-authorized' as
   appropriate.
ToP   noToC   RFC2911 - Page 64
3.3.1.1 Send-Document Request
The following attribute sets are part of the Send-Document Request: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in 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 define the target for this operation as described in section 3.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the client as described in section 8.3. "document-name" (name(MAX)): The client OPTIONALLY supplies this attribute. The Printer object MUST support this attribute. It contains the client supplied document name. The document name MAY be different than the Job name. It might be helpful, but NEED NOT be unique across multiple documents in the same Job. Typically, the client software automatically supplies the document name on behalf of the end user by using a file name or an application generated name. See the description of the "document-name" operation attribute in the Print-Job Request (section 3.2.1.1) for more information about this attribute. "compression" (type3 keyword): See the description of "compression" for the Print-Job operation in Section 3.2.1.1. "document-format" (mimeMediaType): See the description of "document-format" for the Print-Job operation in Section 3.2.1.1. "document-natural-language" (naturalLanguage): The client OPTIONALLY supplies this attribute. The Printer object OPTIONALLY supports this attribute. This attribute specifies the natural language of the document for those document-formats that require a specification of the natural language in order to image the document unambiguously. There are no particular values required for the Printer object to support.
ToP   noToC   RFC2911 - Page 65
      "last-document" (boolean):
        The client MUST supply this attribute.  The Printer object MUST
        support this attribute. It is a boolean flag that is set to
        'true' if this is the last document for the Job, 'false'
        otherwise.

   Group 2: Document Content

      The client MUST supply the document data if the "last-document"
      flag is set to 'false'.  However, since a client might not know
      that the previous document sent with a Send-Document (or Send-URI)
      operation was the last document (i.e., the "last-document"
      attribute was set to 'false'), it is legal to send a Send-Document
      request with no document data where the "last-document" flag is
      set to 'true'.  Such a request MUST NOT increment the value of the
      Job object's "number-of-documents" attribute, since no real
      document was added to the job.  It is not an error for a client to
      submit a job with no actual document data, i.e., only a single
      Create-Job and Send-Document request with a "last-document"
      operation attribute set to 'true' with no document data.

3.3.1.2 Send-Document Response
The following sets of attributes are part of the Send-Document 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 sections 13 and 3.1.6. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. Group 3: Job Object Attributes This is the same set of attributes as described in the Print-Job response (see section 3.2.1.2).


(next page on part 4)

Next Section