RFC 8011
Internet Printing Protocol/1.1: Model and Semantics
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.
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).
"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.
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.
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
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
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.
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.
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.
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).
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
"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
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"
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.
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.
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".
"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.
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.
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.
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.
+--------------+--------------+-----------------+-------------------+ | 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
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.
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
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)
