RFC 2566
Internet Printing Protocol/1.0: Model and Semantics
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]
- RFC 1759 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
different semantic ideas for each attribute. Section 6.1 describes
how the protocol can be extended with new keyword values. Examples
of attribute name keywords:
"job-name"
"attributes-charset"
Note: This document uses "type1", "type2", and "type3" prefixes to
the "keyword" basic syntax to indicate different levels of review for
extensions (see section 6.1).
4.1.4 'enum' The 'enum' attribute syntax is an enumerated integer value that is in the range from 1 to 2**31 - 1 (MAX). Each value has an associated ' keyword' name. In the definition for each attribute of this syntax type, the full set of possible values for that attribute are listed. This syntax type is used for attributes for which there are enum values assigned by other standards, such as SNMP MIBs. A number of attribute enum values in this specification are also used for corresponding attributes in other standards [RFC1759]. This syntax type is not used for attributes to which the system administrator may assign values. Section 6.1 describes how the protocol can be extended with new enum values. Enum values are for use in the protocol. A user interface will provide a mapping between protocol enum values and displayable user- friendly words and phrases which are localized to the natural language of the user. While the enum symbols 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. Note: SNMP MIBs use '2' for 'unknown' which corresponds to the IPP "out-of-band" value 'unknown'. See the description of the "out-of- band" values at the beginning of Section 4.1. Therefore, attributes of type 'enum' start at '3'. Note: This document uses "type1", "type2", and "type3" prefixes to the "enum" basic syntax to indicate different levels of review for extensions (see section 6.1). 4.1.5 'uri' The 'uri' attribute syntax is any valid Uniform Resource Identifier or URI [RFC2396]. Most often, URIs are simply Uniform Resource Locators or URLs. The maximum length of URIs used as values of IPP attributes is 1023 octets. Although most other IPP attribute syntax types allow for only lower-cased values, this attribute syntax type conforms to the case-sensitive and case-insensitive rules specified in [RFC2396]. 4.1.6 'uriScheme' The 'uriScheme' attribute syntax is a sequence of characters representing a URI scheme according to RFC 2396 [RFC2396]. Though RFC 2396 requires that the values be case-insensitive, IPP requires
all lower case values in IPP attributes to simplify comparing by IPP
clients and Printer objects. Standard values for this syntax type
are the following keywords:
'http': for HTTP schemed URIs (e.g., "http:...")
'https': for use with HTTPS schemed URIs (e.g., "https:...")
(not on IETF standards track)
'ftp': for FTP schemed URIs (e.g., "ftp:...")
'mailto': for SMTP schemed URIs (e.g., "mailto:...")
'file': for file schemed URIs (e.g., "file:...")
A Printer object MAY support any URI 'scheme' that has been
registered with IANA [IANA-MT]. The maximum length of URI 'scheme'
values used to represent IPP attribute values is 63 octets.
4.1.7 'charset'
The 'charset' attribute syntax is a standard identifier for a
charset. A charset is a coded character set and encoding scheme.
Charsets are used for labeling certain document contents and 'text'
and 'name' attribute values. The syntax and semantics of this
attribute syntax are specified in RFC 2046 [RFC2046] and contained in
the IANA character-set Registry [IANA-CS] according to the IANA
procedures [RFC2278]. Though RFC 2046 requires that the values be
case-insensitive US-ASCII, IPP requires all lower case values in IPP
attributes to simplify comparing by IPP clients and Printer objects.
When a character-set in the IANA registry has more than one name
(alias), the name labeled as "(preferred MIME name)", if present,
MUST be used.
The maximum length of 'charset' values used to represent IPP
attribute values is 63 octets.
Some examples are:
'utf-8': ISO 10646 Universal Multiple-Octet Coded Character Set
(UCS) represented as the UTF-8 [RFC2279] transfer encoding
scheme in which US-ASCII is a subset charset.
'us-ascii': 7-bit American Standard Code for Information
Interchange (ASCII), ANSI X3.4-1986 [ASCII]. That standard
defines US-ASCII, but RFC 2045 [RFC2045] eliminates most of the
control characters from conformant usage in MIME and IPP.
'iso-8859-1': 8-bit One-Byte Coded Character Set, Latin Alphabet
Nr 1 [ISO8859-1]. That standard defines a coded character set
that is used by Latin languages in the Western Hemisphere and
Western Europe. US-ASCII is a subset charset.
'iso-10646-ucs-2': ISO 10646 Universal Multiple-Octet Coded
Character Set (UCS) represented as two octets (UCS-2), with the
high order octet of each pair coming first (so-called Big Endian
integer).
Some attribute descriptions MAY place additional requirements on
charset values that may be used, such as REQUIRED values that MUST be
supported or additional restrictions, such as requiring that the
charset have US-ASCII as a subset charset.
4.1.8 'naturalLanguage'
The 'naturalLanguage' attribute syntax is a standard identifier for a
natural language and optionally a country. The values for this
syntax type are defined by RFC 1766 [RFC1766]. Though RFC 1766
requires that the values be case-insensitive US-ASCII, IPP requires
all lower case to simplify comparing by IPP clients and Printer
objects. Examples include:
'en': for English
'en-us': for US English
'fr': for French
'de': for German
The maximum length of 'naturalLanguage' values used to represent IPP
attribute values is 63 octets.
4.1.9 'mimeMediaType'
The 'mimeMediaType' attribute syntax is the Internet Media Type
(sometimes called MIME type) as defined by RFC 2046 [RFC2046] and
registered according to the procedures of RFC 2048 [RFC2048] for
identifying a document format. The value MAY include a charset
parameter, depending on the specification of the Media Type in the
IANA Registry [IANA-MT]. Although most other IPP syntax types allow
for only lower-cased values, this syntax type allows for mixed-case
values which are case-insensitive.
Examples are:
'text/html': An HTML document
'text/plain': A plain text document in US-ASCII (RFC 2046 indicates
that in the absence of the charset parameter MUST mean US-ASCII
rather than simply unspecified) [RFC2046].
'text/plain; charset=US-ASCII': A plain text document in US-ASCII
[52, 56].
'text/plain; charset=ISO-8859-1': A plain text document in ISO
8859-1 (Latin 1) [ISO8859-1].
'text/plain; charset=utf-8': A plain text document in ISO 10646
represented as UTF-8 [RFC2279]
'text/plain, charset=iso-10646-ucs-2': A plain text document in
ISO 10646 represented in two octets (UCS-2) [ISO10646-1]
'application/postscript': A PostScript document [RFC2046]
'application/vnd.hp-PCL': A PCL document [IANA-MT] (charset escape
sequence embedded in the document data)
'application/octet-stream': Auto-sense - see below
One special type is 'application/octet-stream'. If the Printer
object supports this value, the Printer object MUST be capable of
auto-sensing the format of the document data. If the Printer
object's default value attribute "document-format-default" is set to
'application/octet-stream', the Printer object not only supports
auto-sensing of the document format, but will depend on the result of
applying its auto-sensing when the client does not supply the
"document-format" attribute. If the client supplies a document
format value, the Printer MUST rely on the supplied attribute, rather
than trust its auto-sensing algorithm. To summarize:
1. If the client does not supply a document format value, the
Printer MUST rely on its default value setting (which may be '
application/octet-stream' indicating an auto-sensing mechanism).
2. If the client supplies a value other than 'application/octet-
stream', the client is supplying valid information about the
format of the document data and the Printer object MUST trust
the client supplied value more than the outcome of applying an
automatic format detection mechanism. For example, the client
may be requesting the printing of a PostScript file as a '
text/plain' document. The Printer object MUST print a text
representation of the PostScript commands rather than interpret
the stream of PostScript commands and print the result.
3. If the client supplies a value of 'application/octet-stream',
the client is indicating that the Printer object MUST use its
auto-sensing mechanism on the client supplied document data
whether auto-sensing is the Printer object's default or not.
Note: Since the auto-sensing algorithm is probabilistic, if the
client requests both auto-sensing ("document-format" set to '
application/octet-stream') and true fidelity ("ipp-attribute-
fidelity" set to 'true'), the Printer object might not be able to
guarantee exactly what the end user intended (the auto-sensing
algorithm might mistake one document format for another ), but it is
able to guarantee that its auto-sensing mechanism be used.
The maximum length of a 'mimeMediaType' value to represent IPP
attribute values is 255 octets.
4.1.10 'octetString' The 'octetString' attribute syntax is a sequence of octets encoded in a maximum of 1023 octets which is indicated in sub-section headers using the notation: octetString(MAX). This syntax type is used for opaque data. 4.1.11 'boolean' The 'boolean' attribute syntax has only two values: 'true' and ' false'. 4.1.12 'integer' The 'integer' attribute syntax is an integer value that is in the range from -2**31 (MIN) to 2**31 - 1 (MAX). Each individual attribute may specify the range constraint explicitly in sub-section headers if the range is different from the full range of possible integer values. For example: job-priority (integer(1:100)) for the "job-priority" attribute. However, the enforcement of that additional constraint is up to the IPP objects, not the protocol. 4.1.13 'rangeOfInteger' The 'rangeOfInteger' attribute syntax is an ordered pair of integers that defines an inclusive range of integer values. The first integer specifies the lower bound and the second specifies the upper bound. If a range constraint is specified in the header description for an attribute in this document whose attribute syntax is 'rangeOfInteger' (i.e., 'X:Y' indicating X as a minimum value and Y as a maximum value), then the constraint applies to both integers. 4.1.14 'dateTime' The 'dateTime' attribute syntax is a standard, fixed length, 11 octet representation of the "DateAndTime" syntax as defined in RFC 2579 [RFC2579]. RFC 2579 also identifies an 8 octet representation of a "DateAndTime" value, but IPP objects MUST use the 11 octet representation. A user interface will provide a mapping between protocol dateTime values and displayable user-friendly words or presentation values and phrases which are localized to the natural language and date format of the user. 4.1.15 'resolution' The 'resolution' attribute syntax specifies a two-dimensional resolution in the indicated units. It consists of 3 values: a cross feed direction resolution (positive integer value), a feed direction
resolution (positive integer value), and a units value. The semantics of these three components are taken from the Printer MIB [RFC1759] suggested values. That is, the cross feed direction component resolution component is the same as the prtMarkerAddressabilityXFeedDir object in the Printer MIB, the feed direction component resolution component is the same as the prtMarkerAddressabilityFeedDir in the Printer MIB, and the units component is the same as the prtMarkerAddressabilityUnit object in the Printer MIB (namely, '3' indicates dots per inch and '4' indicates dots per centimeter). All three values MUST be present even if the first two values are the same. Example: '300', '600', ' 3' indicates a 300 dpi cross-feed direction resolution, a 600 dpi feed direction resolution, since a '3' indicates dots per inch (dpi). 4.1.16 '1setOf X' The '1setOf X' attribute syntax is 1 or more values of attribute syntax type X. This syntax type is used for multi-valued attributes. The syntax type is called '1setOf' rather than just 'setOf' as a reminder that the set of values MUST NOT be empty (i.e., a set of size 0). Sets are normally unordered. However each attribute description of this type may specify that the values MUST be in a certain order for that attribute. 4.2 Job Template Attributes Job Template attributes describe job processing behavior. Support for Job Template attributes by a Printer object is OPTIONAL (see section 13.2.3 for a description of support for OPTIONAL attributes). Also, clients OPTIONALLY supply Job Template attributes in create requests. Job Template attributes conform to the following rules. For each Job Template attribute called "xxx": 1. If the Printer object supports "xxx" then it MUST support both a "xxx-default" attribute (unless there is a "No" in the table below) and a "xxx-supported" attribute. If the Printer object doesn't support "xxx", then it MUST support neither an "xxx- default" attribute nor an "xxx-supported" attribute, and it MUST treat an attribute "xxx" supplied by a client as unsupported. An attribute "xxx" may be supported for some document formats and not supported for other document formats. For example, it is expected that a Printer object would only support "orientation-requested" for some document formats (such as ' text/plain' or 'text/html') but not others (such as ' application/postscript').
2. "xxx" is OPTIONALLY supplied by the client in a create request.
If "xxx" is supplied, the client is indicating a desired job
processing behavior for this Job. When "xxx" is not supplied,
the client is indicating that the Printer object apply its
default job processing behavior at job processing time if the
document content does not contain an embedded instruction
indicating an xxx-related behavior.
Note: Since an administrator MAY change the default value
attribute after a Job object has been submitted but before it
has been processed, the default value used by the Printer object
at job processing time may be different that the default value
in effect at job submission time.
3. The "xxx-supported" attribute is a Printer object attribute that
describes which job processing behaviors are supported by that
Printer object. A client can query the Printer object to find
out what xxx-related behaviors are supported by inspecting the
returned values of the "xxx-supported" attribute.
Note: The "xxx" in each "xxx-supported" attribute name is
singular, even though an "xxx-supported" attribute usually has
more than one value, such as "job-sheet-supported", unless the
"xxx" Job Template attribute is plural, such as "finishings" or
"sides". In such cases the "xxx-supported" attribute names are:
"finishings-supported" and "sides-supported".
4. The "xxx-default" default value attribute describes what will be
done at job processing time when no other job processing
information is supplied by the client (either explicitly as an
IPP attribute in the create request or implicitly as an embedded
instruction within the document data).
If an application wishes to present an end user with a list of
supported values from which to choose, the application SHOULD query
the Printer object for its supported value attributes. The
application SHOULD also query the default value attributes. If the
application then limits selectable values to only those value that
are supported, the application can guarantee that the values supplied
by the client in the create request all fall within the set of
supported values at the Printer. When querying the Printer, the
client MAY enumerate each attribute by name in the Get-Printer-
Attributes Request, or the client MAY just name the "job-template"
group in order to get the complete set of supported attributes (both
supported and default attributes).
The "finishings" attribute is an example of a Job Template attribute.
It can take on a set of values such as 'staple', 'punch', and/or '
cover'. A client can query the Printer object for the "finishings-
supported" attribute and the "finishings-default" attribute. The
supported attribute contains a set of supported values. The default
value attribute contains the finishing value(s) that will be used for
a new Job if the client does not supply a "finishings" attribute in
the create request and the document data does not contain any
corresponding finishing instructions. If the client does supply the
"finishings" attribute in the create request, the IPP object
validates the value or values to make sure that they are a subset of
the supported values identified in the Printer object's "finishings-
supported" attribute. See section 3.2.1.2.
The table below summarizes the names and relationships for all Job
Template attributes. The first column of the table (labeled "Job
Attribute") shows the name and syntax for each Job Template attribute
in the Job object. These are the attributes that can optionally be
supplied by the client in a create request. The last two columns
(labeled "Printer: Default Value Attribute" and "Printer: Supported
Values Attribute") shows the name and syntax for each Job Template
attribute in the Printer object (the default value attribute and the
supported values attribute). A "No" in the table means the Printer
MUST NOT support the attribute (that is, the attribute is simply not
applicable). For brevity in the table, the 'text' and 'name' entries
do not show the maximum length for each attribute.
+===================+======================+======================+
| Job Attribute |Printer: Default Value| Printer: Supported |
| | Attribute | Values Attribute |
+===================+======================+======================+
| job-priority | job-priority-default |job-priority-supported|
| (integer 1:100) | (integer 1:100) |(integer 1:100) |
+-------------------+----------------------+----------------------+
| job-hold-until | job-hold-until- |job-hold-until- |
| (type3 keyword | | default | supported |
| name) | (type3 keyword | |(1setOf |
| | name) | type3 keyword | name)|
+-------------------+----------------------+----------------------+
| job-sheets | job-sheets-default |job-sheets-supported |
| (type3 keyword | | (type3 keyword | |(1setOf |
| name) | name) | type3 keyword | name)|
+-------------------+----------------------+----------------------+
|multiple-document- |multiple-document- |multiple-document- |
| handling | handling-default |handling-supported |
| (type2 keyword) | (type2 keyword) |(1setOf type2 keyword)|
+-------------------+----------------------+----------------------+
+===================+======================+======================+
| Job Attribute |Printer: Default Value| Printer: Supported |
| | Attribute | Values Attribute |
+===================+======================+======================+
| copies | copies-default | copies-supported |
| (integer (1:MAX)) | (integer (1:MAX)) | (rangeOfInteger |
| | | (1:MAX)) |
+-------------------+----------------------+----------------------+
| finishings | finishings-default | finishings-supported |
|(1setOf type2 enum)|(1setOf type2 enum) |(1setOf type2 enum) |
+-------------------+----------------------+----------------------+
| page-ranges | No | page-ranges- |
| (1setOf | | supported (boolean) |
| rangeOfInteger | | |
| (1:MAX)) | | |
+-------------------+----------------------+----------------------+
| sides | sides-default | sides-supported |
| (type2 keyword) | (type2 keyword) |(1setOf type2 keyword)|
+-------------------+----------------------+----------------------+
| number-up | number-up-default | number-up-supported |
| (integer (1:MAX)) | (integer (1:MAX)) |(1setOf integer |
| | | (1:MAX) | |
| | | rangeOfInteger |
| | | (1:MAX)) |
+-------------------+----------------------+----------------------+
| orientation- |orientation-requested-|orientation-requested-|
| requested | default | supported |
| (type2 enum) | (type2 enum) | (1setOf type2 enum) |
+-------------------+----------------------+----------------------+
| media | media-default | media-supported |
| (type3 keyword | | (type3 keyword | |(1setOf |
| name) | name) | type3 keyword | name)|
| | | |
| | | media-ready |
| | |(1setOf |
| | | type3 keyword | name)|
+-------------------+----------------------+----------------------+
| printer-resolution| printer-resolution- | printer-resolution- |
| (resolution) | default | supported |
| | (resolution) |(1setOf resolution) |
+-------------------+----------------------+----------------------+
| print-quality | print-quality-default| print-quality- |
| (type2 enum) | (type2 enum) | supported |
| | |(1setOf type2 enum) |
+-------------------+----------------------+----------------------+
4.2.1 job-priority (integer(1:100)) This attribute specifies a priority for scheduling the Job. A higher value specifies a higher priority. The value 1 indicates the lowest possible priority. The value 100 indicates the highest possible priority. Among those jobs that are ready to print, a Printer MUST print all jobs with a priority value of n before printing those with a priority value of n-1 for all n. If the Printer object supports this attribute, it MUST always support the full range from 1 to 100. No administrative restrictions are permitted. This way an end-user can always make full use of the entire range with any Printer object. If privileged jobs are implemented outside IPP/1.0, they MUST have priorities higher than 100, rather than restricting the range available to end-users. If the client does not supply this attribute and this attribute is supported by the Printer object, the Printer object MUST use the value of the Printer object's "job-priority-default" at job submission time (unlike most Job Template attributes that are used if necessary at job processing time). The syntax for the "job-priority-supported" is also integer(1:100). This single integer value indicates the number of priority levels supported. The Printer object MUST take the value supplied by the client and map it to the closest integer in a sequence of n integers values that are evenly distributed over the range from 1 to 100 using the formula: roundToNearestInt((100x+50)/n) where n is the value of "job-priority-supported" and x ranges from 0 through n-1. For example, if n=1 the sequence of values is 50; if n=2, the sequence of values is: 25 and 75; if n = 3, the sequence of values is: 17, 50 and 83; if n = 10, the sequence of values is: 5, 15, 25, 35, 45, 55, 65, 75, 85, and 95; if n = 100, the sequence of values is: 1, 2, 3, . 100. If the value of the Printer object's "job-priority-supported" is 10 and the client supplies values in the range 1 to 10, the Printer object maps them to 5, in the range 11 to 20, the Printer object maps them to 15, etc.
(next page on part 4)
