I know this is on the agenda for next week, but I expect it to eventually
go in the model doc.
Scott
>>> Tom Hastings <hastings@cp10.es.xerox.com> 09/03 12:57 AM >>>
Here is the action item that Roger and I had from the last meeting to
propose explicit text for a 'dictionary' attribute to be added to the
model and protocol documents.
I've posted the .pdf and .doc files in:
ftp://ftp.pwg.org/pub/pwg/new_MOD/
-rw-r--r-- 1 pwg pwg 24576 Sep 3 06:55 ipp-dict.doc
-rw-r--r-- 1 pwg pwg 18152 Sep 3 06:56 ipp-dict.pdf
-rw-r--r-- 1 pwg pwg 11511 Sep 3 06:56 ipp-dict.txt
Attached is the .txt file as well (but the .pdf file is much easier to read,
especially the long example). Also the .pdf file has line numbers and is
four
pages long.
If possible, I'd like to discuss this proposal at the Wed, 9/3, IPP telecon.
Tom
Subj: Proposal for adding a 'dictionary' attribute syntax
to IPP Model
From: Tom Hastings and Roger deBry
Date: 9/02/97, version 0.5
File: ipp-dict.doc
1. Problem Statement
There is no good way to add attribute syntaxes that contain
several fields, whether the fields are mandatory or
optional. Instead of each new attribute that needs more
than one field (struct), requiring an ad hoc attribute
syntax, such as we have done for the 'resolution' attribute
syntax for use in the "printer-resolution" attribute, it
would be desirable to have a simple, general mechanism for
representing multi-field values. It would also be desirable
to allow fields to be omitted, when the attribute
specification allows that. This mechanism would be useful
for both new attributes that we might add to IPP standard,
that might be registered, or that implementors might
implement as private extensions.
2. Suggested solution
Add a 'dictionary' attribute syntax, in which the attribute
value is a set of attributes. Then each 'field' that is
present in the attribute value would be self identifying by
its attribute name. An attribute with an attribute syntax
could be single valued ('dictionary'), i.e., with one
dictionary value, or could be multi-valued ('1SetOf
dictionary'). As with all attribute values, the dictionary
value has a length of the entire value. If the dictionary
attribute is multi-valued, as with any multi-valued
attribute, each dictionary value has a length. Thus
implementations that did not support the specified attribute
could skip over the entire value to get to the next
attribute (or to the next dictionary value, if the
dictionary attribute is multi-valued). The syntax of each
dictionary value is the same as a set of attributes, so each
attribute has its keyword name, its attribute syntax code,
and its value. An attribute in a dictionary can be single
valued or multi-valued as well.
For example, the new "printer-resolution" attribute was
defined using a very ad hoc 'resolution' attribute syntax.
Had we had the dictionary attribute syntax, we might have
chosen to use it here, though we wouldn't have had to
either. If we did use the 'dictionary' attribute syntax for
the "printer-resolution", the attribute value would contain
the following attributes: "cross-feed-resolution", "feed-
resolution", "units". However, we can also keep resolution
as it is, even if we add the 'dictionary' attribute syntax.
As a second example, an attribute could represent the fields
that the submitter wishes to be printed on the job-start
page. The name of the attribute might be: "job-start-page-
contents". The dictionary value might include: "job-name",
"user-name", "job-comment", "account-name", etc. where the
values of the attributes in the dictionary are printed after
each attribute name on the job-start-page.
As a third example, an attribute could represent a person's
address using a dictionary that contains the following
attributes where each attribute has a simple 'text'
attribute syntax:
"addressee-name" required
"company-name" optional
"internal-mail-stop" optional
"apartment-number optional
"street-address" required
"city-or-town required
"state" required
"postal-zone required
"country" optional
"phone-numbers optional
The "address" attribute could be specified to be single-
valued ('dictionary'), or could be multi-valued ('1setOf
dictionary'). Also the specification for the "address"
attribute could require that the constituent attributes be
in the above order or that they could be in any order. For
this example, it would make sense for the specification of
the "address" attribute to require that the dictionary be
ordered, with only the optional attributes being permitted
to be omitted. It seems unnecessary to consider ordered and
unordered dictionaries as separate attribute syntaxes.
Some attribute specifications might allow additional
attributes to be included (open-ended) and other attribute
specifications might specify that only the attributes
specified in the standard or registration may be used in the
dictionary value (closed-ended).
As a fourth example, a dictionary attribute syntax would be
a much better way for the Printer to represent its
capabilities, rather than the ad hoc naming conventions:
"xxx" Printer attribute to represent default and the "xxx-
supported" Printer attribute to represent the supported
values. So the client would request the "xxx" attribute of
the Printer and get back the "xxx" attribute whose
dictionary values would be the "default" and "supported-
values" attributes whose values would indicate the default
and supported values, respectively of the "xxx" job template
attribute. Adding additional attributes to indicate future
capabilities, such as "ready-values", "multi-valued", etc.
could be done by adding additional attributes in the
dictionary value that is returned.
3. Suggested Text
Add to section 4.1 Attribute Syntaxes of the IPP Model
specification:
dictionary: a set or sequence of attributes, where each
attribute MAY be single-valued or multi-valued as specified
for the dictionary attribute. As in the attribute sets that
are passed in operations, no attribute SHALL occur more than
once in a dictionary. However, if the same attribute does
occur more than once in a dictionary, the recipient SHALL
use the later occuring one, ignoring any earlier occurrences
of the same attribute.
The specification of the attribute that uses the
'dictionary' attribute syntax SHALL specify:
1. as with any attribute, whether the attribute is single-
valued (attribute syntax = 'dictionary) or multi-valued
(attribute-syntax = '1SetOf dictionary').
2. whether the attributes in the dictionary value are
ordered or unordered.
3. for each attribute in the dictionary value, whether the
attribute's presence is required or optional.
4. for each attribute permitted in the dictionary value,
the completed specification of that attribute shall be
included or inferred by reference to the specification of
that attribute elsewhere.
5. whether additional attributes not specified with the
dictionary attribute specification may be included (open-
ended) in a dictionary value or not (closed-ended). For
open-ended dictionary attributes, there MAY be some
requirements on what kind of attributes may be included,
including restrictions on attribute syntaxes.
A dictionary may contain another dictionary, if the
specification of the dictionary attribute allows.
Add to section 9, Appendix A: Protocol Examples of the IPP
Protocol specification
9.2 Print-Job Request with an "address" dictionary
attribute, including two address dictionary values and two
phone numbers in the first address dictionary value.
Octets Symbolic Protocol comments
Value field
0x0100 1.0 version
0x0002 PrintJob operation
0x02 start attribute
attributes tag
0x42 name type value-tag "job-name"
attribute
0x0008 name-
length
job-name job-name name
0x0006 value-
length
foobar foobar value
0x?? dictionary value-tag "addresses"
type attribute
0x0007 name-
length
address address name
0x009c value- 156 octets in 1st
length dict value
0x41 text type value-tag start of 1st
dictionary value
0x000e name-
length
addressee- addressee- name "addresses-name"
name name attribute
0x0009 value-
length
Tom Jones Tom Jones value
0x41 text type value-tag "street-address"
attribute
0x000e name-
length
street- street- name
address address
0x000c value-
length
100 Main St. 100 Main value
St.
0x41 text type value-tag "city-or-town"
attribute
0x000c name-
length
city-or-town city-or- name
town
0x0008 value-
length
New York New York value
0x41 text type value-tag "state" attribute
0x0005 name-
length
state state name
0x0002 value-
length
NY NY value
0x41 text type value-tag "postal-zone"
attribute
0x000b name-
length
postal-zone postal-zone name
0x0005 value-
length
10200 10200 value
0x41 text type value-tag "phone-numbers"
attribute
0x000d name-
length
phone- phone- name
numbers numbers
0x08 value-
length
312-1234 312-1234 value
0x41 text type value-tag start of 2nd
phone-numbers
value
0x0000 name- 0 length means
length next multiple
value
0x0008 value-
length
372-8432 372-8432 value end of 1st
dictionary value
0x?? dictionary- value-tag start of 2nd
type dictionary value
0x0000 name- 0 length mean
length next multple
value
0xnnnn 0xnnnn value- nnnn octets in 2nd
length dict value
0x41 text type value-tag start of 2nd
dictionary value
0x000e name-
length
addressee- addressee- name "addresses-name"
name name attribute
0x000a value-
length
Bill Smith Bill Smith value
... nnnn octets of the
next dict value
0x03 start-data data-tag
%!PS... <PostScript data
>