RFC 2911
Internet Printing Protocol/1.1: Model and Semantics
Pages: 224
Obsoletes: 2566
Obsoleted by: 8011
Updated by: 3380 3382 3996 3995 7472
Obsoletes: 2566
Obsoleted by: 8011
Updated by: 3380 3382 3996 3995 7472
Part 3 of 9 – Pages 41 to 65
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).
"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.
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.
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.
"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
- 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.
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
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.
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.
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.
- '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
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-
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.
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.
"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.
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.
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
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:
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.
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:
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.
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
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.
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.
"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)