INTERNET-DRAFT                                               Roger deBry
<draft-ietf-ipp-collection-00.txt>                  IBM Printing Company
                                                             T. Hastings
                                                       Xerox Corporation
                                                              R. Herriot
                                                       Xerox Corporation
                                                        December 8, 1999
                    Internet Printing Protocol/1.1:
                   The 'collection' attribute syntax
Status of this Memo:

This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of [RFC2026].  Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, and
its working groups.  Note that other groups may also distribute working
documents as Internet-Drafts.


Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress".


The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt


The list of Internet-Draft Shadow Directories can be accessed as
http://www.ietf.org/shadow.html.

                                Abstract

   This document specifies an OPTIONAL attribute syntax called
   'collection' for use with the Internet Printing Protocol/1.0
   (IPP) [RFC2565, RFC2566] and IPP/1.1 [ipp-mod, ipp-pro]. A
   'collection' is a container holding one or more named values,
   which are called "member" attributes.  A collection allows data
   to be grouped like a C struct.

                           Table of Contents

1  Problem Statement.................................................2
2  Solution..........................................................2
3  Definition of a collection type...................................2
4  Unsupported Values................................................3
5  Encoding..........................................................3
6  Legacy issues.....................................................5
7  IANA Considerations...............................................6
8  Internationalization Considerations...............................6
9  Security Considerations...........................................6
10 References........................................................6
11 Author's Addresses................................................7
12 APPENDIX A: Example of collection usage...........................7
 12.1"job-notify" Operation attribute...............................7
13 Appendix A: Full Copyright Statement..............................8


deBry, Hastings, Herriot                                       [page 1]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999




1  Problem Statement

IPP supports most of the common data structures that are available in
programming languages. It lacks a mechanism for grouping several values
of different types.  The C language uses the struct to solve this
problem.

2  Solution

The IPP 'collection' is a container holding one or more named values
(i.e. attributes), which are called member attributes. A collection also
has a type name, which identifies the allowed member attributes, as does
the name of a C struct or Java class. A collection value is similar to a
group, such as an operation group. They both consist of a series of
attributes.

The name of each member attribute MUST be unique within a collection,
but MAY be the same as the name of a member attribute in another
collection type. In order to support legacy IPP implementations, the
name of a member attribute MUST be different from any attribute in an
operation or object unless its semantics are identical to those in the
operation or object.

Each member attribute can have any syntax type, including collection,
and can be either single-valued or multi-valued.  The length of a
collection value is not limited. However, the length of each member
attribute MUST NOT exceed the limit of its attribute syntax.

Note: if a collection contains two or more member attributes with the
same attribute name, the collection is not well formed. The receiver of
such a collection can either treat the collection as a bad value or
ignore all but one of the identically named members.


3  Definition of a collection type

When a specification defines an attribute whose syntax type is
'collection' or '1setOf collection', it must define following aspects of
the collection.

1.the name of the collection type, whose characters are the same as
  those for a keyword.

2.the following information about each member attribute:

  a) its name, which is a keyword like all attributes. It must be unique
     within the collection type. It must also be unique with respect to
     operation and object attributes unless its semantics are identical
     to those in the operation or object.





deBry, Hastings, Herriot                                       [page 2]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999


  b) its syntax type, which may be any IPP syntax type, include
     collection. If the syntax type starts with "1setOf", the member
     attribute is multi-valued.

  c) its allowed values, either enumerated explicitly or specified by
     the values of a referenced attribute.

  d) whether it MUST be or MAY be supplied by a client.

  e) its default value if a client MAY supply it. The default value can
     be stated explicitly or can come from a specified attribute.

  f) whether it MUST be or MAY be supported by the printer.

  g) its semantics


4  Unsupported Values

The rules for returning an unsupported collection attribute are an
extension to the current rules.

     1.If a collection contains unrecognized, unsupported member
       attributes and/or conflicting value, the attribute returned in
       the Unsupported Group is a collection containing the
       unrecognized, unsupported member attributes, and/or conflicting
       values. The unrecognized member attributes have an out-of-band
       value of unsupported. The unsupported member attributes and
       conflicting values have their unsupported values.


5  Encoding

This section defines the encoding of a collection syntax type.  A
collection is encoded by using three new tags:

