INTERNET-DRAFT Roger deBry 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 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) 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]