Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8011

Internet Printing Protocol/1.1: Model and Semantics

Pages: 221
Internet Standard: 92
Errata
Obsoletes:  291133813382
Part 4 of 12 – Pages 50 to 73
First   Prev   Next

Top   ToC   RFC8011 - Page 50   prevText

4.2. Printer Operations

All Printer operations are directed at Printers. A Client MUST always supply the "printer-uri" operation attribute in order to identify the correct target of the operation.
Top   ToC   RFC8011 - Page 51

4.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 Appendix C for the suggested steps for processing Job Creation requests and their operation and Job Template attributes.
4.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 4.1.4.1. The Printer MUST copy these values to the corresponding Job Status attributes described in Sections 5.3.19 and 5.3.20. Target: The "printer-uri" (uri) operation attribute, which is the target for this operation as described in Section 4.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the Client as described in Section 9.3. "job-name" (name(MAX)): The Client MAY supply and the Printer 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. 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 (see Section 5.3.5).
Top   ToC   RFC8011 - Page 52
      "ipp-attribute-fidelity" (boolean):

         The Client MAY supply and the Printer MUST support this
         attribute.  The value 'true' indicates that total fidelity to
         Client-supplied Job Template attributes and values is required;
         otherwise, the Printer MUST reject the Print-Job request.  The
         value 'false' indicates that a reasonable attempt to print the
         Job is acceptable and the Printer MUST accept the Print-Job
         request.  If not supplied, the Printer assumes that the value
         is 'false'.  All Printers MUST support both types of Job
         processing.  See Appendix C for a full description of
         "ipp-attribute-fidelity" and its relationship to other
         attributes, especially the Printer's "pdl-override-supported"
         attribute.

      "document-name" (name(MAX)):

         The Client MAY supply and the Printer 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 the following: 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.

      "compression" (type2 keyword):

         The Client MAY supply and the Printer MUST support this
         attribute.  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 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, i.e., the value is not one of the
             values of the Printer's "compression-supported" attribute,
             the Printer MUST reject the request and return the
             'client-error-compression-not-supported' status-code.  See
             Section 4.1.7 for details on returning unsupported
             attributes and values.
Top   ToC   RFC8011 - Page 53
         c.  If the Client supplies the attribute and the Printer
             supports the attribute value, the Printer uses the
             corresponding decompression algorithm on the Document data.

         d.  If the decompression algorithm fails before the Printer
             returns an operation response, the Printer 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 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 the
             "document-format" operation attribute definition below).

      "document-format" (mimeMediaType):

         The Client MAY supply and the Printer MUST support this
         attribute.  The value identifies the format of the supplied
         Document data.  The following cases exist:

         a.  If the Client does not supply this attribute, the Printer
             assumes that the Document data is in the format defined by
             the Printer'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, i.e., the value is not one of the
             values of the Printer's "document-format-supported"
             attribute, the Printer 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 5.1.10.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.
Top   ToC   RFC8011 - Page 54
         d.  If the Client supplies this attribute and the value is
             supported by the Printer, the Printer is capable of
             interpreting the Document data.

         e.  If interpretation of the Document data fails before the
             Printer returns an operation response, the Printer MUST
             reject the request and return the
             'client-error-document-format-error' status-code.

         f.  If interpretation of the Document data fails after the
             Printer returns an operation response, the Printer 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 MAY supply and the Printer SHOULD support this
         attribute.  The value specifies the natural language of the
         Document content for those Document formats that require a
         specification of the natural language in order to properly
         image the Document.

      "job-k-octets" (integer(0:MAX)):

         The Client MAY supply and the Printer SHOULD support this
         attribute.  The Client-supplied "job-k-octets" operation
         attribute identifies the total size of the Document(s) in
         K octets being submitted (see Section 5.3.17.1 for the complete
         semantics).  If the Client supplies the attribute and the
         Printer supports the attribute, the value of the attribute is
         used to populate the Job'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 does not support the
         attribute, the Printer 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's "xxx-supported" attribute, the Printer
         MUST use the value to populate the Job'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's "xxx-supported" attribute, the Printer
         MUST copy the attribute and its value to the Unsupported
         Attributes 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 SHOULD
