RFC2566 - Internet Printing Protocol/1.0: Model and Semantics(2)
In all cases, the target URIs contained within the body of IPP
operation requests and responses must be in absolute format rather
than relative format (a relative URL identifies a resource with the
scope of the HTTP server, but does not include scheme, host or port).
The following rules apply to the use of port numbers in URIs that
identify IPP objects:
1. If the URI scheme allows the port number to be explicitly
included in the URI string, and a port number is specified
within the URI, then that port number MUST be used by the client
to contact the IPP object.
2. If the URI scheme allows the port number to be explicitly
included in the URI string, and a port number is not specified
within the URI, then default port number implied by that URI
scheme MUST be used by the client to contact the IPP object.
3. If the URI scheme does not allow an explicit port number to be
specified within the URI, then the default port number implied
by that URI MUST be used by the client to contact the IPP
object.
Note: The IPP encoding and transport document [RFC2565] shows a
mapping of IPP onto HTTP/1.1 and defines a new default port number
for using IPP over HTTP/1.1.
3.1.6 Operation Status Codes and Messages
Every operation response includes a REQUIRED "status-code" parameter
and an OPTIONAL "status-message" operation attribute. The "status-
code" provides information on the processing of a request. A
"status-message" attribute provides a short textual description of
the status of the operation. The status code is intended for use by
automata, and the status message is intended for the human end user.
If a response does include a "status-message" attribute, an IPP
client NEED NOT examine or display the message, however it SHOULD do
so in some implementation specific manner.
The "status-code" value is a numeric value that has semantic meaning.
The "status-code" syntax is similar to a "type2 enum" (see section
4.1 on "Attribute Syntaxes") except that values can range only from
0x0000 to 0x7FFF. Section 13 describes the status codes, assigns the
numeric values, and suggests a corresponding status message for each
status code. The "status-message" attribute's syntax is "text(255)".
A client implementation of IPP SHOULD convert status code values into
any localized message that has semantic meaning to the end user.
If the Printer object supports the "status-message" operation
attribute, the Printer object MUST be able to generate this message
in any of the natural languages identified by the Printer object's
"generated-natural-language-supported" attribute (see the
"attributes-natural-language" operation attribute specified in
section 3.1.4.1). As described in section 3.1.4.1 for any returned '
text' attribute, if there is a choice for generating this message,
the Printer object uses the natural language indicated by the value
of the "attributes-natural-language" in the client request if
supported, otherwise the Printer object uses the value in the Printer
object's own "natural-language-configured" attribute. If the Printer
object supports the "status-message" operation attribute, it SHOULD
use the REQUIRED 'utf-8' charset to return a status message for the
following error status codes (see section 13): 'client-error-bad-
request', 'client-error-charset-not-supported', 'server-error-
internal-error', 'server-error-operation-not-supported', and '
server-error-version-not-supported'. In this case, it MUST set the
value of the "attributes-charset" operation attribute to 'utf-8' in
the error response.
3.1.7 Versions
Each operation request and response carries with it a "version-
number" parameter. Each value of the "version-number" is in the form
"X.Y" where X is the major version number and Y is the minor version
number. By including a version number in the client request, it
allows the client to identify which version of IPP it is interested
in using. If the IPP object does not support that version, the
object responds with a status code of 'server-error-version-not-
supported' along with the closest version number that is supported
(see section 13.1.5.4).
There is no version negotiation per se. However, if after receiving
a 'server-error-version-not-supported' status code from an IPP
object, there is nothing that prevents a client from trying again
with a different version number. In order to conform to IPP/1.0, an
implementation MUST support at least version '1.0'.
There is only one notion of "version number" that covers both IPP
Model and IPP Protocol changes. Thus the version number MUST change
when introducing a new version of the Model and Semantics document
[RFC2566] or a new version of the Encoding and Transport document
[RFC2565].
Changes to the major version number indicate structural or syntactic
changes that make it impossible for older version of IPP clients and
Printer objects to correctly parse and process the new or changed
attributes, operations and responses. If the major version number
changes, the minor version numbers is set to zero. As an example,
adding the "ipp-attribute-fidelity" attribute (if it had not been
part of version '1.0'), would have required a change to the major
version number. Items that might affect the changing of the major
version number include any changes to the Model and Semantics
document [RFC2566] or the Encoding and Transport [RFC2565] itself,
such as:
- reordering of ordered attributes or attribute sets
- changes to the syntax of existing attributes
- changing Operation or Job Template attributes from OPTIONAL to
REQUIRED and vice versa
- adding REQUIRED (for an IPP object to support) operation
attributes
- adding REQUIRED (for an IPP object to support) operation
attribute groups
- adding values to existing operation attributes
- adding REQUIRED operations
Changes to the minor version number indicate the addition of new
features, attributes and attribute values that may not be understood
by all IPP objects, but which can be ignored if not understood.
Items that might affect the changing of the minor version number
include any changes to the model objects and attributes but not the
encoding and transport rules [RFC2565] (except adding attribute
syntaxes). Examples of such changes are:
- grouping all extensions not included in a previous version into
a new version
- adding new attribute values
- adding new object attributes
- adding OPTIONAL (for an IPP object to support) operation
attributes (i.e., those attributes that an IPP object can ignore
without confusing clients)
- adding OPTIONAL (for an IPP object to support) operation
attribute groups (i.e., those attributes that an IPP object can
ignore without confusing clients)
- adding new attribute syntaxes
- adding OPTIONAL operations
- changing Job Description attributes or Printer Description
attributes from OPTIONAL to REQUIRED or vice versa.
The encoding of the "operation-id", the "version-number", the
"status-code", and the "request-id" MUST NOT change over any version
number (either major or minor). This rule guarantees that all future
versions will be backwards compatible with all previous versions (at
least for checking the "operation-id", the "version-number", and the
"request-id"). In addition, any protocol elements (attributes, error
codes, tags, etc.) that are not carried forward from one version to
the next are deprecated so that they can never be reused with new
semantics.
Implementations that support a certain major version NEED NOT support
ALL previous versions. As each new major version is defined (through
the release of a new specification), that major version will specify
which previous major versions MUST be supported in compliant
implementations.
3.1.8 Job Creation Operations
In order to "submit a print job" and create a new Job object, a
client issues a create request. A create request is any one of
following three operation requests:
- The Print-Job Request: A client that wants to submit a print job
with only a single document uses the Print-Job operation. The
operation allows for the client to "push" the document data to
the Printer object by including the document data in the request
itself.
- The Print-URI Request: A client that wants to submit a print job
with only a single document (where the Printer object "pulls" the
document data instead of the client "pushing" the data to the
Printer object) uses the Print-URI operation. In this case, the
client includes in the request only a URI reference to the
document data (not the document data itself).
- The Create-Job Request: A client that wants to submit a print job
with multiple documents uses the Create-Job operation. This
operation is followed by an arbitrary number of Send-Document
and/or Send-URI operations (each creating another document for
the newly create Job object). The Send-Document operation
includes the document data in the request (the client "pushes"
the document data to the printer), and the Send-URI operation
includes only a URI reference to the document data in the request
(the Printer "pulls" the document data from the referenced
location). The last Send-Document or Send-URI request for a
given Job object includes a "last-document" operation attribute
set to 'true' indicating that this is the last request.
Throughout this model specification, the term "create request" is
used to refer to any of these three operation requests.
A Create-Job operation followed by only one Send-Document operation
is semantically equivalent to a Print-Job operation, however, for
performance reasons, the client SHOULD use the Print-Job operation
for all single document jobs. Also, Print-Job is a REQUIRED
operation (all implementations MUST support it) whereas Create-Job is
an OPTIONAL operation, hence some implementations might not support
it.
Job submission time is the point in time when a client issues a
create request. The initial state of every Job object is the '
pending' or 'pending-held' state. Later, the Printer object begins
processing the print job. At this point in time, the Job object's
state moves to 'processing'. This is known as job processing time.
There are validation checks that must be done at job submission time
and others that must be performed at job processing time.
At job submission time and at the time a Validate-Job operation is
received, the Printer MUST do the following:
1. Process the client supplied attributes and either accept or
reject the request
2. Validate the syntax of and support for the scheme of any client
supplied URI
At job submission time the Printer object MUST validate whether or
not the supplied attributes, attribute syntaxes, and values are
supported by matching them with the Printer object's corresponding
"xxx-supported" attributes. See section 3.2.1.2 for details. [ipp-
iig] presents suggested steps for an IPP object to either accept or
reject any request and additional steps for processing create
requests.
At job submission time the Printer object NEED NOT perform the
validation checks reserved for job processing time such as:
1. Validating the document data
2. Validating the actual contents of any client supplied URI
(resolve the reference and follow the link to the document data)
At job submission time, these additional job processing time
validation checks are essentially useless, since they require
actually parsing and interpreting the document data, are not
guaranteed to be 100% accurate, and MUST be done, yet again, at job
processing time. Also, in the case of a URI, checking for
availability at job submission time does not guarantee availability
at job processing time. In addition, at job processing time, the
Printer object might discover any of the following conditions that
were not detectable at job submission time:
- runtime errors in the document data,
- nested document data that is in an unsupported format,
- the URI reference is no longer valid (i.e., the server hosting
the document might be down), or
- any other job processing error
At job processing time, since the Printer object has already
responded with a successful status code in the response to the create
request, if the Printer object detects an error, the Printer object
is unable to inform the end user of the error with an operation
status code. In this case, the Printer, depending on the error, can
set the "job-state", "job-state-reasons", or "job-state-message"
attributes to the appropriate value(s) so that later queries can
report the correct job status.
Note: Asynchronous notification of events is outside the scope of
IPP/1.0.
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.23 and 4.3.24.
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.0 does not
support the concept of document level attributes.
"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. 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. 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.
"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.
"compression" (type3 keyword)
The client OPTIONALLY supplies this attribute. The Printer
object OPTIONALLY supports this attribute and the "compression-
supported" attribute (see section 4.4.29). The client supplied
"compression" operation attribute identifies the compression
algorithm used on the document data. If the client omits this
attribute, the Printer object MUST assume that the data is not
compressed. If the client supplies the attribute and the
Printer object supports the attribute, the Printer object uses
the corresponding decompression algorithm on the document data.
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 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.
"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.30). 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 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.
Note: 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.31). 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.18 for the complete semantics).
See note 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.32). 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.19 for the complete semantics).
See note 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.
Note: 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) operation attribute as described in sections 14 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
This is a set of Operation and Job Template attributes supplied
by the client (in the request) that are not supported by the
Printer object or that conflict with one another (see the
Implementer's Guide [ipp-iig]). If the Printer object is not
returning any Unsupported Attributes in the response, the
Printer object SHOULD omit Group 2 rather than sending an empty
group. However, a client MUST be able to accept an empty group.
Unsupported attributes fall into three categories:
1. The Printer object does not support the supplied attribute
(no matter what the attribute syntax or value).
2. The Printer object does support the attribute, but does not
support some or all of the particular attribute syntaxes or
values supplied by the client (i.e., the Printer object does
not have those attribute syntaxes or values in its
corresponding "xxx-supported" attribute).
3. The Printer object does support the attributes and values
supplied, but the particular values are in conflict with one
another, because they violate a constraint, such as not being
able to staple transparencies.
In the case of an unsupported attribute name, the Printer object
returns the client-supplied attribute with a substituted "out-
of-band" value of 'unsupported' indicating no support for the
attribute itself (see the beginning of section 4.1).
In the case of a supported attribute with one or more
unsupported attribute syntaxes or values, the Printer object
simply returns the client-supplied attribute with the
unsupported attribute syntaxes or values as supplied by the
client. This indicates support for the attribute, but no
support for that particular attribute syntax or value. If the
client supplies a multi-valued attribute with more than one
value and the Printer object supports the attribute but only
supports a subset of the client-supplied attribute syntaxes or
values, the Printer object MUST return only those attribute
syntaxes or values that are unsupported.
In the case of two (or more) supported attribute values that are
in conflict with one another (although each is supported
independently, the values conflict when requested together
within the same job), the Printer object MUST return all the
values that it ignores or substitutes to resolve the conflict,
but not any of the values that it is still using. The choice
for exactly how to resolve the conflict is implementation
dependent. See The Implementer's Guide [ipp-iig] for an
example.
In these three cases, the value of the "ipp-attribute-fidelity"
supplied by the client does not affect what the Printer object
returns. 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":
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":
The Printer object OPTIONALLY returns the Job object's OPTIONAL
"job-state-reasons" 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-reasons" attribute is not supported
and will not be returned in a subsequent Job object query.
"job-state-message":
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":
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" 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. See The Implementer's Guide
[ipp-iig] for suggested additional checks. The Printer NEED NOT
follow the reference and validate the contents of the reference.
If the Printer object supports this operation, it MUST support the
"reference-uri-schemes-supported" Printer attribute (see section
4.4.24).
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.
Note: 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.28).
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': all of the Job Template attributes that apply to
a Printer object (the last two columns of the table in Section
4.2).
- 'printer-description': the attributes specified in Section 4.4.
- 'all': the special group 'all' that includes all supported
attributes.
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:
attributes-charset" and "attributes-natural-language" butes 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) operation attribute as described in section 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
This is a set of Operation attributes supplied by the client (in
the request) that are not supported by the Printer object or
that conflict with one another (see sections 3.2.1.2 and 16).
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 is not
returning any Unsupported Attributes in the response, the
Printer object SHOULD omit Group 2 rather than sending an empty
group. However, a client MUST be able to accept an empty group.
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 (see the description of Job attribute group names in
section 3.3.4).
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
indicates a limit to the number of Job objects 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 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
mentation does not keep jobs in the 'completed', 'canceled', '
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 all
jobs or just the jobs submitted by the requesting user of this
request MUST 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., all jobs. 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 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.
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) operation attribute as described in sections 14 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
This is a set of Operation attributes supplied by the client (in
the request) that are not supported by the Printer object or
that conflict with one another (see sections 3.2.1.2 and the
Implementer's Guide [ipp-iig]). 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
is not returning any Unsupported Attributes in the response, the
Printer object SHOULD omit Group 2 rather than sending an empty
group. However, a client MUST be able to accept an empty group.
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.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.
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 multiple document jobs, the Printer object MUST support the
"multiple-operation-time-out" attribute (see section 4.4.28). 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), if supported, 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), if supported.
This action allows the user or an operator to determine whether
to continue processing the Job by moving it back to the '
pending' state or to cancel the job.
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.
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:
"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
"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. 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. 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.
"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.
"compression" (type3 keyword)
The client OPTIONALLY supplies this attribute. The Printer
object OPTIONALLY supports this attribute and the "compression-
supported" attribute (see section 4.4.29). The client supplied
"compression" operation attribute identifies the compression
algorithm used on the document data. If the client omits this
attribute, the Printer object MUST assume that the data is not
compressed. If the client supplies the attribute and the
Printer object supports the attribute, the Printer object MUST
use the corresponding decompression algorithm on the document
data. 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 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.
"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.
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) operation attribute as described in sections 14 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
This is a set of Operation attributes supplied by the client (in
the request) that are not supported by the Printer object or
that conflict with one another (see sections 3.2.1.2 and the
Implementer's Guide [ipp-iig]). If the Printer object is not
returning any Unsupported Attributes in the response, the
Printer object SHOULD omit Group 2 rather than sending an empty
group. However, a client MUST be able to accept an empty group.
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).
3.3.2 Send-URI Operation
This OPTIONAL operation is identical to the Send-Document operation
(see section 3.3.1) except that a client MUST supply a URI reference
("document-uri" operation attribute) rather than the document data
itself. If a Printer object supports this operation, clients can use
both Send-URI or Send-Document operations to add new documents to an
existing multi-document Job object. However, if a client needs to
indicate that the previous Send-URI or Send-Document was the last
document, the client MUST use the Send-Document operation with no
document data and the "last-document" flag set to 'true' (rather than
using a Send-URI operation with no "document-uri" operation
attribute).
If a Printer object supports this operation, it MUST also support the
Print-URI operation (see section 3.2.2).
The Printer object MUST validate the syntax and URI scheme of the
supplied URI before returning a response, just as in the Print-URI
operation.
3.3.3 Cancel-Job Operation
This REQUIRED operation allows a client to cancel a Print Job from
the time the job is created up to the time it is completed, canceled,
or aborted. Since a Job might already be printing by the time a
Cancel-Job is received, some media sheet pages might be printed
before the job is actually terminated.
3.3.3.1 Cancel-Job Request
The following groups of attributes are part of the Cancel-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.
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.
"message" (text(127)):
The client OPTIONALLY supplies this attribute. The Printer
object OPTIONALLY supports this attribute. It is a message to
the operator. This "message" attribute is not the same as the
"job-message-from-operator" attribute. That attribute is used
to report a message from the operator to the end user that
queries that attribute. This "message" operation attribute is
used to send a message from the client to the operator along
with the operation request. It is an implementation decision of
how or where to display this message to the operator (if at
all).
3.3.3.2 Cancel-Job Response
The following sets of attributes are part of the Cancel-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) operation attribute as described in sections 14 and
3.1.6.
If the job is already in the 'completed', 'aborted', or '
canceled' state, or the 'process-to-stop-point' value is set in
the Job's "job-state-reasons" attribute, the Printer object MUST
reject the request and return the 'client-error-not-possible'
error status code.
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
This is a set of Operation attributes supplied by the client (in
the request) that are not supported by the Printer object or
that conflict with one another (see section 3.2.1.2 and the
Implementer's Guide [ipp-iig]). If the Printer object is not
returning any Unsupported Attributes in the response, the
Printer object SHOULD omit Group 2 rather than sending an empty
group. However, a client MUST be able to accept an empty group.
Once a successful response has been sent, the implementation
guarantees that the Job will eventually end up in the 'canceled'
state. Between the time of the Cancel-Job operation is accepted and
when the job enters the 'canceled' job-state (see section 4.3.7), the
"job-state-reasons" attribute SHOULD contain the 'processing-to-
stop-point' value which indicates to later queries that although the
Job might still be 'processing', it will eventually end up in the '
canceled' state, not the 'completed' state.
3.3.4 Get-Job-Attributes Operation
This REQUIRED operation allows a client to request the values of
attributes of a Job object and it is almost identical to the Get-
Printer-Attributes operation (see section 3.2.5). The only
differences are that the operation is directed at a Job object rather
than a Printer object, there is no "document-format" operation
attribute used when querying a Job object, and the returned attribute
group is a set of Job object attributes rather than a set of Printer
object attributes.
For Jobs, the possible names of attribute groups are:
- 'job-template': all of the Job Template attributes that apply to a
Job object (the first column of the table in Section 4.2).
- 'job-description': all of the Job Description attributes specified
in Section 4.3.
- 'all': the special group 'all' that includes all supported
attributes.
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, 'job-name' and 'job-description', the client is actually
requesting the "job-name" attribute once by naming it explicitly, and
once by inclusion in the 'job-description' group. In such cases, the
Printer object NEED NOT return the 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 Job object support all attributes belonging
to a group (since some attributes are OPTIONAL). However it is
REQUIRED that each Job object support all group names.
3.3.4.1 Get-Job-Attributes Request
The following groups of attributes are part of the Get-Job-Attributes
Request when the request is directed at a Job object:
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.