RFC2566 - Internet Printing Protocol/1.0: Model and Semantics(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
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 RFC2396 [RFC2396]. Though
RFC2396 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 RFC2046 [RFC2046] and contained in
the IANA character-set Registry [IANA-CS] according to the IANA
procedures [RFC2278]. Though RFC2046 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 RFC2045 [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 RFC1766 [RFC1766]. Though RFC1766
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 RFC2046 [RFC2046] and
registered according to the procedures of RFC2048 [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 (RFC2046 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 RFC2579
[RFC2579]. RFC2579 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.
4.2.2 job-hold-until (type3 keyword name (MAX))
This attribute specifies the named time period during which the Job
MUST become a candidate for printing.
Standard keyword values for named time periods are:
'no-hold': immediately, if there are not other reasons to hold the
job
'day-time': during the day
'evening': evening
'night': night
'weekend': weekend
'second-shift': second-shift (after close of business)
'third-shift': third-shift (after midnight)
An administrator MUST associate allowable print times with a named
time period (by means outside IPP/1.0). An administrator is
encouraged to pick names that suggest the type of time period. An
administrator MAY define additional values using the 'name' or '
keyword' attribute syntax, depending on implementation.
If the value of this attribute specifies a time period that is in the
future, the Printer MUST add the 'job-hold-until-specified' value to
the job's "job-state-reasons" attribute, move the job to the '
pending-held' state, and MUST NOT schedule the job for printing until
the specified time-period arrives. When the specified time period
arrives, the Printer MUST remove the 'job-hold-until-specified' value
from the job's "job-state-reason" attribute and, if there are no
other job state reasons that keep the job in the 'pending-held'
state, the Printer MUST consider the job as a candidate for
processing by moving the job to the 'pending' state.
If this job attribute value is the named value 'no-hold', or the
specified time period has already started, the job MUST be a
candidate for processing immediately.
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-hold-until-default" at job
submission time (unlike most Job Template attributes that are used if
necessary at job processing time).
4.2.3 job-sheets (type3 keyword name(MAX))
This attribute determines which job start/end sheet(s), if any, MUST
be printed with a job.
Standard keyword values are:
'none': no job sheet is printed
'standard': one or more site specific standard job sheets are
printed, e.g. a single start sheet or both start and end sheet
is printed
An administrator MAY define additional values using the 'name' or '
keyword' attribute syntax, depending on implementation.
Note: The effect of this attribute on jobs with multiple documents
MAY be affected by the "multiple-document-handling" job attribute
(section 4.2.4), depending on the job sheet semantics.
4.2.4 multiple-document-handling (type2 keyword)
This attribute is relevant only if a job consists of two or more
documents. The attribute controls finishing operations and the
placement of one or more print-stream pages into impressions and onto
media sheets. When the value of the "copies" attribute exceeds 1, it
also controls the order in which the copies that result from
processing the documents are produced. For the purposes of this
explanations, if "a" represents an instance of document data, then
the result of processing the data in document "a" is a sequence of
media sheets represented by "a(*)".
Standard keyword values are:
'single-document': If a Job object has multiple documents, say, the
document data is called a and b, then the result of processing
all the document data (a and then b) MUST be treated as a single
sequence of media sheets for finishing operations; that is,
finishing would be performed on the concatenation of the
sequences a(*),b(*). The Printer object MUST NOT force the data
in each document instance to be formatted onto a new print-
stream page, nor to start a new impression on a new media sheet.
If more than one copy is made, the ordering of the sets of media
sheets resulting from processing the document data MUST be a(*),
b(*), a(*), b(*), ..., and the Printer object MUST force each
copy (a(*),b(*)) to start on a new media sheet.
'separate-documents-uncollated-copies': If a Job object has
multiple documents, say, the document data is called a and b,
then the result of processing the data in each document instance
MUST be treated as a single sequence of media sheets for
finishing operations; that is, the sets a(*) and b(*) would each
be finished separately. The Printer object MUST force each copy
of the result of processing the data in a single document to
start on a new media sheet. If more than one copy is made, the
ordering of the sets of media sheets resulting from processing
the document data MUST be a(*), a(*), ..., b(*), b(*) ... .
'separate-documents-collated-copies': If a Job object has multiple
documents, say, the document data is called a and b, then the
result of processing the data in each document instance MUST be
treated as a single sequence of media sheets for finishing
operations; that is, the sets a(*) and b(*) would each be
finished separately. The Printer object MUST force each copy of
the result of processing the data in a single document to start
on a new media sheet. If more than one copy is made, the
ordering of the sets of media sheets resulting from processing
the document data MUST be a(*), b(*), a(*), b(*), ... .
'single-document-new-sheet': Same as 'single-document', except
that the Printer object MUST ensure that the first impression of
each document instance in the job is placed on a new media
sheet. This value allows multiple documents to be stapled
together with a single staple where each document starts on a
new sheet.
The 'single-document' value is the same as 'separate-documents-
collated-copies' with respect to ordering of print-stream pages, but
not media sheet generation, since 'single-document' will put the
first page of the next document on the back side of a sheet if an odd
number of pages have been produced so far for the job, while '
separate-documents-collated-copies' always forces the next document
or document copy on to a new sheet. In addition, if the "finishings"
attribute specifies 'staple', then with 'single-document', documents
a and b are stapled together as a single document with no regard to
new sheets, with 'single-document-new-sheet', documents a and b are
stapled together as a single document, but document b starts on a new
sheet, but with 'separate-documents-uncollated-copies' and '
separate-documents-collated-copies', documents a and b are stapled
separately.
Note: None of these values provide means to produce uncollated sheets
within a document, i.e., where multiple copies of sheet n are
produced before sheet n+1 of the same document.
The relationship of this attribute and the other attributes that
control document processing is described in section 15.3.
4.2.5 copies (integer(1:MAX))
This attribute specifies the number of copies to be printed.
On many devices the supported number of collated copies will be
limited by the number of physical output bins on the device, and may
be different from the number of uncollated copies which can be
supported.
Note: The effect of this attribute on jobs with multiple documents is
controlled by the "multiple-document-handling" job attribute (section
4.2.4) and the relationship of this attribute and the other
attributes that control document processing is described in section
15.3.
4.2.6 finishings (1setOf type2 enum)
This attribute identifies the finishing operations that the Printer
uses for each copy of each printed document in the Job. For Jobs with
multiple documents, the "multiple-document-handling" attribute
determines what constitutes a "copy" for purposes of finishing.
Standard enum values are:
Value Symbolic Name and Description
'3' 'none': Perform no finishing
'4' 'staple': Bind the document(s) with one or more staples.
The exact number and placement of the staples is
site-defined.
'5' 'punch': This value indicates that holes are required in
the finished document. The exact number and placement
of the holes is site-defined The punch specification
MAY be satisfied (in a site- and implementation-
specific manner) either by drilling/punching, or by
substituting pre-drilled media.
'6' 'cover': This value is specified when it is desired to
select a non-printed (or pre-printed) cover for the
document. This does not supplant the specification of
a printed cover (on cover stock medium) by the
document itself.
'7' 'bind': This value indicates that a binding is to be
applied to the document; the type and placement of the
binding is site-defined."
Note: The effect of this attribute on jobs with multiple documents is
controlled by the "multiple-document-handling" job attribute (section
4.2.4) and the relationship of this attribute and the other
attributes that control document processing is described in section
15.3.
If the client supplies a value of 'none' along with any other
combination of values, it is the same as if only that other
combination of values had been supplied (that is the 'none' value has
no effect).
4.2.7 page-ranges (1setOf rangeOfInteger (1:MAX))
This attribute identifies the range(s) of print-stream pages that the
Printer object uses for each copy of each document which are to be
printed. Nothing is printed for any pages identified that do not
exist in the document(s). Ranges MUST be in ascending order, for
example: 1-3, 5-7, 15-19 and MUST NOT overlap, so that a non-spooling
Printer object can process the job in a single pass. If the ranges
are not ascending or are overlapping, the IPP object MUST reject the
request and return the 'client-error-bad-request' status code. The
attribute is associated with print-stream pages not application-
numbered pages (for example, the page numbers found in the headers
and or footers for certain word processing applications).
For Jobs with multiple documents, the "multiple-document-handling"
attribute determines what constitutes a "copy" for purposes of the
specified page range(s). When "multiple-document-handling" is '
single-document', the Printer object MUST apply each supplied page
range once to the concatenation of the print-stream pages. For
example, if there are 8 documents of 10 pages each, the page-range '
41:60' prints the pages in the 5th and 6th documents as a single
document and none of the pages of the other documents are printed.
When "multiple-document-handling" is 'separate-documents-uncollated-
copies' or 'separate-documents-collated-copies', the Printer object
MUST apply each supplied page range repeatedly to each document copy.
For the same job, the page-range '1:3, 10:10' would print the first 3
pages and the 10th page of each of the 8 documents in the Job, as 8
separate documents.
In most cases, the exact pages to be printed will be generated by a
device driver and this attribute would not be required. However,
when printing an archived document which has already been formatted,
the end user may elect to print just a subset of the pages contained
in the document. In this case, if page-range = n.m is specified, the
first page to be printed will be page n. All subsequent pages of the
document will be printed through and including page m.
"page-ranges-supported" is a boolean value indicating whether or not
the printer is capable of supporting the printing of page ranges.
This capability may differ from one PDL to another. There is no
"page-ranges-default" attribute. If the "page-ranges" attribute is
not supplied by the client, all pages of the document will be
printed.
Note: The effect of this attribute on jobs with multiple documents is
controlled by the "multiple-document-handling" job attribute (section
4.2.4) and the relationship of this attribute and the other
attributes that control document processing is described in section
15.3.
4.2.8 sides (type2 keyword)
This attribute specifies how print-stream pages are to be imposed
upon the sides of an instance of a selected medium, i.e., an
impression.
The standard keyword values are:
'one-sided': imposes each consecutive print-stream page upon the
same side of consecutive media sheets.
'two-sided-long-edge': imposes each consecutive pair of print-
stream pages upon front and back sides of consecutive media
sheets, such that the orientation of each pair of print-stream
pages on the medium would be correct for the reader as if for
binding on the long edge. This imposition is sometimes called '
duplex' or 'head-to-head'.
'two-sided-short-edge': imposes each consecutive pair of print-
stream pages upon front and back sides of consecutive media
sheets, such that the orientation of each pair of print-stream
pages on the medium would be correct for the reader as if for
binding on the short edge. This imposition is sometimes called
'tumble' or 'head-to-toe'.
'two-sided-long-edge', 'two-sided-short-edge', 'tumble', and 'duplex'
all work the same for portrait or landscape. However 'head-to-toe'
is 'tumble' in portrait but 'duplex' in landscape. 'head-to-head'
also switches between 'duplex' and 'tumble' when using portrait and
landscape modes.
Note: The effect of this attribute on jobs with multiple documents is
controlled by the "multiple-document-handling" job attribute (section
4.2.4) and the relationship of this attribute and the other
attributes that control document processing is described in section
15.3.