Top   ToC   RFC8011 - Page 55
         populate the corresponding Job attribute if it supports the
         attribute and is able to calculate or discern the correct
         value.

      "job-impressions" (integer(0:MAX)):

         The Client MAY supply and the Printer SHOULD support this
         attribute.  The Client-supplied "job-impressions" operation
         attribute identifies the total size in number of Impressions of
         the Document(s) being submitted (see Section 5.3.17.2 for the
         complete semantics).

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

      "job-media-sheets" (integer(1:MAX)):

         The Client MAY supply and the Printer SHOULD support this
         attribute.  The Client-supplied "job-media-sheets" operation
         attribute identifies the total number of Media Sheets to be
         produced for this Job (see Section 5.3.17.3 for the complete
         semantics).

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

   Group 2: Job Template Attributes

      The Client MAY supply a set of Job Template attributes as defined
      in Section 5.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 MUST be able to
      accept an empty group.

   Group 3: Document Data

      The Client MUST supply the Document data to be processed.

   The simplest Print-Job request consists of just the
   "attributes-charset" and "attributes-natural-language" operation
   attributes, the "printer-uri" target operation attribute, and the
   Document data.  In this simple case, the Printer:

   o  creates a new Job containing a single Document,

   o  stores a generated Job name in the "job-name" attribute in the
      natural language and charset requested (see Section 4.1.4.1) (if
      those are supported; otherwise, using the Printer's default
      natural language and charset), and
Top   ToC   RFC8011 - Page 56
   o  at Job processing time, uses its corresponding default value
      attributes for the supported Job Template attributes that were not
      supplied by the Client as an IPP attribute or embedded
      instructions in the Document data.

4.2.1.2. Print-Job Response
The Printer MUST return to the Client the following sets of attributes as part of the Print-Job response: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in Section 4.1.4.2. Status Message: In addition to the REQUIRED status-code returned in every response, the response MAY include a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in Appendix B and Section 4.1.6. If the Client supplies unsupported or conflicting Job Template attributes or values, the Printer MUST reject or accept the Print-Job request, depending on whether the Client supplied a 'true' or 'false' value for the "ipp-attribute-fidelity" operation attribute. See the Implementor's Guides [RFC3196] [PWG5100.19] for guidance on processing Job Creation requests. Group 2: Unsupported Attributes See Section 4.1.7 for details on returning unsupported attributes. The value of "ipp-attribute-fidelity" supplied by the Client does not affect what attributes the Printer 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 can query the Job using the Get-Job-Attributes operation, requesting the unsupported attributes that were returned in the Print-Job response to see which attributes were ignored (not stored in the Job) and which attributes were stored with other (substituted) values.
Top   ToC   RFC8011 - Page 57
   Group 3: Job Attributes

      "job-id" (integer(1:MAX)):

         The Printer MUST return the Job's ID in the REQUIRED "job-id"
         Job 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.

      "job-uri" (uri):

         The Printer MUST return the Job's URI by returning the contents
         of the REQUIRED "job-uri" Job attribute.

      "job-state" (type1 enum):

         The Printer MUST return the Job's REQUIRED "job-state"
         attribute.  The value of this attribute along with the value of
         the "job-state-reasons" attribute is a "snapshot" of the new
         Job's state when the Printer returns the response.

      "job-state-reasons" (1setOf type2 keyword):

         The Printer MUST return the Job's REQUIRED "job-state-reasons"
         attribute.

      "job-state-message" (text(MAX)):

         The Printer SHOULD return the Job's RECOMMENDED
         "job-state-message" attribute.  If the Printer 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 query.

      "number-of-intervening-jobs" (integer(0:MAX)):

         The Printer SHOULD return the Job's RECOMMENDED
         "number-of-intervening-jobs" attribute.  If the Printer
         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 "number-of-intervening-jobs"
         attribute is not supported and will not be returned in a
         subsequent Job query.