Tag name         Tag      Meaning
                 value

beginCollection  0x34     Begin the named collection.

endCollection    0x37     End the named collection.

sepCollection    0x38     Separate two collections of a multi-
                           valued attribute

 A collection value is encoded as a sequence of attribute values
preceded by a beginCollection value and followed by an endCollection
value. The value field of a beginCollection and an endCollection both
contain the name of the collection type, which is a string of ASCII
characters. These values allow a receiver to optionally match an
endCollection value with a beginCollection. A 1setOf collection is
encoded using the rules for 1setOf and collection, except that adjacent
endCollection and beginCollection values MUST be combined into a single

deBry, Hastings, Herriot                                       [page 3]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999


sepCollection value. Its value field contains the collection type. In a
1setOf collection, the endCollection value marks the end of last
collection in the 1setOf collection. For legacy reasons, the name field
for the endCollection and sepCollection must be non-empty.  The name is
arbitrarily assigned to be "c".

The following example is written in the style of the IPP/1.1 "Encoding
and Transport" document [ipp-pro].  The following example is for a job-
notify attribute containing a set of 2 collections.

Octets           Symbolic       Protocol   comments
                 Value          field
0x34             beginCollecti  value-tag  Beginning of the collection
                 on
0x000a                          name-
                                length
job-notify       job-notify     Name
0x000f                          Value-
                                length
job-notify-coll  job-notify-    Value      Collection type
                 coll
0x45             uri type       value-tag  "notify-recipients"
                                           attribute
0x0010                          name-
                                length
notify-          notify-        Name
recipient        recipient
0x0013                          value-
                                length
ipp-                            Value
notify:port=700
0x44             keyword type   value-tag  "notify-event-groups"
                                           attribute
0x000d                          name-
                                length
notify-events                   Name
0x0d                            value-
                                length
job-completed                   Value
0x44             keyword type   value-tag  2nd "notify-event-groups"
                                           attribute
0x0000                          name-      0 length means next
                                length     multiple value
0x0011                          value-
                                length
job-state-       job-           Value
changed          completion
0x38             sepCollection  value-tag  Separator between
                                           collection values
0x0001                          name-
                                length
c                               Name       Non-empty for legacy


deBry, Hastings, Herriot                                       [page 4]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999


Octets           Symbolic       Protocol   comments
                 Value          field
0x000f                          value-
                                length
job-notify-coll                 Value      Matches value of
                                           beginCollection
0x45             uri type       value-tag  "notify-recipients"
                                           attribute
0x0010                          name-
                                length
notify-                         Name
recipient
0x0014                          value-
                                length
mailto:smith@fo                 Value
o.com
0x44             keyword type   value-tag  "notify-event-groups"
                                           attribute
0x000d                          name-
                                length
notify-events                   Name
0x0d                            value-
                                length
job-completed                   Value
0x37             endCollection  value-tag  End of last collection
0x0001                          name-
                                length
c                               Name       Non-empty for legacy
0x000f                          value-
                                length
job-notify-coll                 Value      Matches value of
                                           beginCollection

6  Legacy issues

The encoding has been designed to work with IPP/1.0 and IPP/1.1
implementations. An IPP/1.0 or IPP/1.1 receiver will treat the three new
syntax types, beginCollection, endCollection and sepCollection as
unrecognized syntax types.  A legacy implementation is expected to
behave as follows.

A beginCollection value appears to be an attribute with an unsupported
value.

The member attributes that follow the beginCollection appear to be
normal attributes within their group (e.g. normal for the operation
attributes group). If an attribute has the same name as an attribute
allowed in the group, it as a recognized member of the group (e.g. as a
normal operation attribute).





deBry, Hastings, Herriot                                       [page 5]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999


An endCollection value appears to be an attribute with an unsupported
value and unrecognized name "c". The same is true for a sepCollection
value.


7  IANA Considerations

This attribute syntax will be registered with IANA after the WG approves
its specification according to the procedures for extension of the
IPP/1.1 Model and Semantics [ipp-mod] and after IPP becomes a proposed
IETF standard.


8  Internationalization Considerations

This attribute syntax by itself has no impact on internationalization.
However, the member attributes that are subsequently defined for use in
a collection may have internationalization considerations, as may any
attribute.


