The file is in:
ftp://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-operation-attributes-and-validatio
n.doc .pdf .txt
I've also embedded the .txt file in this mail message.
We'd like to discuss this paper at the IPP telecon, Wed, 11/19/97 1-3 pm PST.
Send any comments as usual. Many of the ideas in these comments came from
writing code to parse and validate operations according to the
algorithms in Section 15.3 of the Model document.
Thanks,
Tom
Subj: Notes on Operation attributes and operation
validation
From: Tom Hastings, Bob Herriot, Scott Isaacson
Date: 11/18/97
File: ipp-operation-attributes-and-validation
One goal of the validation is to maximize consistent
behavior between clients and servers of different vendors,
including different minor version numbers. It is a goal to
try not to need a major version number change. Major
version number changes are for changes that a client
implementing one major version cannot interwork with an IPP
object implementing another major version number (higher or
lower). These comments on the IPP Model move us closer to
that goal, especially with respect to Operation attributes.
But first some comments on the Operation attributes:
1. Comments on Operation Attributes
Here are some comments on the current draft of the Model
document which will create Operation attributes that are
OPTIONAL for a Printer object to support:
1. The following four Job Template attributes should move
to become Operation attributes and Job Description
attributes: "compression", "job-k-octets", "job-
impressions", and "job-media-sheets". These attributes are
describing the job, not requesting some type of processing.
The corresponding "compression-supported", "job-k-octets-
supported", "job-impressions-supported", and "job-media-
sheets-supported" become Printer Description attributes.
Also none of these four attributes had "xxx-default"
attributes, further indicating that they are different from
Job Template attributes.
2. These four Operation attributes are OPTIONAL for
Printers to support, so some Operation attributes are
OPTIONAL for a Printer to support and some are MANDATORY.
Clients NEED NOT supply these Operation attributes, just as
when they were Job Template attributes.
2. Validation of Operations
Given the above here are some more steps for validating
Operation attributes in all operations that should be added
to section 15.3 in order to meet the interworking goal:
1. The validation of all Operation attributes is
independent of the "ipp-attribute-fidelity" attribute. The
"ipp-attribute-fidelity" only applies to Job Template
attributes in create and Validate-Job requests.
2. For all operations: An IPP object SHALL validate that
the length of each keyword and each attribute value meet the
requirements in the Model document. If they don't, the IPP
object SHALL reject the request and return either the (new)
'client-error-keyword-or-value-too-long' or the (new)
'client-error-wrong-length-value' status codes as
appropriate. For example: a keyword that is 256 or more
octets, or an integer that is not 4 octets long,
respectively.
3. For all operations: Client requests and IPP object
responses SHALL contain attribute groups in the order
specified by the model. An IPP object SHALL verify that the
attribute groups are in the correct order. If an IPP object
receives a request with the attributes groups out of order,
the IPP object SHALL reject the request and return the (new)
'client-error-attribute-groups-out-of-order' status code.
4. For all operations: If the client fails to supply an
Operation attribute that clients MUST supply, the IPP object
SHALL return the (new) 'client-error-missing-required-
operation-attributes' status code with no indication of
which attribute. This error is a development time error or
a major version number mismatch, not an end-user run-time
error and so a client SHOULD not display the status code to
a user. Examples: "attribute-charset" and "attribute-
natural-language" MUST be supplied in all operations.
5. For all operations: an IPP object SHALL ignore all
unsupported Operation attributes, independent of the value
of the "ipp-attribute-fidelity" attribute. An unsupported
attribute is either one that is not in the Model document or
that is in the Model document, but is not required to be
supported. When the operation is otherwise successful, the
IPP object SHALL return the (existing) 'successful-ok-
ignored-or-substituted-attributes' status code. In order to
inform the client of an unsupported Operation attribute, an
IPP object SHALL return such an Operation attribute with the
out-of-band 'unsupported' value copied to the (new)
delimited group in the response, called 'unsupported-
operation-attributes' (new delimiter tag in the Protocol
document). This treatment of unsupported Operation
attributes in all operations is analogous to the handling of
unsupported Job Template attributes in the create and
Validate-Job operations.
Rationale: This rule is so that we can add OPTIONAL
Operation attributes to future versions of IPP without
affecting older clients.
6. For all operations: For supported Operation
attributes, an IPP object SHALL validate that each supplied
attribute value is among the set of supported values for
that attribute. Such validation depends on the specification
of the Operation attribute, not on the operation, and not on
the value of the supplied "ipp-attribute-fidelity"
attribute. Some Operation attribute specifications indicate
that the IPP object SHALL ignore any unsupported values,
while other attribute specifications indicate that the IPP
object SHALL reject the operation for any unsupported
values. See the tables in the next section for each
Operation attribute. For example, the IPP object SHALL
ignore any unsupported values of "attribute-natural-
language", "attributes-requested" and "which-jobs" and SHALL
reject the operation for any unsupported values of
"attribute-charset", "compression", and "document-format".
Such validation includes checking to see (1) that the
attribute syntax tag is correct for the attribute, (2)
that the value is in the range specified for that
attribute syntax in the Model document, (3) the multiple
values are not supplied for attributes that are single-
valued (not 1setOf), and (4) that the value is one of the
set of values that are supported by the IPP object. For
some Operation attributes the set of supported values is
specified by an "xxx-supported" Printer description
attribute, such as "document-format-supported". For
other Operation attributes, the supported values are hard
coded into the implementation.
If the Model document requires unsupported values to be
ignored for the particular Operation attribute, the IPP
object SHALL return the (existing) 'successful-ok-ignored-
or-substituted-attributes' status code. If the Model
document requires that unsupported values to be rejected
for the particular Operation attribute, the IPP object
SHALL return the (renamed) 'client-error-attributes-or-
values-not-supported' status code. See the tables below
for each attribute. In either case, the IPP object SHALL
copy the attribute and value to the (new) 'unsupported-
operation-attributes' delimited group in the response.
Rationale: The reason for checking that the supplied
values are supported and ignoring or rejecting, depending
on the attribute, is so that a future version of IPP
could extend the set of values without affecting older
clients.
3. Summary of new syntax for the Model and Protocol
Summary of new syntax to be added to the Model and Protocol:
1. New delimited group in responses: 'unsupported-
operation-attributes'
2. New 'client-error-keyword-or-value-too-long' status
code
3. New 'client-error-wrong-length-value' status code
4. New 'client-error-attribute-groups-out-of-order' status
code
5. New 'client-error-missing-required-operation-
attributes' status code
6. Rename 'client-error-attribute-not-supported' status
code to 'client-error-attributes-or-values-not-supported',
since it may include both unsupported attributes and
unsupported attribute values.
4. Validation of Job Template and Operation Attributes
This section contains a summary table of the validation of
Job Template and Operation attributes for all operations.
We propose that these tables be added to the Model document.
4.1 Validation of Job Template Attributes
The table below lists the Job Template attributes and shows
what the Printer SHALL do if a value is unsupported. All are
OPTIONAL for a Printer to support. Each "xxx" attribute
that the Printer recognizes is checked against a printer
attribute with the name "xxx-supported" (after "copies-
collated-supported" gets removed) to determine if the value
is supported. If the Printer doesn't recognize/support an
attribute, the Printer treats the attribute as an unknown
attribute (see the unknown rows in the table below). Note
that when a Job Template attribute is not supported, the
value of the "ipp-attribute-fidelity" Operation attribute
determines whether to reject the job (true) or accept it and
ignore the attribute (false).
Job Template Attribute value is supported if xxx- accept or
xxx supported exists and if reject if
the value is: value is
unsupported
job-priority the value is of the based on
(integer(1:100)) correct type (value fidelity
mapped to new priority
value)
job-hold-until the value is a member of based on
(type4 keyword | name) the set fidelity
job-sheets the value is a member of based on
(type4 keyword | name) the set fidelity
multiple-document- the value is a member of based on
handling the set fidelity
(type2 keyword)
copies the value is xxx- based on
(integer(1:MAX)) supported value fidelity
finishings the value is a member of based on
(1setOf type2 enum) the set fidelity
page-ranges the boolean value is true based on
(1setOf fidelity
rangeOfInteger(1:MAX))
sides the value is a member of based on
(type2 keyword) the set fidelity
number-up the value is a member of based on
(integer(0:MAX)) the set consisting of int fidelity
and intRanges
orientation the value is a member of based on
(type2 enum) the set fidelity
media the value is a member of based on
(type4 keyword | name) the set fidelity
printer-resolution the value is a member of based on
(resolution) the set fidelity
print-quality the value is a member of based on
(type2 enum) the set fidelity
unknown attribute the value is not based on
supported fidelity
4.2
Validation of MANDATORY Operation Attributes
The table below contains abbreviations for operations:
Abbr Operation Abb Operation Abbr Operation
r
pj Print-Job sd Send-Document gap Get-Attribute
(Printer)
cj Create- su Send-URI gaj Get-Attribute
Job (Job)
vj Validate- caj Cancel-Job gj Get-Jobs
Job
pu Print-URI
The table below lists operation attributes that are
MANDATORY for a Printer to support, and shows what the
Printer SHALL do if a value is unsupported. Each xxx
attribute is checked against some public or private printer
attribute which must exist because the attribute is
MANDATORY. The check fails if its value is not among those
supported.
Operation Operatio value is supported if accept or
Attributes ns the value is: reject if
xxx value is
unsupported
attributes- all a member of the set in reject
charset Printer's "charset- (client MUST
(charset) supported", which is send)
MANDATORY
attributes- all any value of the accept always
natural- correct type (client MUST
language send)
(naturalLangu
age)
document-uri
(uri) pu, su a member of the set in reject
the Printer's (client MUST
"reference-uri-schemes- send)
supported"
job-id sd, su, a member of the set of reject
(integer(1:MA caj, gaj jobIds (client MUST
X)) send)
document- pj, cj a member of the set in reject
format Printer's "document- (client MAY
(mimeMediaTyp format-supported" send)
e)
ISSUE: this doesn't
seem to be MANDATORY
for a printer to
support. Is that an
oversight?
last-document sd, su any value of the reject
(boolean) correct type (client MAY
send)
requested- gap, any value of the reject
attributes gaj, gj correct type (client MAY
(1setOf send)
keyword)
job-name pj, cj, any value of the reject
(name) vj, pu correct type (client MAY
send)
document-name pj, sd, any value of the reject
(name) su correct type (client MAY
send)
ipp-attribute- pj, cj, any value of the reject
fidelity pu correct type (client MAY
(type 2 send)
keyword)
limit gj any value of the reject
(integer(1:MA correct type (client MAY
X)) send)
4.3
Validation of OPTIONAL Operation Attributes
The table below lists the operation attributes that are
OPTIONAL for a Printer to support and shows what the Printer
SHALL do if a value is unsupported. Each xxx attribute that
the Printer recognizes is checked against some public or
private printer attribute. If the Printer doesn't
recognize/support an attribute, the Printer treats the
attribute as an unknown attribute (see the unknown rows in
the table below). For example, if a printer doesn't support
job-k-octets (because of the implementation or because of
some administrator's choice), the Printer treats job-k-
octets as an unknown attribute.
Operation Operation value is supported if accept or
Attributes s the value is: reject if
xxx value is
unsupported
document- pj, pu, any value of the accept always
natural- sd, su correct type
language
(naturalLangu
age)
compression pj, cj, a member of the set in reject
(type3 vj, pu Printer's "compression- (client MAY
keyword) supported" send)
job-k-octets pj, cj, a member of the reject
(integer(0:MA vj, pu rangeOfInteger in the (client MAY
X)) Printer's "job-k- send)
octets-supported"
job- pj, cj, a member of the reject
impressions vj, pu rangeOfInteger in the (client MAY
(integer(0:MA Printer's "job- send)
X)) impressions-supported"
job-media- pj, cj, a member of the reject
sheets vj, pu rangeOfInteger in the (client MAY
(integer(0:MA Printer's "job-media- send)
X)) sheets-supported"
message caj any value of the accept always
(text) correct type (client MAY
send)
which- gap a member of the set in accept and
document- Printer's "document- ignore
format format-supported" and attribute
(type2 the Printer supports (client MAY
keyword) this Operation send)
attribute
Note: a printer may
support several
document-formats for
printing but not
support this operation
attribute for Get-
Attributes.
which-jobs gj a member of the set of accept and
(type2 values supported by ignore
keyword) the operation (no attribute
Printer attribute) (client MAY
send)
my-jobs gj a member of the set of accept and
(boolean) values supported by ignore
the operation (no attribute
Printer attribute) (client MAY
send)
unknown all not applicable accept and
attribute ignore
attribute
(client MAY
send)
ISSUE: the "document-format" Operation attribute is proposed
to be changed to "which-document-format" in the Get
Attributes (from Printer) operation, so that it isn't
confused with the "document-format" Operation attribute that
is used in pj, cj, vj, pu, sd, and su to identify the
document format of the document being submitted.