Top   ToC   RFC8011 - Page 58
   Note: Since any Printer state information that 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 additional
   Printer Status attributes.

   Note: The simplest response consists of just the "attributes-charset"
   and "attributes-natural-language" operation attributes and the
   "job-uri", "job-id", and "job-state" Job attributes.  In this
   simplest case, the status-code is 'successful-ok' and there is no
   "status-message" or "detailed-status-message" operation attribute.

4.2.2. Print-URI Operation

This OPTIONAL operation is identical to the Print-Job operation (Section 4.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's "referenced-uri-scheme-supported" attribute, the Printer MUST reject the request and return the 'client-error-uri-scheme-not-supported' status-code. The Printer MAY validate the accessibility of the Document as part of the operation, or subsequently. If the Printer discovers an accessibility problem before returning an operation response, it MUST reject the request and return 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 4.1.6.4). If the Printer discovers this Document accessibility problem after accepting the request and returning an operation response with one of the successful status-code values, the Printer MUST add the "document-access-error" value to the Job's "job-state-reasons" attribute and MAY populate the Job's "job-document-access-errors" Job Status attribute (see Section 5.3.11). See the Implementor's Guides [RFC3196] [PWG5100.19] for guidance on processing Job Creation requests. If the Printer supports this operation, it MUST support the "reference-uri-schemes-supported" Printer attribute (see Section 5.4.27). It is up to the Printer to interpret the URI and subsequently "pull" the Document data from the source referenced by the URI string.
Top   ToC   RFC8011 - Page 59

4.2.3. Validate-Job Operation

This REQUIRED operation is similar to the Print-Job operation (Section 4.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. This operation is used only to verify the capabilities of a Printer 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 Job Creation request (with the Document data) would be accepted. The Validate-Job operation also performs the same security negotiation as the Print-Job, Print-URI, and Create-Job operations (see Section 9) so that a Client can check that the Client and Printer security requirements can be met before performing a Job Creation request. 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 returns the same status-code values, Operation Attributes (Group 1), and Unsupported Attributes (Group 2) as the Print-Job operation. However, no Job Attributes (Group 3) are returned, since no Job is created.

4.2.4. Create-Job Operation

This RECOMMENDED operation is similar to the Print-Job operation (Section 4.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 MAY supply the "document-name", "document-format", and "document-natural-language" attributes for each Document in the Job. If a Printer supports the Create-Job operation, it MUST also support the Send-Document operation. If the Printer supports the Create-Job and Print-URI operations, it MUST also support the Send-URI operation. If the Printer supports this operation, it MUST support the "multiple-operation-time-out" Printer attribute (see Section 5.4.31).
Top   ToC   RFC8011 - Page 60
   If the Printer supports this operation, then it MUST support the
   "multiple-document-jobs-supported" Printer Description attribute
   (see Section 5.4.16) and indicate whether it supports multiple
   Documents in a Job.

   If the Printer supports this operation and supports multiple
   Documents in a Job, then it MUST support the
   "multiple-document-handling" Job Template attribute with at least
   one value (see Section 5.2.4), and the associated
   "multiple-document-handling-default" and
   "multiple-document-handling-supported" Printer attributes
   (see Section 5.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
   operation, even though no Document data has arrived.  A Printer MAY
   set the 'job-data-insufficient' value of the Job's
   "job-state-reasons" 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 can set "job-state" to
   'processing', even though there is not yet any data to process.
   See Sections 5.3.7 and 5.3.8.

4.2.5. Get-Printer-Attributes Operation

This REQUIRED operation allows a Client to request the values of the attributes of a Printer. 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 returns a corresponding attribute set with the appropriate attribute values filled in. For Printers, the possible names of attribute groups are: o 'job-template': the subset of the Job Template attributes that apply to a Printer (the last two columns of Table 8 in Section 5.2) that the implementation supports for Printers. o 'printer-description': the subset of the attributes specified in Section 5.4 that the implementation supports for Printers. o 'all': the special group 'all' that includes all attributes that the implementation supports for Printers. Since a Client MAY request specific attributes or named groups, there is a potential for some overlap. For example, if a Client requests 'printer-name' and 'all', the Client is actually requesting the
Top   ToC   RFC8011 - Page 61
   "printer-name" attribute twice: once by naming it explicitly, and
   once by inclusion in the 'all' group.  In such cases, the Printer
   returns 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.

   Printers MUST support all group names and MUST return all supported
   attributes belonging to the group.

4.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 4.1.4.1. Target: The "printer-uri" (uri) operation attribute, which is the target for this operation as described in Section 4.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the Client as described in Section 9.3. "requested-attributes" (1setOf keyword): The Client MAY supply a set of attribute names and/or attribute group names in whose values the requester is interested. The Printer 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 MAY supply and the Printer MUST support this attribute. It is useful for a Client to determine the set of supported attribute values that relate to the requested Document format. The Printer MUST return the attributes and values that it uses to validate a Job in a Job Creation or Validate-Job operation in which this Document format is supplied. The Printer SHOULD return only (1) those attributes
Top   ToC   RFC8011 - Page 62
         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 to eliminate the attributes and values that are not
         supported for a specific Document format.  For example, a
         Printer might have multiple interpreters to support both
         'application/postscript' (for PostScript) and 'text/plain' (for
         text) Documents.  However, only one of those interpreters might
         support the "number-up" Job Template attribute with values of
         '1', '2', and '4'.  The other interpreter might only be able to
         support the "number-up" Job Template attribute 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 Job Creation request.

         If the Printer does not distinguish between different sets of
         supported values for each different Document format when
         validating Jobs in the Create-Job, Print-Job, Print-URI, and
         Validate-Job operations, it MUST NOT distinguish between
         different Document formats in the Get-Printer-Attributes
         operation.  If the Printer 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 attributes:

         +  Printer attributes that are Job Template attributes
            ("xxx-default", "xxx-supported", and "xxx-ready")
            (see Table 8 in Section 5.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"
Top   ToC   RFC8011 - Page 63
         The values of all other Printer attributes (including
         "document-format-supported") remain invariant with respect to
         the Client-supplied Document format (except for new Printer
         Description attributes as registered according to Section 7.2).

         If the Client omits this "document-format" operation attribute,
         the Printer MUST respond as if the attribute had been supplied
         with the value of the Printer's "document-format-default"
         attribute.  Clients SHOULD always supply a value for
         "document-format", since the Printer's
         "document-format-default" value can 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 5.1.10.

         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's
         "document-format-supported" attribute, the Printer MUST reject
         the operation and return the
         'client-error-document-format-not-supported' status-code.

4.2.5.2. Get-Printer-Attributes Response
The Printer returns the following sets of attributes as part of the Get-Printer-Attributes response: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in Section 4.1.4.2. Status Message: In addition to the REQUIRED status-code returned in every response, the response MAY include a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in Appendix B and Section 4.1.6.
Top   ToC   RFC8011 - Page 64
   Group 2: Unsupported Attributes

      See Section 4.1.7 for details on returning unsupported attributes.

      The response MAY contain the "requested-attributes" operation
      attribute with any supplied values (attribute keywords) that were
      requested by the Client but are not supported by the Printer.  If
      the Printer 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 this document but not
      supported by the implementation.

   Group 3: Printer Attributes

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

4.2.6. Get-Jobs Operation

This REQUIRED operation allows a Client to retrieve the list of Jobs belonging to the target Printer. The Client can also supply a list of Job attribute names and/or attribute group names. A group of Job attributes will be returned for each Job 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 Job.
Top   ToC   RFC8011 - Page 65
4.2.6.1. Get-Jobs Request
The Client submits the Get-Jobs request to a Printer. 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 4.1.4.1. Target: The "printer-uri" (uri) operation attribute, which is the target for this operation as described in Section 4.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the Client as described in Section 9.3. "limit" (integer(1:MAX)): The Client MAY supply and the Printer 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" (described below) 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. If the Client does not supply this attribute, the Printer responds with all applicable Jobs. "requested-attributes" (1setOf type2 keyword): The Client MAY supply and the Printer MUST support this attribute. It is a set of Job attribute names and/or attribute group names in whose values the requester is interested. This set of attributes is returned for each Job that is returned. The allowed attribute group names are the same as those defined in the Get-Job-Attributes operation in Section 4.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".
Top   ToC   RFC8011 - Page 66
      "which-jobs" (type2 keyword):

         The Client MAY supply and the Printer MUST support this
         attribute.  It indicates which Jobs MUST be returned by the
         Printer.  The values for this attribute include:

         +  'completed': Any Job whose state is 'completed', 'canceled',
            or 'aborted'.

         +  'not-completed': Any Job whose state is 'pending',
            'processing', 'processing-stopped', or 'pending-held'.

         A Printer 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 that is not supported by
         the Printer, the Printer MUST copy the attribute and the
         unsupported value to the Unsupported Attributes group, reject
         the request, and return the
         'client-error-attributes-or-values-not-supported' status-code.

         If the Client does not supply this attribute, the Printer MUST
         respond as if the Client had supplied the attribute with a
         value of 'not-completed'.

      "my-jobs" (boolean):

         The Client MAY supply and the Printer 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.
         If the Client does not supply this attribute, the Printer MUST
         respond as if the Client had supplied the attribute with a
         value of 'false', i.e., Jobs from all users.  The means for
         authenticating the requesting user and matching the Jobs is
         described in Section 9.

4.2.6.2. Get-Jobs Response
The Printer returns all of the Jobs 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 Jobs are returned, since there can literally be no Jobs at the Printer or there can be no Jobs that match the criteria supplied by the Client. If the Client requests any Job attributes at all, there is a set of Job Attributes returned for each Job.
Top   ToC   RFC8011 - Page 67
   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 one 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

      Natural Language and Character Set:

         The "attributes-charset" and "attributes-natural-language"
         attributes as described in Section 4.1.4.2.

      Status Message:

         In addition to the REQUIRED status-code returned in every
         response, the response MAY include a "status-message"
         (text(255)) and/or a "detailed-status-message" (text(MAX))
         operation attribute as described in Appendix B and
         Section 4.1.6.

   Group 2: Unsupported Attributes

      See Section 4.1.7 for details on returning unsupported attributes.

      The response MAY contain the "requested-attributes" operation
      attribute with any supplied values (attribute keywords) that were
      requested by the Client but are not supported by the Printer.  If
      the Printer 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 this document but not
      supported by the implementation.

   Groups 3 to N: Job Attributes

      The Printer responds with one set of Job Attributes for each
      returned Job.  The Printer ignores (does not respond with) any
      requested attribute or value that is not supported or that 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 9).  However, the
      Printer MUST respond with the 'unknown' value for any supported
      attribute (including all REQUIRED attributes) for which the
      Printer 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 5.1.
Top   ToC   RFC8011 - Page 68
      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).

4.2.7. Pause-Printer Operation

This OPTIONAL operation allows a Client to stop the Printer 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 (1) stopped as soon as the implementation permits or (2) completed, depending on implementation. The Printer MUST still accept Job Creation requests 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 or devices that were in the 'processing' or 'processing-stopped' state 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's "printer-state-reasons" attribute (see Section 5.4.12). When the device or devices have all stopped, the IPP Printer transitions the Printer to the 'stopped' state; removes the 'moving-to-paused' value, if present; and adds the 'paused' value to the Printer's "printer-state-reasons" attribute. When the current Job or Jobs complete that were in the 'processing' state, the IPP Printer transitions them to the 'completed' state. When the current Job or Jobs 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 Jobs' "job-state-reasons" attribute.
Top   ToC   RFC8011 - Page 69
   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 MAY update those Jobs'
   "job-state-reasons" values when those Jobs are queried (so-called
   "lazy evaluation").

   The IPP Printer MUST accept the request in any state and transition
   the Printer to the indicated new "printer-state" before returning, as
   shown in Table 2.

   Access Rights: The authenticated user (see Section 9.3) performing
   this operation MUST be an Operator or Administrator of the Printer
   (see Sections 1 and 9.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.
Top   ToC   RFC8011 - Page 70
   +--------------+--------------+-----------------+-------------------+
   | Current      | New          | "printer-state- | IPP Printer's     |
   | "printer-    | "printer-    | reasons"        | response status-  |
   | state"       | state"       |                 | code and action:  |
   +--------------+--------------+-----------------+-------------------+
   | 'idle'       | 'stopped'    | 'paused'        | 'successful-ok'   |
   +--------------+--------------+-----------------+-------------------+
   | 'processing' | 'processing' | 'moving-to-     | Option 1:         |
   |              |              | paused'         | 'successful-ok';  |
   |              |              |                 | Later, when all   |
   |              |              |                 | output has        |
   |              |              |                 | 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'   |
   +--------------+--------------+-----------------+-------------------+

                 Table 2: Pause-Printer State Transitions
Top   ToC   RFC8011 - Page 71
4.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 4.1.4.1. Target: The "printer-uri" (uri) operation attribute, which is the target for this operation as described in Section 4.1.5. Requesting User Name: The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied by the Client as described in Section 9.3.
4.2.7.2. Pause-Printer Response
The following groups of attributes are part of the Pause-Printer response: Group 1: Operation Attributes Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in Section 4.1.4.2. Status Message: In addition to the REQUIRED status-code returned in every response, the response MAY include a "status-message" (text(255)) and/or a "detailed-status-message" (text(MAX)) operation attribute as described in Appendix B and Section 4.1.6. Group 2: Unsupported Attributes See Section 4.1.7 for details on returning unsupported attributes.
Top   ToC   RFC8011 - Page 72

4.2.8. Resume-Printer Operation

This OPTIONAL operation allows a Client to resume the Printer scheduling Jobs on all its devices. The Printer MUST remove the 'paused' and 'moving-to-paused' values from the Printer's "printer-state-reasons" attribute, if present. If there are no other reasons to keep a device paused (such as a media jam), the IPP Printer is free to transition itself to the 'processing' or 'idle' state, depending on whether there are Jobs to be processed or not, respectively, and the device(s) resumes 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 and transition the Printer to the indicated new state as shown in Table 3. Access Rights: The authenticated user (see Section 9.3) performing this operation MUST be an Operator or Administrator of the Printer (see Sections 1 and 9.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 4.2.7.1 and 4.2.7.2). +-----------------+-----------------+-------------------------------+ | Current | New "printer- | IPP Printer's response | | "printer-state" | state" | status-code and action: | +-----------------+-----------------+-------------------------------+ | '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 | +-----------------+-----------------+-------------------------------+ Table 3: Resume-Printer State Transitions
Top   ToC   RFC8011 - Page 73

4.2.9. Purge-Jobs Operation

This DEPRECATED operation allows a Client to remove all Jobs from a Printer, regardless of their Job states, including Jobs in the Printer's Job History (see Section 5.3.7.2). After a Purge-Jobs operation has been performed, a Printer MUST return no Jobs in subsequent Get-Job-Attributes and Get-Jobs responses (until new Jobs are submitted). Note: This operation SHOULD NOT be supported in new implementations, since it destroys Printer accounting information. Whether the Purge-Jobs (and Get-Jobs) operation affects Jobs that were submitted to the device from sources other than the IPP Printer in the same way that the Purge-Jobs operation affects Jobs that were submitted to the IPP Printer using IPP depends on implementation, i.e., on whether IPP 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. If this OPTIONAL operation is supported, the Printer MUST accept this operation in any state and transition the Printer to the 'idle' state. Access Rights: The authenticated user (see Section 9.3) performing this operation MUST be an Operator or Administrator of the Printer (see Sections 1 and 9.5). Otherwise, the Printer 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 4.2.7.1 and 4.2.7.2).


(page 73 continued on part 5)

Next Section