9  Security Considerations

This attribute syntax causes no more security concerns than any other
attribute syntax.  It is only the attributes that are subsequently
defined to use this or any other attribute syntax that may have security
concerns, depending on the semantics of the attribute.


10 References

[ipp-mod]
     Isaacson, S., deBry, R., Hastings, T., Herriot, R., Powell, P.,
     "Internet Printing Protocol/1.1: Model and Semantics" draft-ietf-
     ipp-model-v11-04.txt, June 23, 1999.

[ipp-not]
     Isaacson, S., Martin, J., deBry, R., Hastings, T., Shepherd, M.,
     Bergman, R. " Internet Printing Protocol/1.0 & 1.1:  IPP Event
     Notification Specification" draft-ietf-ipp-not-spec-01.doc, work in
     progress, October 10, 1999.

[ipp-pro]
     Herriot, R., Butler, S., Moore, P., Turner, R., "Internet Printing
     Protocol/1.1: Encoding and Transport", draft-ietf-ipp-protocol-v11-
     03.txt, June 23, 1999.

[ISO-10175]
     ISO/IEC 10175 Document Printing Application (DPA), June 1996.

[RFC2565]
     Herriot, R., Butler, S., Moore, P., Tuner, R., "Internet Printing
     Protocol/1.0: Encoding and Transport", RFC 2565, April 1999.




deBry, Hastings, Herriot                                       [page 6]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999


[RFC2566]
     R. deBry, T. Hastings, R. Herriot, S. Isaacson, P. Powell,
     "Internet Printing Protocol/1.0: Model and Semantics", RFC 2566,
     April 1999.


11 Author's Addresses

     Tom Hastings
     Xerox Corporation
     737 Hawaii St.  ESAE 231
     El Segundo, CA  90245

     Phone: 310-333-6413
     Fax: 310-333-5514
     e-mail: hastings@cp10.es.xerox.com

     Robert Herriot
     Xerox Corp.
     3400 Hill View Ave, Building 1
     Palo Alto, CA 94304

     Phone: 650-813-7696
     Fax:  650-813-6860
     e-mail: robert.herriot@pahv.xerox.com

     Roger deBry
     Utah Valley State College
     Orem, UT 84058

     Phone: (801) 222-8000
     EMail: debryro@uvsc.edu

12 APPENDIX A: Example of collection usage

This section describes one collection Job Template example.


12.1"job-notify" Operation attribute

The following example illustrates the definition of a collection
attribute for the "job-notify" operation attribute. Each column of the
table corresponds to information that is required for member attributes.
Only the semantics have been omitted.

1.collection type: "job-notify-coll"

2.members of the collection








deBry, Hastings, Herriot                                       [page 7]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999


Member name    Member type     Supported-     Client         Printer
                                values         supplied/      support
                                               default

notify-        uri             notify-        MUST           MUST
recipient                       recipient-
                                schemes-
                                supported

notify-events  1setOf type2    notify-events- notify-events- MUST
               keyword         supported      default

subscriber-    octetString(63) <any octet     <empty         MUST
user-data                       string>        octetString>

notify-        charset         charset-       attributes-    MAY
attributes-                     supported      charset in
charset                                        operation
                                               group

notify-        naturalLanguage generated-     attributes-    MAY
attributes-                     natural-       natural-
natural-                        language-      language in
language                        supported      operation
                                               group

Note: for the "client supplied/default" column, the default is specified
if the client MAY supply it.


13 Appendix A: Full Copyright Statement

Copyright (C) The Internet Society (1998,1999). All Rights Reserved


This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it or
assist in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are included
on all such copies and derivative works.  However, this document itself
may not be modified in any way, such as by removing the copyright notice
or references to the Internet Society or other Internet organizations,
except as needed for the purpose of developing Internet standards in
which case the procedures for copyrights defined in the Internet
Standards process must be followed, or as required to translate it into
languages other than English.


The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.


This document and the information contained herein is provided on an "AS
IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.


deBry, Hastings, Herriot                                       [page 8]


                      [Expires:  June 8, 2000]



INTERNET-DRAFT IPP/1.1: The 'collection' attribute syntax   Dec 8, 1999
























































deBry, Hastings, Herriot                                       [page 9]

                      [Expires:  June 8, 2000]