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.
"requested-attributes" (1setOf keyword) :
The client OPTIONALLY supplies this attribute. The IPP object
MUST support this attribute. It is a set of attribute names
and/or attribute group names in whose values the requester is
interested. If the client omits this attribute, the IPP object
MUST respond as if this attribute had been supplied with a value
of 'all'.
3.3.4.2 Get-Job-Attributes Response
The Printer object returns the following sets of attributes as part
of the Get-Job-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 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. The "attributes-
natural-language" MAY be the natural language of the Job object,
rather than the one requested.
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.
Group 3: Job Object Attributes
This is the set of requested attributes and their current
values. The IPP 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 IPP
object MUST respond with the 'unknown' value for any supported
attribute (including all RED butes) for which the IPP object
does not know the value, s it would violate the security policy.
See the description e "out-of-band" values in the beginning of
Section 4.1.
4. Object Attributes
This section describes the attributes with their corresponding
attribute syntaxes and values that are part of the IPP model. The
sections below show the objects and their associated attributes which
are included within the scope of this protocol. Many of these
attributes are derived from other relevant specifications:
- Document Printing Application (DPA) [ISO10175]
- RFC1759 Printer MIB [RFC1759]
Each attribute is uniquely identified in this document using a
"keyword" (see section 12.2.1) which is the name of the attribute.
The keyword is included in the section header describing that
attribute.
Note: Not only are keywords used to identify attributes, but one of
the attribute syntaxes described below is "keyword" so that some
attributes have keyword values. Therefore, these attributes are
defined as having an attribute syntax that is a set of keywords.
4.1 Attribute Syntaxes
This section defines the basic attribute syntax types that all clients
and IPP objects MUST be able to accept in responses and accept in
requests, respectively. Each attribute description in sections 3 and
4 includes the name of attribute syntax(es) in the heading (in
parentheses). A conforming implementation of an attribute MUST
include the semantics of the attribute syntax(es) so identified.
Section 6.3 describes how the protocol can be extended with new
attribute syntaxes.
The attribute syntaxes are specified in the following sub-sections,
where the sub-section heading is the keyword name of the attribute
syntax inside the single quotes. In operation requests and responses
each attribute value MUST be represented as one of the attribute
syntaxes specified in the sub-section heading for the attribute. In
addition, the value of an attribute in a response (but not in a
request) MAY be one of the "out-of-band" values. Standard
"out-of-band" values are:
'unknown': The attribute is supported by the IPP object, but the
value is unknown to the IPP object for some reason.
'unsupported': The attribute is unsupported by the IPP object. This
value MUST be returned only as the value of an attribute in the
Unsupported Attributes Group.
'no-value': The attribute is supported by the Printer object, but
the system administrator has not yet configured a value.
The Encoding and Transport specification [RFC2565] defines mechanisms
for passing "out-of-band" values. All attributes in a request MUST
have one or more values as defined in Sections 4.2 to 4.4. Thus
clients MUST NOT supply attributes with "out-of-band" values. All
attribute in a response MUST have one or more values as defined in
Sections 4.2 to 4.4 or a single "out-of-band" value.
Most attributes are defined to have a single attribute syntax.
However, a few attributes (e.g., "job-sheet", "media", "job-hold-
until") are defined to have several attribute syntaxes, depending on
the value. These multiple attribute syntaxes are separated by the
"|" character in the sub-section heading to indicate the choice.
Since each value MUST be tagged as to its attribute syntax in the
protocol, a single-valued attribute instance may have any one of its
attribute syntaxes and a multi-valued attribute instance may have a
mixture of its defined attribute syntaxes.
4.1.1 'text'
A text attribute is an attribute whose value is a sequence of zero or
more characters encoded in a maximum of 1023 ('MAX') octets. MAX is
the maximum length for each value of any text attribute. However, if
an attribute will always contain values whose maximum length is much
less than MAX, the definition of that attribute will include a
qualifier that defines the maximum length for values of that
attribute. For example: the "printer-location" attribute is
specified as "printer-location (text(127))". In this case, text
values for "printer-location" MUST NOT exceed 127 octets; if supplied
with a longer text string via some external interface (other than the
protocol), implementations are free to truncate to this shorter
length limitation.
In this specification, all text attributes are defined using the '
text' syntax. However, 'text' is used only for brevity; the formal
interpretation of 'text' is: 'textWithoutLanguage |
textWithLanguage'. That is, for any attribute defined in this
specification using the 'text' attribute syntax, all IPP objects and
clients MUST support both the 'textWithoutLanguage' and '
textWithLanguage' attribute syntaxes. However, in actual usage and
protocol execution, objects and clients accept and return only one of
the two syntax per attribute. The syntax 'text' never appears "on-
the-wire".
Both 'textWithoutLanguage' and 'textWithLanguage' are needed to
support the real world needs of interoperability between sites and
systems that use different natural languages as the basis for human
communication. Generally, one natural language applies to all text
attributes in a given request or response. The language is indicated
by the "attributes-natural-language" operation attribute defined in
section 3.1.4 or "attributes-natural-language" job attribute defined
in section 4.3.24, and there is no need to identify the natural
language for each text string on a value-by-value basis. In these
cases, the attribute syntax 'textWithoutLanguage' is used for text
attributes. In other cases, the client needs to supply or the
Printer object needs to return a text value in a natural language
that is different from the rest of the text values in the request or
response. In these cases, the client or Printer object uses the
attribute syntax 'textWithLanguage' for text attributes (this is the
Natural Language Override mechanism described in section 3.1.4).
The 'textWithoutLanguage' and 'textWithLanguage' attribute syntaxes
are described in more detail in the following sections.
4.1.1.1 'textWithoutLanguage'
The 'textWithoutLanguage' syntax indicates a value that is sequence
of zero or more characters. Text strings are encoded using the rules
of some charset. The Printer object MUST support the UTF-8 charset
[RFC2279] and MAY support additional charsets to represent 'text'
values, provided that the charsets are registered with IANA [IANA-
CS]. See Section 4.1.7 for the specification of the 'charset'
attribute syntax, including restricted semantics and examples of
charsets.
4.1.1.2 'textWithLanguage'
The 'textWithLanguage' attribute syntax is a compound attribute
syntax consisting of two parts: a 'textWithoutLanguage' part plus an
additional 'naturalLanguage' (see section 4.1.8) part that overrides
the natural language in force. The 'naturalLanguage' part explicitly
identifies the natural language that applies to the text part of that
value and that value alone. For any give text attribute, the '
textWithoutLanguage' part is limited to the maximum length defined
for that attribute, but the 'naturalLanguage' part is always limited
to 63 octets. Using the 'textWithLanguage' attribute syntax rather
than the normal 'textWithoutLanguage' syntax is the so-called Natural
Language Override mechanism and MUST be supported by all IPP objects
and clients.
If the attribute is multi-valued (1setOf text), then the '
textWithLanguage' attribute syntax MUST be used to explicitly specify
each attribute value whose natural language needs to be overridden.
Other values in a multi-valued 'text' attribute in a request or a
response revert to the natural language of the operation attribute.
In a create request, the Printer object MUST accept and store with
the Job object any natural language in the "attributes-natural-
language" operation attribute, whether the Printer object supports
that natural language or not. Furthermore, the Printer object MUST
accept and store any 'textWithLanguage' attribute value, whether the
Printer object supports that natural language or not. These
requirements are independent of the value of the "ipp-attribute-
fidelity" operation attribute that the client MAY supply.
Example: If the client supplies the "attributes-natural-language"
operation attribute with the value: 'en' indicating English, but the
value of the "job-name" attribute is in French, the client MUST use
the 'textWithLanguage' attribute syntax with the following two
values:
'fr': Natural Language Override indicating French
'Rapport Mensuel': the job name in French
See the Encoding and Transport document [RFC2565] for a detailed
example of the 'textWithLanguage' attribute syntax.
4.1.2 'name'
This syntax type is used for user-friendly strings, such as a Printer
name, that, for humans, are more meaningful than identifiers. Names
are never translated from one natural language to another. The '
name' attribute syntax is essentially the same as 'text', including
the REQUIRED support of UTF-8 except that the sequence of characters
is limited so that its encoded form MUST NOT exceed 255 (MAX) octets.
Also like 'text', 'name' is really an abbreviated notation for either
'nameWithoutLanguage' or 'nameWithLanguage'. That is, all IPP
objects and clients MUST support both the 'nameWithoutLanguage' and '
nameWithLanguage' attribute syntaxes. However, in actual usage and
protocol execution, objects and clients accept and return only one of
the two syntax per attribute. The syntax 'name' never appears "on-
the-wire".
Note: Only the 'text' and 'name' attribute syntaxes permit the
Natural Language Override mechanism.
Some attributes are defined as 'type3 keyword | name'. These
attributes support values that are either type3 keywords or names.
This dual-syntax mechanism enables a site administrator to extend
these attributes to legally include values that are locally defined
by the site administrator. Such names are not registered with IANA.
4.1.2.1 'nameWithoutLanguage'
The 'nameWithoutLanguage' syntax indicates a value that is sequence
of zero or more characters so that its encoded form does not exceed
MAX octets.
4.1.2.2 'nameWithLanguage'
The 'nameWithLanguage' attribute syntax is a compound attribute
syntax consisting of two parts: a 'nameWithoutLanguage' part plus an
additional 'naturalLanguage' (see section 4.1.8) part that overrides
the natural language in force. The 'naturalLanguage' part explicitly
identifies the natural language that applies to that name value and
that name value alone.
The 'nameWithLanguage' attribute syntax behaves the same as the '
textWithLanguage' syntax. If a name is in a language that is
different than the rest of the object or operation, then this '
nameWithLanguage' syntax is used rather than the generic '
nameWithoutLanguage' syntax.
Example: If the client supplies the "attributes-natural-language"
operation attribute with the value: 'en' indicating English, but the
"printer-name" attribute is in German, the client MUST use the '
nameWithLanguage' attribute syntax as follows:
'de': Natural Language Override indicating German
'Farbdrucker': the Printer name in German
4.1.2.3 Matching 'name' attribute values
For purposes of matching two 'name' attribute values for equality,
such as in job validation (where a client-supplied value for
attribute "xxx" is checked to see if the value is among the values of
the Printer object's corresponding "xxx-supported" attribute), the
following match rules apply:
1. 'keyword' values never match 'name' values.
2. 'name' (nameWithoutLanguage and nameWithLanguage) values
match if (1) the name parts match and (2) the Associated
Natural-Language parts (see section 3.1.4.1) match. The
matching rules are:
a. the name parts match if the two names are identical
character by character, except it is RECOMMENDED that case
be ignored. For example: 'Ajax-letter-head-white' MUST
match 'Ajax-letter-head-white' and SHOULD match 'ajax-
letter-head-white' and 'AJAX-LETTER-HEAD-WHITE'.
b. the Associated Natural-Language parts match if the
shorter of the two meets the syntactic requirements of RFC
1766 [RFC1766] and matches byte for byte with the longer.
For example, 'en' matches 'en', 'en-us' and 'en-gb', but
matches neither 'fr' nor 'e'.
4.1.3 'keyword'
The 'keyword' attribute syntax is a sequence of characters, length: 1
to 255, containing only the US-ASCII [ASCII] encoded values for
lowercase letters ("a" - "z"), digits ("0" - "9"), hyphen ("-"), dot
("."), and underscore ("_"). The first character MUST be a lowercase
letter. Furthermore, keywords MUST be in U.S. English.
This syntax type is used for enumerating semantic identifiers of
entities in the abstract protocol, i.e., entities identified in this
document. Keywords are used as attribute names or values of
attributes. Unlike 'text' and 'name' attribute values, 'keyword'
values MUST NOT use the Natural Language Override mechanism, since
they MUST always be US-ASCII and U.S. English.
Keywords are for use in the protocol. A user interface will likely
provide a mapping between protocol keywords and displayable user-
friendly words and phrases which are localized to the natural
language of the user. While the keywords specified in this document
MAY be displayed to users whose natural language is U.S. English,
they MAY be mapped to other U.S. English words for U.S. English
users, since the user interface is outside the scope of this
document.
In the definition for each attribute of this syntax type, the full
set of defined keyword values for that attribute are listed.
When a keyword is used to represent an attribute (its name), it MUST
be unique within the full scope of all IPP objects and attributes.
When a keyword is used to represent a value of an attribute, it MUST
be unique just within the scope of that attribute. That is, the same
keyword MUST NOT be used for two different values within the same
attribute to mean two different semantic ideas. However, the same
keyword MAY be used across two or more attributes, representing