RFC 2566
Internet Printing Protocol/1.0: Model and Semantics
3.1.4 Character Set and Natural Language Operation Attributes Some Job and Printer attributes have values that are text strings and names intended for human understanding rather than machine understanding (see the 'text' and 'name' attribute syntax descriptions in section 4.1). The following sections describe two special Operation Attributes called "attributes-charset" and "attributes-natural-language". These attributes are always part of the Operation Attributes group. For most attribute groups, the order of the attributes within the group is not important. However, for these two attributes within the Operation Attributes group, the order is critical. The "attributes-charset" attribute MUST be the first attribute in the group and the "attributes-natural-language" attribute MUST be the second attribute in the group. In other words, these attributes MUST be supplied in every IPP request and response, they MUST come first in the group, and MUST come in the specified order. For job creation operations, the IPP Printer implementation saves these two attributes with the new Job object as Job Description attributes. For the sake of brevity in this document, these operation attribute descriptions are not repeated with every operation request and response, but have a reference back to this section instead. 3.1.4.1 Request Operation Attributes The client MUST supply and the Printer object MUST support the following REQUIRED operation attributes in every IPP/1.0 operation request:
"attributes-charset" (charset):
This operation attribute identifies the charset (coded character
set and encoding method) used by any 'text' and 'name'
attributes that the client is supplying in this request. It
also identifies the charset that the Printer object MUST use (if
supported) for all 'text' and 'name' attributes and status
messages that the Printer object returns in the response to this
request. See Sections 4.1.1 and 4.1.2 for the specification of
the 'text' and 'name' attribute syntaxes.
All clients and IPP objects MUST support the 'utf-8' charset
[RFC2279] and MAY support additional charsets provided that they
are registered with IANA [IANA-CS]. If the Printer object does
not support the client supplied charset value, the Printer
object MUST reject the request, set the "attributes-charset" to
'utf-8' in the response, and return the 'client-error-charset-
not-supported' status code and any 'text' or 'name' attributes
using the 'utf-8' charset. The Printer object MUST indicate the
charset(s) supported as the values of the "charset-supported"
Printer attribute (see Section 4.4.15), so that the client can
query to determine which charset(s) are supported.
Note to client implementers: Since IPP objects are only required
to support the 'utf-8' charset, in order to maximize
interoperability with multiple IPP object implementations, a
client may want to supply 'utf-8' in the "attributes-charset"
operation attribute, even though the client is only passing and
able to present a simpler charset, such as US-ASCII or ISO-
8859-1. Then the client will have to filter out (or charset
convert) those characters that are returned in the response that
it cannot present to its user. On the other hand, if both the
client and the IPP objects also support a charset in common
besides utf-8, the client may want to use that charset in order
to avoid charset conversion or data loss.
See the 'charset' attribute syntax description in Section 4.1.7
for the syntax and semantic interpretation of the values of this
attribute and for example values.
"attributes-natural-language" (naturalLanguage):
This operation attribute identifies the natural language used by
any 'text' and 'name' attributes that the client is supplying in
this request. This attribute also identifies the natural
language that the Printer object SHOULD use for all 'text' and '
name' attributes and status messages that the Printer object
returns in the response to this request.
There are no REQUIRED natural languages required for the Printer
object to support. However, the Printer object's "generated-
natural-language-supported" attribute identifies the natural
languages supported by the Printer object and any contained Job
objects for all text strings generated by the IPP object. A
client MAY query this attribute to determine which natural
language(s) are supported for generated messages.
For any of the attributes for which the Printer object generates
text, i.e., for the "job-state-message", "printer-state-
message", and status messages (see Section 3.1.6), the Printer
object MUST be able to generate these text strings in any of its
supported natural languages. If the client requests a natural
language that is not supported, the Printer object MUST return
these generated messages in the Printer's configured natural
language as specified by the Printer's "natural-language-
configured" attribute" (see Section 4.4.16).
For other 'text' and 'name' attributes supplied by the client,
authentication system, operator, system administrator, or
manufacturer (i.e., for "job-originating-user-name", "printer-
name" (name), "printer-location" (text), "printer-info" (text),
and "printer-make-and-model" (text)), the Printer object is only
required to support the configured natural language of the
Printer identified by the Printer object's "natural-language-
configured" attribute, though support of additional natural
languages for these attributes is permitted.
For any 'text' or 'name' attribute in the request that is in a
different natural language than the value supplied in the
"attributes-natural-language" operation attribute, the client
MUST use the Natural Language Override mechanism (see sections
4.1.1.2 and 4.1.2.2) for each such attribute value supplied.
The client MAY use the Natural Language Override mechanism
redundantly, i.e., use it even when the value is in the same
natural language as the value supplied in the "attributes-
natural-language" operation attribute of the request.
The IPP object MUST accept any natural language and any Natural
Language Override, whether the IPP object supports that natural
language or not (and independent of the value of the "ipp-
attribute-fidelity" Operation attribute). That is the IPP
object accepts all client supplied values no matter what the
values are in the Printer object's "generated-natural-language-
supported" attribute. That attribute, "generated-natural-
language-supported", only applies to generated messages,
not client supplied messages. The IPP object MUST remember that
natural language for all client-supplied attributes, and when
returning those attributes in response to a query, the IPP
object MUST indicate that natural language.
Each value whose attribute syntax type is 'text' or 'name' (see
sections 4.1.1 and 4.1.2) has an Associated Natural-Language.
This document does not specify how this association is stored in
a Printer or Job object. When such a value is encoded in a
request or response, the natural language is either implicit or
explicit:
- In the implicit case, the value contains only the
text/name value, and the language is specified by the
"attributes-natural-language" operation attribute in the
request or response (see sections 4.1.1.1
textWithoutLanguage and 4.1.2.1 nameWithoutLanguage).
- In the explicit case (also known as the Natural-Language
Override case), the value contains both the language and
the text/name value (see sections 4.1.1.2
textWithLanguage and 4.1.2.2 nameWithLanguage).
For example, the "job-name" attribute MAY be supplied by the
client in a create request. The text value for this attribute
will be in the natural language identified by the "attribute-
natural-language" attribute, or if different, as identified by
the Natural Language Override mechanism. If supplied, the IPP
object will use the value of the "job-name" attribute to
populate the Job object's "job-name" attribute. Whenever any
client queries the Job object's "job-name" attribute, the IPP
object returns the attribute as stored and uses the Natural
Language Override mechanism to specify the natural language, if
it is different from that reported in the "attributes-natural-
language" operation attribute of the response. The IPP object
MAY use the Natural Language Override mechanism redundantly,
i.e., use it even when the value is in the same natural language
as the value supplied in the "attributes-natural-language"
operation attribute of the response.
An IPP object MUST NOT reject a request based on a supplied
natural language in an "attributes-natural-language" Operation
attribute or in any attribute that uses the Natural Language
Override.
See the 'naturalLanguage' attribute syntax description in
section 4.1.8 for the syntax and semantic interpretation of the
values of this attribute and for example values.
Clients SHOULD NOT supply 'text' or 'name' attributes that use an
illegal combination of natural language and charset. For example,
suppose a Printer object supports charsets 'utf-8', 'iso-8859-1', and
'iso-8859-7'. Suppose also, that it supports natural languages 'en'
(English), 'fr' (French), and 'el' (Greek). Although the Printer
object supports the charset 'iso-8859-1' and natural language 'el',
it probably does not support the combination of Greek text strings
using the 'iso-8859-1' charset. The Printer object handles this
apparent incompatibility differently depending on the context in
which it occurs:
- In a create request: If the client supplies a text or name
attribute (for example, the "job-name" operation attribute) that
uses an apparently incompatible combination, it is a client
choice that does not affect the Printer object or its correct
operation. Therefore, the Printer object simply accepts the
client supplied value, stores it with the Job object, and
responds back with the same combination whenever the client (or
any client) queries for that attribute.
- In a query-type operation, like Get-Printer-Attributes: If the
client requests an apparently incompatible combination, the
Printer object responds (as described in section 3.1.4.2) using
the Printer's configured natural language rather than the natural
language requested by the client.
In either case, the Printer object does not reject the request
because of the apparent incompatibility. The potential incompatible
combination of charset and natural language can occur either at the
global operation level or at the Natural Language Override
attribute-by-attribute level. In addition, since the response always
includes explicit charset and natural language information, there is
never any question or ambiguity in how the client interprets the
response.
3.1.4.2 Response Operation Attributes
The Printer object MUST supply and the client MUST support the
following REQUIRED operation attributes in every IPP/1.0 operation
response:
"attributes-charset" (charset):
This operation attribute identifies the charset used by any '
text' and 'name' attributes that the Printer object is returning
in this response. The value in this response MUST be the same
value as the "attributes-charset" operation attribute supplied
by the client in the request. If this is not possible
(i.e., the charset requested is not supported), the request
would have been rejected. See "attributes-charset" described in
Section 3.1.4.1 above.
If the Printer object supports more than just the 'utf-8'
charset, the Printer object MUST be able to code convert between
each of the charsets supported on a highest fidelity possible
basis in order to return the 'text' and 'name' attributes in the
charset requested by the client. However, some information loss
MAY occur during the charset conversion depending on the
charsets involved. For example, the Printer object may convert
from a UTF-8 'a' to a US-ASCII 'a' (with no loss of
information), from an ISO Latin 1 CAPITAL LETTER A WITH ACUTE
ACCENT to US-ASCII 'A' (losing the accent), or from a UTF-8
Japanese Kanji character to some ISO Latin 1 error character
indication such as '?', decimal code equivalent, or to the
absence of a character, depending on implementation.
Note: Whether an implementation that supports more than one
charset stores the data in the charset supplied by the client or
code converts to one of the other supported charsets, depends on
implementation. The strategy should try to minimize loss of
information during code conversion. On each response, such an
implementation converts from its internal charset to that
requested.
"attributes-natural-language" (naturalLanguage):
This operation attribute identifies the natural language used by
any 'text' and 'name' attributes that the IPP object is
returning in this response. Unlike the "attributes-charset"
operation attribute, the IPP object NEED NOT return the same
value as that supplied by the client in the request. The IPP
object MAY return the natural language of the Job object or the
Printer's configured natural language as identified by the
Printer object's "natural-language-configured" attribute, rather
than the natural language supplied by the client. For any '
text' or 'name' attribute or status message in the response that
is in a different natural language than the value returned in
the "attributes-natural-language" operation attribute, the IPP
object MUST use the Natural Language Override mechanism (see
sections 4.1.1.2 and 4.1.2.2) on each attribute value returned.
The IPP object MAY use the Natural Language Override mechanism
redundantly, i.e., use it even when the value is in the same
natural language as the value supplied in the "attributes-
natural-language" operation attribute of the response.
3.1.5 Operation Targets All IPP operations are directed at IPP objects. For Printer operations, the operation is always directed at a Printer object using one of its URIs (i.e., one of the values in the Printer object's "printer-uri-supported" attribute). Even if the Printer object supports more than one URI, the client supplies only one URI as the target of the operation. The client identifies the target object by supplying the correct URI in the "printer-uri (uri)" operation attribute. For Job operations, the operation is directed at either: - The Job object itself using the Job object's URI. In this case, the client identifies the target object by supplying the correct URI in the "job-uri (uri)" operation attribute. - The Printer object that created the Job object using both the Printer objects URI and the Job object's Job ID. Since the Printer object that created the Job object generated the Job ID, it MUST be able to correctly associate the client supplied Job ID with the correct Job object. The client supplies the Printer object's URI in the "printer-uri (uri)" operation attribute and the Job object's Job ID in the "job-id (integer(1:MAX))" operation attribute. If the operation is directed at the Job object directly using the Job object's URI, the client MUST NOT include the redundant "job-id" operation attribute. The operation target attributes are REQUIRED operation attributes that MUST be included in every operation request. Like the charset and natural language attributes (see section 3.1.4), the operation target attributes are specially ordered operation attributes. In all cases, the operation target attributes immediately follow the "attributes-charset" and "attributes-natural-language" attributes within the operation attribute group, however the specific ordering rules are: - In the case where there is only one operation target attribute (i.e., either only the "printer-uri" attribute or only the "job- uri" attribute), that attribute MUST be the third attribute in the operation attributes group. - In the case where Job operations use two operation target attributes (i.e., the "printer-uri" and "job-id" attributes), the "printer-uri" attribute MUST be the third attribute and the "job-id" attribute MUST be the fourth attribute.
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).
(page 50 continued on part 3)
