standards/rfc3382.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                           R. deBry
   8 Request for Comments: 3382                     Utah Valley State College
   9 Updates: 2910, 2911                                           R. Herriot
  10 Category: Standards Track                                     Consultant
  11                                                              T. Hastings
  12                                                                  K. Ocke
  13                                                                P. Zehler
  14                                                        Xerox Corporation
  15                                                           September 2002
  16
  17
  18                    Internet Printing Protocol (IPP):
  19                    The 'collection' attribute syntax
  20
  21 Status of this Memo
  22
  23    This document specifies an Internet standards track protocol for the
  24    Internet community, and requests discussion and suggestions for
  25    improvements.  Please refer to the current edition of the "Internet
  26    Official Protocol Standards" (STD 1) for the standardization state
  27    and status of this protocol.  Distribution of this memo is unlimited.
  28
  29 Copyright Notice
  30
  31    Copyright (C) The Internet Society (2002).  All Rights Reserved.
  32
  33 Abstract
  34
  35    This document specifies an OPTIONAL attribute syntax called
  36    'collection' for use with the Internet Printing Protocol (IPP/1.0 and
  37    IPP/1.1).  A 'collection' is a container holding one or more named
  38    values, which are called "member" attributes.  A collection allows
  39    data to be grouped like a PostScript dictionary or a Java Map.  This
  40    document also specifies the conformance requirements for a definition
  41    document that defines a collection attribute.  Finally, this document
  42    gives some illustrative example collection attribute definitions that
  43    are not intended as actual attribute specifications.
  44
  45 Table of Contents
  46
  47    1 Introduction.....................................................3
  48    1.1 Problem Statement..............................................3
  49    1.2 Solution.......................................................3
  50    2 Terminology......................................................4
  51    2.1 Conformance Terminology........................................4
  52    2.2 Other terminology..............................................5
  53    3 Definition of a Collection Attribute.............................5
  54    3.1 Information to Include.........................................5
  55
  56
  57
  58 deBry, et. al.              Standards Track                     [Page 1]
  59 \f
  60 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
  61
  62
  63    3.2 Nested Collections.............................................9
  64    4 Collection Attributes as Attributes in Operations................9
  65    4.1 General Rules..................................................9
  66    4.2 Unsupported Values.............................................9
  67    5 Example definition of a collection attribute.....................9
  68    5.1 media-col (collection)........................................10
  69    5.1.1 media-color (type3 keyword | name(MAX)......................10
  70    5.1.2 media-size (collection).....................................11
  71    5.2 media-col-default (collection)................................11
  72    5.3 media-col-ready (1setOf collection)...........................12
  73    5.4 media-col-supported (1setOf type2 keyword)....................12
  74    6 A Second Example Definition Of A Collection Attribute...........12
  75    7 Encoding........................................................13
  76    7.1 Additional tags defined for representing a collection
  77        attribute value...............................................13
  78    7.2 Example encoding: "media-col" (collection)....................14
  79    8 Legacy issues...................................................20
  80    9 IANA Considerations.............................................20
  81    10 Internationalization Considerations............................20
  82    11 Security Considerations........................................21
  83    12 References.....................................................21
  84    Appendix A: Encoding Example of a Simple Collection (Informative).22
  85    Appendix B: Encoding Example of 1setOf Collection (Informative)...25
  86    Appendix C: Encoding Example of Collection containing 1setOf XXX
  87                attribute (Informative)...............................31
  88    Appendix D: Description of the Base IPP Documents (Informative)...35
  89    Authors' Addresses................................................36
  90    Full Copyright Statement..........................................38
  91
  92 Table of Tables
  93
  94    Table 1 - "media-col" member attributes...........................10
  95    Table 2 - "media-size" collection member attributes...............11
  96    Table 3 - Tags defined for encoding the 'collection' attribute
  97              syntax .................................................13
  98    Table 4 - Overview Encoding of "media-col" collection.............15
  99    Table 5 - Example Encoding of "media-col" collection..............16
 100    Table 6 - Overview Encoding of simple collection..................22
 101    Table 7 - Example Encoding of simple collection...................22
 102    Table 8 - Overview Encoding of 1setOf collection..................25
 103    Table 9 - Example Encoding of 1setOf collection...................26
 104    Table 10 - Overview Encoding of collection with 1setOf value......31
 105    Table 11 - Example Encoding of collection with 1setOf value.......32
 106
 107
 108
 109
 110
 111
 112
 113
 114 deBry, et. al.              Standards Track                     [Page 2]
 115 \f
 116 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 117
 118
 119 1 Introduction
 120
 121    This document is an OPTIONAL extension to IPP/1.0 [RFC2565, RFC2566]
 122    and IPP/1.1 [RFC2911, RFC2910].  For a description of the base IPP
 123    documents see Appendix D.
 124
 125 1.1 Problem Statement
 126
 127    The IPP Model and Semantics [RFC2911] supports most of the common
 128    data structures that are available in programming languages.  It
 129    lacks a mechanism for grouping several attributes of different types.
 130    The Java language uses the Map to solve this problem and PostScript
 131    has a dictionary.  The new mechanism for grouping attributes together
 132    (called 'collection' mechanism) must allow for optional members and
 133    the subsequent addition of new members.
 134
 135    The 'collection' mechanism must be encoded in a manner consistent
 136    with existing 1.0 and 1.1 parsing rules (see [RFC2910]).  Current 1.0
 137    and 1.1 parsers that don't support the 'collection' mechanism must
 138    not confuse collections or parts of a collection they receive with
 139    other attributes.
 140
 141 1.2 Solution
 142
 143    The new mechanism is a new IPP attribute syntax called a
 144    'collection'.  As such, each collection value is a value of an
 145    attribute whose attribute syntax type is defined to be a
 146    'collection'.  Such an attribute is called a collection attribute.
 147    The name of the collection attribute serves to identify the
 148    collection value in an operation request or response, as with any
 149    attribute value.
 150
 151    The 'collection' attribute syntax is a container holding one or more
 152    named values (i.e., attributes), which are called member attributes.
 153    Each collection attribute definition document lists the mandatory and
 154    optional member attributes of each collection value.  A collection
 155    value is similar to an IPP attribute group in a request or a
 156    response, such as the operation attributes group.  They both consist
 157    of a set of attributes.
 158
 159    As with any attribute syntax, the document that defines a collection
 160    attribute specifies whether the attribute is single-valued
 161    (collection) or multi-valued (1setOf collection).  If the attribute
 162    is multi-valued (1setOf collection), each collection value MUST be a
 163    separate instance of a single definition of a collection, i.e., it
 164    MUST have the same member attributes except for OPTIONAL member
 165    attributes.  If we view each collection definition as a separate
 166    syntax type, this rule continues the IPP/1.1 notion that each
 167
 168
 169
 170 deBry, et. al.              Standards Track                     [Page 3]
 171 \f
 172 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 173
 174
 175    attribute has a single type or pattern (e.g., "keyword | name" is a
 176    pattern).  Without this rule, the supported values would be more
 177    difficult to describe and the mechanism defined in item 4 of section
 178    3.1 would not be sufficient.
 179
 180    The name of each member attribute MUST be unique for a collection
 181    attribute, but MAY be the same as the name of a member attribute in
 182    another collection attribute and/or MAY be the same as the name of an
 183    attribute that is not a member of a collection.  The rules for naming
 184    member attributes are given in section 3.1.
 185
 186    Each member attribute can have any attribute syntax type, including
 187    'collection', and can be either single-valued or multi-valued.  The
 188    length of a collection value is not limited.  However, the length of
 189    each member attribute MUST NOT exceed the limit of its attribute
 190    syntax.
 191
 192    The member attributes in a collection MAY be in any order in a
 193    request or response.  When a client sends a collection attribute to
 194    the Printer, the order that the Printer stores the member attributes
 195    of the collection value and the order returned in a response MAY be
 196    different from the order sent by the client.
 197
 198    A collection value MUST NOT contain two or more member attributes
 199    with the same attribute name.  Such a collection is mal-formed.
 200    Clients MUST NOT submit such malformed requests and Printers MUST NOT
 201    return such malformed responses.  If such a malformed request is
 202    submitted to a Printer, the Printer MUST (depending on
 203    implementation) either (1) reject the request with the 'client-
 204    error-bad-request' status code (see [RFC2911] section 13.1.4.1), or
 205    (2) accept the request and use only one of each duplicate member
 206    attributes.
 207
 208 2 Terminology
 209
 210    This section defines terminology used throughout this document.
 211
 212 2.1 Conformance Terminology
 213
 214    Capitalized terms, such as MUST, MUST NOT, REQUIRED, SHOULD, SHOULD
 215    NOT, MAY, NEED NOT, and OPTIONAL, have special meaning relating to
 216    conformance as defined in BCP 14, RFC 2119 [RFC2119] and [RFC2911],
 217    section 12.1.  If an implementation supports the extension defined in
 218    this document, then these terms apply; otherwise, they do not.  These
 219    terms define conformance to this document only; they do not affect
 220    conformance to other documents, unless explicitly stated otherwise.
 221
 222
 223
 224
 225
 226 deBry, et. al.              Standards Track                     [Page 4]
 227 \f
 228 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 229
 230
 231 2.2 Other terminology
 232
 233    This document uses terms such as Job object (or Job), IPP Printer
 234    object (or Printer), "operation", "request", response", "attributes",
 235    "keywords", and "support".  These terms have special meaning and are
 236    defined in the model terminology [RFC2911] section 12.2.  The
 237    following additional terms are introduced in this document:
 238
 239       collection: an attribute syntax in which each attribute value is a
 240          set of attributes, called member attributes.
 241
 242       member attribute: an attribute that is defined to be used as one
 243          of the attributes in a collection.
 244
 245       collection attribute: an attribute whose definition specifies the
 246          'collection' attribute syntax and each of the member attributes
 247          that MAY occur in a collection attribute value.
 248
 249 3 Definition of a Collection Attribute
 250
 251    This section describes the requirements for any collection attribute
 252    definition.
 253
 254 3.1 Information to Include
 255
 256    When a specification document defines an "xxx" collection attribute,
 257    i.e., an attribute whose attribute syntax type is 'collection' or
 258    '1setOf collection'; the definition document MUST include the
 259    following aspects of the attribute semantics.  Suppose the "xxx"
 260    collection attribute contains N member attributes named  "aaa1",
 261    "aaa2", ..., "aaaN" ("aaaI" represents any one of these N member
 262    attributes).
 263
 264    1. The name of the collection attribute MUST be specified  (e.g.,
 265       "xxx").  The selection of the name "xxx" MUST follow the same
 266       rules for uniqueness as for attributes of any other syntax type,
 267       (as defined by IPP/1.1) unless "xxx" is a member attribute of
 268       another collection.  Then the selection of the name "xxx" MUST
 269       follow the rules for uniqueness defined in item 5a) of this list.
 270
 271    2. The collection attribute syntax MUST be of type 'collection' or
 272       '1setOf collection'.
 273
 274    3. The context of the collection attribute MUST be specified, i.e.,
 275       whether the attribute is an operation attribute, a Job Template
 276       attribute, a Job Description attribute, a Printer Description
 277       attribute, a member attribute of a particular collection
 278       attribute, etc.
 279
 280
 281
 282 deBry, et. al.              Standards Track                     [Page 5]
 283 \f
 284 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 285
 286
 287    4. An "xxx-supported" attribute MUST be specified and it has one of
 288       the following two forms:
 289
 290       a) "xxx-supported" is a "1setOf collection", which enumerates all
 291          of the supported collection values of "xxx".  If a collection
 292          of this form contains a nested collection, it MUST be of the
 293          same form.
 294
 295          For example, "media-size-supported" might have the values {{x-
 296          dimension:210, y-dimension:297},{x-dimension:297, y-
 297          dimension:420}} to show that it supports two values of "media
 298          size": A4 (210x297) and A3 (297x420).  It does not support
 299          other combinations of "x-dimension" and "y-dimension" member
 300          attributes, such as 210x420 or 297x297, and it does not support
 301          non-enumerated values, such as 420x595.
 302
 303       b) "xxx-supported" is a "1setOf type2 keyword", which enumerates
 304          the names of all of the member attributes of "xxx": "aaa1",
 305          "aaa2", ..., "aaaN".  If a collection of this form contains a
 306          nested collection, it MAY be of either form.  See item 5f)
 307          below for details on supported values of member attributes.
 308
 309          For example, "media-col-supported" might have the keyword
 310          values: "media-size" and "media-color".
 311
 312    5. The member attributes MUST be defined.  For each member attribute,
 313       the definition document MUST provide the following information:
 314
 315       a) The member attribute's name (e.g., "aaa") MUST be unique within
 316          the collection being defined and MUST either:
 317
 318            i) reuse the attribute name of another attribute (that is
 319               unique across the entire IPP attribute name space) and
 320               have the same syntax and semantics as the reused attribute
 321               (if the condition of item 4b) above is met).  For example,
 322               a member attribute definition could reuse the IPP/1.1
 323               "media" attribute.
 324
 325           ii) potentially occur elsewhere in the entire IPP attribute
 326               name space.  (if the condition of item 4a) above is met).
 327               For example, a member attribute could be "x-dimension",
 328               which could potentially occur in another collection or as
 329               an attribute outside of a collection.
 330
 331          iii) be unique across the entire IPP attribute name space (if
 332               the condition of item 4b) above is met).  For example, a
 333               member attribute could be "media-color" which must be
 334               unique across the entire IPP attribute name space.
 335
 336
 337
 338 deBry, et. al.              Standards Track                     [Page 6]
 339 \f
 340 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 341
 342
 343       b) Whether the member attribute is REQUIRED or OPTIONAL for the
 344          Printer to support.
 345
 346       c) Whether the member attribute is REQUIRED or OPTIONAL for the
 347          client to supply in a request.
 348
 349       d) The member attribute's syntax type, which can be any attribute
 350          syntax, including '1setOf X', 'collection', and '1setOf
 351          collection'.  If this attribute name reuses the name of another
 352          attribute (case of item a1 above), it MUST have the same
 353          attribute syntax, including cardinality (whether or not
 354          1setOf).
 355
 356       e) The semantics of the "aaa" member attribute.  The semantic
 357          definition MUST include a description of any constraint or
 358          boundary conditions the member attribute places on the
 359          associated attribute, especially if the attribute reuses the
 360          name of another attribute (case of item a1 above).
 361
 362       f) The supported values for each "aaaI" member attribute (of the
 363          member attributes  "aaa1", "aaa2", ..., "aaaN") is specified by
 364          one of two mechanisms.
 365
 366            i) If "xxx-supported" is a "1setOf collection" (see item 4a)
 367               above), the value for each "aaaI" is specified in each
 368               collection value of "xxx-supported", in the context of
 369               other member attributes.  That is, "xxx-supported"
 370               enumerates all supported values of "xxx".
 371
 372           ii) If the value of "xxx-supported" is a "1setOf type2
 373               keyword" (see item 4b) above), the supported values of
 374               "aaaI" are the values specified by either i) the "aaaI-
 375               supported" attribute or ii) the definition of the member
 376               attribute "aaaI" within the document defining the "xxx"
 377               attribute.  The values of each member attribute "aaaI" are
 378               specified independently of other member attributes, though
 379               a Printer is not required to support all combinations of
 380               supported values.
 381
 382               For example, "media-col-supported" might have the keyword
 383               values: "media-size" and "media-color".  Using the first
 384               method for defining supported values (an "aaaI-supported"
 385               attribute), the collection values of "media-col" are
 386               combinations of values of "media-size-supported" and
 387               "media-color-supported".  If "media-size-supported" has
 388               the values of '210x297' and '297x420' and "media-color-
 389               supported" has the values of 'white' and 'pink', the
 390
 391
 392
 393
 394 deBry, et. al.              Standards Track                     [Page 7]
 395 \f
 396 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 397
 398
 399               Printer might support only the combinations 'white-
 400               210x297', 'pink-210x297' and 'white-297x420', and not
 401               'pink-297x420'.
 402
 403               If a collection contains a member "aaaI", whose syntax
 404               type is "text", the supported values would probably be
 405               defined by the definition of "xxx" rather than by the
 406               attribute "aaaI-supported".
 407
 408       g) the default value of each "aaaI" member attribute if it is
 409          OPTIONAL for a client to supply the "aaa" member attribute in a
 410          request.  The default value is specified by the attribute's
 411          definition within a document and MUST be one of the following:
 412
 413            i) a fixed default
 414
 415           ii) a mechanism by which the Printer determines default
 416
 417          iii) an indefinite default that is left to the implementation.
 418
 419           iv) an attribute that the Printer uses to determine the
 420               default
 421
 422    6. The default value of "xxx", if a client does not supply it.  The
 423       default value is specified by the attribute's definition within a
 424       document and MUST be one of the following:
 425
 426       a) a fixed default
 427
 428       b) a mechanism by which the Printer determines default
 429
 430       c) an indefinite default that is left to the implementation
 431
 432       d) a Printer attribute "xxx-default" which is a collection with
 433          the same member attributes as "xxx".  If optional member
 434          attributes are absent, the Printer uses the defaulting rules of
 435          item 5g) above.
 436
 437    7. The "xxx-ready (1setOf collection)" attribute, if human
 438       intervention is required to make many of the supported values
 439       available.  For example, "media-col" is an attribute which has a
 440       "ready" attribute.  Most attributes do not have a "ready"
 441       attribute.
 442
 443
 444
 445
 446
 447
 448
 449
 450 deBry, et. al.              Standards Track                     [Page 8]
 451 \f
 452 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 453
 454
 455 3.2 Nested Collections
 456
 457    A member attribute may have a syntax type of 'collection' or '1setOf
 458    collection', in which case it is called a nested collection
 459    attribute.  The rules for a nested collection attribute are the same
 460    as for a collection attribute as specified in section 3.1.
 461
 462 4 Collection Attributes as Attributes in Operations
 463
 464 4.1 General Rules
 465
 466    A collection value is like any other IPP/1.1 value, except that it is
 467    structured.  The rules for attributes with collection values are the
 468    same as for attributes of any other syntax type (see IPP/1.1), be
 469    they in any group of a request of a response.
 470
 471 4.2 Unsupported Values
 472
 473    The rules for returning an unsupported collection attribute are an
 474    extension to the current rules:
 475
 476    1. If the entire collection attribute is unsupported, then the
 477       Printer returns just the collection attribute name with the
 478       'unsupported' out-of-band value (see the beginning of [RFC2911]
 479       section 4.1) in the Unsupported Attributes Group.
 480
 481    2. If a collection contains unrecognized, unsupported member
 482       attributes and/or conflicting values, the attribute returned in
 483       the Unsupported Group is a collection containing the unrecognized,
 484       unsupported member attributes, and/or conflicting values.  The
 485       unrecognized member attributes have an out-of-band value of
 486       'unsupported' (see the beginning of [RFC2911] section 4.1).  The
 487       unsupported member attributes and conflicting values have their
 488       unsupported or conflicting values.
 489
 490 5 Example definition of a collection attribute
 491
 492    In some printing environments, it is desirable to allow the client to
 493    select the media by its properties, e.g., weight, color, size, etc.,
 494    instead of by name.  In IPP/1.1 (see [RFC2911]), the "media (type3
 495    keyword | name) Job Template attribute allows selection by name.  It
 496    is tempting to extend the "media" attribute syntax to include
 497    "collection", but then existing clients could not understand default
 498    or supported media values that use the collection value.  To preserve
 499    interoperability, a new attribute MUST BE added, e.g., "media-col
 500    (collection)".  The following subsections contain a sample definition
 501    of a simplified "media-col" attribute.  The definition follows the
 502    rules in section 3.
 503
 504
 505
 506 deBry, et. al.              Standards Track                     [Page 9]
 507 \f
 508 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 509
 510
 511    All of the example attribute definitions in this document are
 512    illustrative examples, rather than actual definitions.  These
 513    examples are intended to illustrate how to define collection
 514    attributes.  Other documents MUST define collection attributes for
 515    use in actual interchange.  Such definitions may be very similar to
 516    the examples in this document, since we attempted to pick useful
 517    examples.
 518
 519    Note: we picked the name "media-col" because the name "media" is
 520    already in use.  Ordinarily the collection attribute would have a
 521    name like any other attribute and would not end in "col".
 522
 523    The member attributes of "media-col" attribute ("media-color (type 3
 524    keyword)" and "media-size (collection)") both follow the naming rules
 525    of item 4a3 of section 3, i.e., the names are unique across the
 526    entire IPP attribute name space.  The member attributes of the
 527    "media-size (collection)" member attribute ("x-dimension
 528    (integer(0:MAX))" and "y-dimension (integer(0:MAX))") both follow the
 529    naming rules of item 4a2 of section 3, i.e., they potentially occur
 530    elsewhere in the IPP attribute name space.
 531
 532 5.1 media-col (collection)
 533
 534    The "media-col" (collection) attribute augments the IPP/1.1 [RFC2911]
 535    "media" attribute.  This collection attribute enables a client end
 536    user to submit a list of media characteristics to the Printer.  When
 537    the client specifies media using the "media-col" collection
 538    attribute, the Printer object MUST match the requested media exactly.
 539    The 'collection' consists of the following member attributes:
 540
 541                   Table 1 - "media-col" member attributes
 542
 543         Attribute name  attribute syntax             request  Printer
 544                                                               Support
 545
 546         media-color     type3 keyword | name (MAX)   MAY      MUST
 547
 548         media-size      collection                   MUST     MUST
 549
 550    The definitions for the member attributes is given in the following
 551    sub-sections:
 552
 553 5.1.1 media-color (type3 keyword | name(MAX)
 554
 555    This member attribute identifies the color of the media.  Valid
 556    values are 'red', 'white' and 'blue'.
 557
 558
 559
 560
 561
 562 deBry, et. al.              Standards Track                    [Page 10]
 563 \f
 564 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 565
 566
 567    The "media-color-supported" (1setOf (type3 keyword | name(MAX)))
 568    Printer attribute identifies the values of this "media-color" member
 569    attribute that the Printer supports, i.e., the colors supported.
 570
 571    If the client omits this member attribute, the Printer determines the
 572    value in an implementation dependent manner.
 573
 574 5.1.2 media-size (collection)
 575
 576    This member attribute identifies the size of the media.  The
 577    'collection' consists of the member attributes shown in Table 2:
 578
 579             Table 2 - "media-size" collection member attributes
 580
 581         Attribute name    attribute syntax      request   Printer
 582                                                           Support
 583
 584         x-dimension       integer (0:MAX)       MUST      MUST
 585
 586         y-dimension       integer (0:MAX)       MUST      MUST
 587
 588    The definitions for the member attributes are given in the following
 589    sub-sections:
 590
 591 5.1.2.1  x-dimension (integer(0:MAX))
 592
 593    This attribute identifies the width of the media in inch units along
 594    the X axis.
 595
 596 5.1.2.2  y-dimension (integer(0:MAX))
 597
 598    This attribute identifies the height of the media in inch units along
 599    the Y axis.
 600
 601    The "media-size-supported" (1setOf collection) Printer attribute
 602    identifies the values of this "media-size" member attribute that the
 603    Printer supports, i.e., the size combinations supported.  The names
 604    of the member attributes are the same as the member attributes of the
 605    "media-size" collection attribute, namely "x-dimension", and "y-
 606    dimension", since they have the same attribute syntax and the same
 607    semantics.
 608
 609 5.2 media-col-default (collection)
 610
 611    The "media-col-default" Printer attribute specifies the media that
 612    the Printer uses, if any, if the client omits the "media-col" and
 613    "media".  Job Template attributes in the Job Creation operation and
 614    the PDL do not include a media specification.  The member attributes
 615
 616
 617
 618 deBry, et. al.              Standards Track                    [Page 11]
 619 \f
 620 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 621
 622
 623    are defined in Table 1.  A Printer MUST support the same member
 624    attributes for this default collection attribute as it supports for
 625    the corresponding "media-col" Job Template attribute.
 626
 627 5.3 media-col-ready (1setOf collection)
 628
 629    The "media-col-ready" Printer attribute identifies the media that are
 630    available for use without human intervention, i.e., the media that
 631    are ready to be used without human intervention.  The collection
 632    value MUST have all of the member attributes that are supported in
 633    Table 1.
 634
 635 5.4 media-col-supported (1setOf type2 keyword)
 636
 637    The "media-col-supported" Printer attribute identifies the keyword
 638    names of the member attributes supported in the "media-col"
 639    collection Job Template attribute, i.e., the keyword names of the
 640    member attributes in Table 1 that the Printer supports.
 641
 642 6 A Second Example Definition Of A Collection Attribute
 643
 644    All of the example attribute definitions in this document are
 645    illustrative examples, rather than actual definitions.  These
 646    examples are intended to illustrate how to define collection
 647    attributes.  Other documents MUST define collection attributes for
 648    use in actual interchange.  Such definitions may be very similar to
 649    the examples in this document, since we attempted to pick useful
 650    examples.
 651
 652    In some printing environments, it is desirable to allow the client to
 653    select the media for the job start sheet.  The reason for not adding
 654    the 'collection' attribute syntax to the existing "job-sheets" Job
 655    Template attribute is the same as for "media".  Instead, a new Job
 656    Template attribute is introduced, e.g., "job-sheet-col (collection)".
 657
 658    The member attributes of "job-sheet-col" attribute ("job-sheets (type
 659    3 keyword)" and "media (type3 keyword | name)") both follow the
 660    naming rules of item 4a1 of section 3, i.e., they reuse existing IPP
 661    attributes.  According to the rules, their supported values come from
 662    the existing IPP attributes: "job-sheets-supported" and "media-
 663    supported".  However, their default values do not come from "job-
 664    sheets-default" and "media-default", respectively.  Rather, the
 665    definition of "job-sheet-col" says that "job-sheets (type 3 keyword)"
 666    is required and if "media (type3 keyword | name)" is absent, the
 667    Printer uses the same media as the rest of the job uses.
 668
 669
 670
 671
 672
 673
 674 deBry, et. al.              Standards Track                    [Page 12]
 675 \f
 676 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 677
 678
 679    If "job-sheet-col" attribute was defined to contain the member
 680    attribute "job-sheet-media (type3 keyword | name)" instead of "media
 681    (type3 keyword | name)", then the definition would also have to
 682    specify a "job-sheet-media-supported (1setOf (type3 keyword | name))"
 683    whose values would be independent of "media-supported (1setOf (type3
 684    keyword | name))" and would be set separately by a System
 685    Administrator.
 686
 687    The actual text for the definition of the attribute is left as an
 688    exercise for the reader.
 689
 690 7 Encoding
 691
 692    This section defines the additional encoding tags used according to
 693    [RFC2910] and gives an example of their use.  The encoding tags
 694    defined in this document MUST be used by all collection attributes
 695    defined in other documents.  However, the example of their use is
 696    illustrative only.
 697
 698 7.1 Additional tags defined for representing a collection attribute
 699     value
 700
 701    The 'collection' attribute syntax uses the tags defined in Table 3.
 702
 703    Table 3 - Tags defined for encoding the 'collection' attribute syntax
 704
 705         Tag name         Tag
 706                          value     Meaning
 707
 708         begCollection    0x34      Begin the collection attribute value.
 709
 710         endCollection    0x37      End the collection attribute value.
 711
 712         memberAttrName   0x4A      The value is the name of the
 713                                    collection member attribute
 714
 715    When encoding a collection attribute "xxx" that contains an attribute
 716    "aaa" and is not inside another collection, the encoding follows
 717    these rules:
 718
 719    1. The beginning of the collection is indicated with a value tag that
 720       MUST be syntax type 'begCollection' (0x34) with a name length and
 721       Name field that represent the name of the collection attribute
 722       ("xxx") as with any attribute, followed by a value.  The Printer
 723       MAY ignore the value and its length MAY be 0.  In the future,
 724       however, this field MAY contain useful information, such as the
 725       collection name (cf. the name of a C struct).
 726
 727
 728
 729
 730 deBry, et. al.              Standards Track                    [Page 13]
 731 \f
 732 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 733
 734
 735    2. Each member attribute is encoded as a sequence of two or more
 736       values that appear to be part of a single multi-valued attribute,
 737       i.e., 1setOf.  The first value after the 'begCollection' value has
 738       the attribute syntax, 'memberAttrName' (0x4A), and its value holds
 739       the name of the first member attribute (e.g., "aaa").  The second
 740       value holds the first member's attribute value, which can be of
 741       any attribute syntax, except 'memberAttrName' or 'endCollection'.
 742       If the first member's attribute value is multi-valued, the third
 743       value holds the second value of the first member's value.
 744       Otherwise, the third value holds the name of second member
 745       attribute (e.g., "bbb"), and its attribute syntax is
 746       'memberAttrName'.  In this case, the fourth member's value is the
 747       value of "bbb".
 748
 749       Note that the technique of encoding a 'collection' as a '1setOf'
 750       makes it easy for a Printer that doesn't support a particular
 751       collection attribute (or the collection attribute syntax at all)
 752       to simply skip over the entire collection value.
 753
 754    3. The end of the collection is indicated with a value tag that MUST
 755       be syntax type 'endCollection' (e.g., 0x37) and MAY have a zero
 756       name length and a zero value length.  In the future, this field
 757       MAY contain useful information, such as the collection name that
 758       matches the one in the 'begCollection' .
 759
 760    4. It is valid to have a member attribute that is itself, a
 761       collection attribute, i.e., collections can be nested within
 762       collections.  This is represented by the occurrence of a member
 763       attribute that is of attribute syntax type 'begCollection'.  Such
 764       a collection is terminated by a matching 'endCollection'.  The
 765       name of such a member attribute is in the immediately preceding
 766       value, whose syntax type is 'memberAttrName'.
 767
 768    5. It is valid for a collection attribute to be multi-valued, i.e.,
 769       have more than one collection value.  If the next attribute
 770       immediately following the 'endCollection' has a zero name length
 771       and a tag of 'begCollection', then the collection attribute is a
 772       multi-valued collection, as with any attribute.  This statement
 773       applies to collections within collections and collections that are
 774       not in collections.
 775
 776 7.2 Example encoding: "media-col" (collection)
 777
 778    The collection specified in section 5 is used for the encoding
 779    example shown in Table 5.  The example also shows nested collections,
 780    since the "media-size" member attribute is a 'collection.  The
 781    encoding example represents a blue 4x6-index card and takes 216
 782    octets.  The Appendices contain more complex examples.
 783
 784
 785
 786 deBry, et. al.              Standards Track                    [Page 14]
 787 \f
 788 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 789
 790
 791    Additional examples have been included in the appendices.
 792
 793    The overall structure of the two collection values can be pictorially
 794    represented as:
 795
 796       "media-col" =
 797         {  "media-color" =  'blue';
 798            "media-size" =
 799            {    "x-dimension" = 6;
 800                 "y-dimension" = 4
 801              }
 802         },
 803
 804    The full encoding is in table 5.  A simplified view of the encoding
 805    looks like this:
 806
 807            Table 4 - Overview Encoding of "media-col" collection
 808
 809       Tag Value             Name                  Value
 810
 811       begCollection         media-col             ""
 812
 813       memberAttrName        ""                    media-color
 814
 815       keyword               ""                    blue
 816
 817       memberAttrName        ""                    media-size
 818
 819       begCollection         ""                    ""
 820
 821       memberAttrName        ""                    x-dimension
 822
 823       integer               ""                    6
 824
 825       memberAttrName        ""                    y-dimension
 826
 827       integer               ""                    4
 828
 829       endCollection         ""                    ""
 830
 831       endCollection         ""                    ""
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842 deBry, et. al.              Standards Track                    [Page 15]
 843 \f
 844 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 845
 846
 847            Table 5 - Example Encoding of "media-col" collection
 848
 849       Octets       Symbolic Value  Protocol   comments
 850                                    field
 851
 852       0x34         begCollection   value-tag  beginning of the "media-
 853                                               col" collection attribute
 854
 855       0x0009                       name-      length of (collection)
 856                                    length     attribute name
 857
 858       media-col    media-col       name       name of (collection)
 859                                               attribute
 860
 861       0x0000                       value-     defined to be 0 for this
 862                                    length     type
 863
 864                                               no value (since value-
 865                                               length was 0)
 866
 867       0x4A         memberAttrName  value-tag  starts a new member
 868                                               attribute: "media-color"
 869
 870       0x0000                       name-      defined to be 0 for this
 871                                    length     type, so part of 1setOf
 872
 873                                               no name (since name-length
 874                                               was 0)
 875
 876       0x000B                       value-     length of "media-color"
 877                                    length     keyword
 878
 879       media-color  media-color     value      value is name of 1st
 880                                               member attribute
 881
 882
 883       0x44         keyword type    value-tag  keyword type
 884
 885       0x0000                       name-      0 indicates 1setOf
 886                                    length
 887
 888                                               no name (since name-length
 889                                               was 0)
 890
 891
 892
 893
 894
 895
 896
 897
 898 deBry, et. al.              Standards Track                    [Page 16]
 899 \f
 900 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 901
 902
 903       Octets       Symbolic Value  Protocol   comments
 904                                    field
 905
 906       0x0004                       value-
 907                                    length
 908
 909       blue         blue            value      value of 1st member
 910                                               attribute
 911
 912
 913       0x4A         memberAttrName  value-tag  starts a new member
 914                                               attribute: "media-size"
 915
 916       0x0000                       name-      defined to be 0 for this
 917                                    length     type, so part of 1setOf
 918
 919                                               no name (since name-length
 920                                               was 0)
 921
 922       0x000A                       value-     length of "media-size"
 923                                    length     keyword
 924
 925       media-size   media-size      value      Name of 2nd member
 926                                               attribute
 927
 928       0x34         begCollection   value-tag  Beginning of the "media-
 929                                               size" collection attribute
 930                                               which is a sub-collection
 931
 932       0x0000                       name-      0 indicates 1setOf
 933                                    length
 934
 935                                               no name (since name-length
 936                                               was 0)
 937
 938       0x0000                       value-     collection attribute names
 939                                    length     have no value
 940
 941                                               no value (since value-
 942                                               length was 0)
 943
 944       0x4A         memberAttrName  value-tag  starts a new member
 945                                               attribute: "x-dimension"
 946
 947
 948
 949
 950
 951
 952
 953
 954 deBry, et. al.              Standards Track                    [Page 17]
 955 \f
 956 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
 957
 958
 959       Octets       Symbolic Value  Protocol   comments
 960                                    field
 961
 962       0x0000                       name-      defined to be 0 for this
 963                                    length     type, so part of 1setOf
 964
 965                                               no name (since name-length
 966                                               was 0)
 967
 968       0x000B                       value-     length of "x-dimension"
 969                                    length     keyword
 970
 971       x-dimension  x-dimension     value      name of  1st sub-
 972                                               collection member
 973                                               attribute
 974
 975
 976       0x21         integer type    value-tag  attribute type
 977
 978       0x0000                       name-      0 indicates 1setOf
 979                                    length
 980
 981                                               no name (since name-length
 982                                               was 0)
 983
 984       0x0004                       value-     length of an integer = 4
 985                                    length
 986
 987       0x0006                       value      value of  1st sub-
 988                                               collection member
 989                                               attribute
 990
 991       0x4A         memberAttrName  value-tag  starts a new member
 992                                               attribute: "y-dimension"
 993
 994       0x0000                       name-      defined to be 0 for this
 995                                    length     type, so part of 1setOf
 996
 997                                               no name (since name-length
 998                                               was 0)
 999
1000       0x000B                       value-     length of the "y-
1001                                    length     dimension" keyword
1002
1003
1004
1005
1006
1007
1008
1009
1010 deBry, et. al.              Standards Track                    [Page 18]
1011 \f
1012 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1013
1014
1015       Octets       Symbolic Value  Protocol   comments
1016                                    field
1017
1018       y-dimension  y-dimension     value      name of  2nd sub-
1019                                               collection member
1020                                               attribute
1021
1022       0x21         integer type    value-tag  attribute type
1023
1024       0x0000                       name-      0 indicates 1setOf
1025                                    length
1026
1027                                               no name (since name-length
1028                                               was 0)
1029
1030       0x0004                       value-     length of an integer = 4
1031                                    length
1032
1033       0x0004                       value      value of  2nd sub-
1034                                               collection member
1035                                               attribute
1036
1037       0x37         endCollection   value-tag  end of the sub-collection
1038
1039       0x0000                       name-      defined to be 0 for this
1040                                    length     type, so part of 1setOf
1041
1042                                               no name (since name-length
1043                                               was 0)
1044
1045       0x0000                       value-     defined to be 0 for this
1046                                    length     type
1047
1048                                               no value (since value-
1049                                               length was 0)
1050
1051       0x37         endCollection   value-tag  end of the 1st collection
1052                                               value in 1setOf
1053
1054       0x0000                       name-      defined to be 0 for this
1055                                    length     type, so part of 1setOf
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066 deBry, et. al.              Standards Track                    [Page 19]
1067 \f
1068 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1069
1070
1071       Octets       Symbolic Value  Protocol   comments
1072                                    field
1073
1074                                               no name (since name-length
1075                                               was 0)
1076
1077       0x0000                       value-     defined to be 0 for this
1078                                    length     type
1079
1080                                               no value (since value-
1081                                               length was 0)
1082
1083 8 Legacy issues
1084
1085    IPP 1.x Printers and Clients will gracefully ignore collections and
1086    its member attributes if it does not understand the collection.  The
1087    begCollection and endCollection elements each look like an attribute
1088    with an attribute syntax that the recipient doesn't support and so
1089    should ignore the entire attribute.  The individual member attributes
1090    and their values will look like a 1setOf values of the collection
1091    attribute, so that the Printer simply ignores the entire attribute
1092    and all of its values.  Returning unsupported attributes is also
1093    simple, since only the name of the collection attribute is returned
1094    with the 'unsupported' out-of-band value (see section 4.2).
1095
1096 9 IANA Considerations
1097
1098    The following table provides registration for the 'collection'
1099    attribute syntax defined in this document.  This is to be registered
1100    according to the procedures in RFC 2911 [RFC2911] section 6.3.
1101
1102    Tag value:      Attribute Syntaxes:            Ref.      Section:
1103    collection                                     RFC 3382         3
1104      0x34          begCollection                  RFC 3382       7.1
1105      0x37          endCollection                  RFC 3382       7.1
1106      0x4A          memberAttrName                 RFC 3382       7.1
1107
1108    The resulting attribute syntax registration will be published in the
1109    http://www.iana.org/assignments/ipp-registrations registry.
1110
1111 10 Internationalization Considerations
1112
1113    This attribute syntax by itself has no impact on
1114    internationalization.  However, the member attributes that are
1115    subsequently defined for use in a collection may have
1116    internationalization considerations, as may any attribute, according
1117    to [RFC2911].
1118
1119
1120
1121
1122 deBry, et. al.              Standards Track                    [Page 20]
1123 \f
1124 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1125
1126
1127 11 Security Considerations
1128
1129    This attribute syntax causes no more security concerns than any other
1130    attribute syntax.  It is only the attributes that are subsequently
1131    defined, to use this or any other attribute syntax, that may have
1132    security concerns, depending on the semantics of the attribute,
1133    according to [RFC2911].
1134
1135 12 References
1136
1137 12.1 Normative References
1138
1139    [RFC2910] Herriot, R., Butler, S., Moore, P. and R. Turner, "Internet
1140              Printing Protocol/1.1: Encoding and Transport", RFC 2910,
1141              September 2000.
1142
1143    [RFC2911] Isaacson, S., deBry, R., Hastings, T., Herriot, R. and P.
1144              Powell, "Internet Printing Protocol/1.1: Model and
1145              Semantics", RFC 2911, September 2000.
1146
1147 12.2 Informative References
1148
1149    [RFC2565] Herriot, R., Butler, S., Moore, P. and R. Tuner, "Internet
1150              Printing Protocol/1.0: Encoding and Transport", RFC 2565,
1151              April 1999.
1152
1153    [RFC2566] deBry, R., Hastings, T., Herriot, R., Isaacson, S. and P.
1154              Powell, "Internet Printing Protocol/1.0: Model and
1155              Semantics", RFC 2566, April 1999.
1156
1157    [RFC2567] Wright, D., "Design Goals for an Internet Printing
1158              Protocol", RFC 2567, April 1999.
1159
1160    [RFC2568] Zilles, S., "Rationale for the Structure and Model and
1161              Protocol for the Internet Printing Protocol", RFC 2568,
1162              April 1999.
1163
1164    [RFC2569] Herriot, R., Hastings, T., Jacobs, N. and J. Martin,
1165              "Mapping between LPD and IPP Protocols", RFC 2569, April
1166              1999.
1167
1168    [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,
1169              L., Leach, P. and T. Berners-Lee, "Hypertext Transfer
1170              Protocol - HTTP/1.1", RFC 2616, June 1999.
1171
1172    [RFC3196] Hastings, T., Manros, C., Zehler, P., Kugler, C. and H.
1173              Holst, "Internet Printing Protocol/1.1: Implementor's
1174              Guide", RFC 3196, November 2001.
1175
1176
1177
1178 deBry, et. al.              Standards Track                    [Page 21]
1179 \f
1180 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1181
1182
1183 Appendix A: Encoding Example of a Simple Collection (Informative)
1184
1185    The overall structure of the collection value can be pictorially
1186    represented as:
1187
1188       "media-size" =
1189         {  "x-dimension" = 6;
1190            "y-dimension" = 4
1191         }
1192
1193    A simplified view of the encoding would look like this:
1194
1195              Table 6 - Overview Encoding of simple collection
1196
1197       Tag Value             Name                  Value
1198
1199       begCollection         media-size            ""
1200
1201       memberAttrName        ""                    x-dimension
1202
1203       integer               ""                    6
1204
1205       memberAttrName        ""                    y-dimension
1206
1207       integer               ""                    4
1208
1209       endCollection         ""                    ""
1210
1211       Note: "" represents a name or value whose length is 0.
1212
1213               Table 7 - Example Encoding of simple collection
1214
1215       Octets       Symbolic Value  Protocol   comments
1216                                    field
1217
1218       0x34         begCollection   value-tag  beginning of the "media-
1219                                               size" collection attribute
1220
1221       0x000A                       name-      length of (collection)
1222                                    length     attribute name
1223
1224       media-size   media-size      name       name of (collection)
1225                                               attribute
1226
1227
1228
1229
1230
1231
1232
1233
1234 deBry, et. al.              Standards Track                    [Page 22]
1235 \f
1236 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1237
1238
1239       Octets       Symbolic Value  Protocol   comments
1240                                    field
1241
1242       0x0000                       value-     defined to be 0 for this
1243                                    length     type
1244
1245                                               no value (since value-
1246                                               length was 0)
1247
1248       0x4A         memberAttrName  value-tag  starts member attribute:
1249                                               "x-dimension"
1250
1251       0x0000                       name-      defined to be 0 for this
1252                                    length     type, so part of 1setOf
1253
1254                                               no name (since name-length
1255                                               was 0)
1256
1257       0x000B                       value-     length of "x-dimension"
1258                                    length     keyword
1259
1260       x-dimension  x-dimension     value      name of  1st collection
1261                                               member attribute
1262
1263
1264       0x21         integer type    value-tag  attribute type
1265
1266       0x0000                       name-      0 indicates 1setOf
1267                                    length
1268
1269                                               no name (since name-length
1270                                               was 0)
1271
1272       0x0004                       value-     length of an integer = 4
1273                                    length
1274
1275       0x0006                       value      value of  1st collection
1276                                               member attribute
1277
1278       0x4A         memberAttrName  value-tag  starts a new member
1279                                               attribute: "y-dimension"
1280
1281       0x0000                       name-      defined to be 0 for this
1282                                    length     type, so part of 1setOf
1283
1284                                               no name (since name-length
1285                                               was 0)
1286
1287
1288
1289
1290 deBry, et. al.              Standards Track                    [Page 23]
1291 \f
1292 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1293
1294
1295       Octets       Symbolic Value  Protocol   comments
1296                                    field
1297
1298       0x000B                       value-     length of the "y-
1299                                    length     dimension" keyword
1300
1301       y-dimension  y-dimension     value      name of  2nd collection
1302                                               member attribute
1303
1304       0x21         integer type    value-tag  attribute type
1305
1306       0x0000                       name-      0 indicates 1setOf for
1307                                    length     media-size
1308
1309                                               no name (since name-length
1310                                               was 0)
1311
1312       0x0004                       value-     length of an integer = 4
1313                                    length
1314
1315       0x0004                       value      value of  2nd collection
1316                                               member attribute
1317
1318       0x37         endCollection   value-tag  end of the collection
1319
1320       0x0000                       name-      defined to be 0 for this
1321                                    length     type, so part of 1setOf
1322
1323                                               no name (since name-length
1324                                               was 0)
1325
1326       0x0000                       value-     defined to be 0 for this
1327                                    length     type
1328
1329                                               no value (since value-
1330                                               length was 0)
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346 deBry, et. al.              Standards Track                    [Page 24]
1347 \f
1348 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1349
1350
1351 Appendix B: Encoding Example of 1setOf Collection (Informative)
1352
1353    The overall structure of the collection value can be pictorially
1354    represented as:
1355
1356       "media-size-supported" =
1357         {  "x-dimension" = 6;
1358            "y-dimension" = 4
1359         },
1360         {  "x-dimension" = 3;
1361            "y-dimension" = 5
1362         };
1363
1364    A simplified view of the encoding would look like this:
1365
1366              Table 8 - Overview Encoding of 1setOf collection
1367
1368       Tag Value              Name                 Value
1369
1370       begCollection          media-size-          ""
1371                              supported
1372
1373       memberAttrName         ""                   x-dimension
1374
1375       integer                ""                   6
1376
1377       memberAttrName         ""                   y-dimension
1378
1379       integer                ""                   4
1380
1381       endCollection          ""                   ""
1382
1383       begCollection          ""                   ""
1384
1385       memberAttrName         ""                   x-dimension
1386
1387       integer                ""                   3
1388
1389       memberAttrName         ""                   y-dimension
1390
1391       integer                ""                   5
1392
1393       endCollection          ""                   ""
1394
1395
1396
1397
1398
1399
1400
1401
1402 deBry, et. al.              Standards Track                    [Page 25]
1403 \f
1404 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1405
1406
1407               Table 9 - Example Encoding of 1setOf collection
1408
1409       Octets       Symbolic Value  Protocol   comments
1410                                    field
1411
1412       0x34         begCollection   value-tag  beginning of the "media-
1413                                               size-supported (1setOf
1414                                               collection" attribute
1415
1416       0x00014                      name-      length of (collection)
1417                                    length     attribute name
1418
1419       media-size-  media-size-     name       name of (collection)
1420       supported    supported                  attribute
1421
1422       0x0000                       value-     defined to be 0 for this
1423                                    length     type
1424
1425                                               no value (since value-
1426                                               length was 0)
1427
1428       0x4A         memberAttrName  value-tag  starts member attribute:
1429                                               "x-dimension"
1430
1431       0x0000                       name-      defined to be 0 for this
1432                                    length     type, so part of 1setOf
1433
1434                                               no name (since name-length
1435                                               was 0)
1436
1437       0x000B                       value-     length of "x-dimension"
1438                                    length     keyword
1439
1440       x-dimension  x-dimension     value      name of  1st collection
1441                                               member attribute
1442
1443       0x21         integer type    value-tag  attribute type
1444
1445       0x0000                       name-      0 indicates 1setOf
1446                                    length
1447
1448                                               no name (since name-length
1449                                               was 0)
1450
1451
1452
1453
1454
1455
1456
1457
1458 deBry, et. al.              Standards Track                    [Page 26]
1459 \f
1460 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1461
1462
1463       Octets       Symbolic Value  Protocol   comments
1464                                    field
1465
1466       0x0004                       value-     length of an integer = 4
1467                                    length
1468
1469       0x0006                       value      value of  1st collection
1470                                               member attribute
1471
1472       0x4A         memberAttrName  value-tag  starts member attribute:
1473                                               "y-dimension"
1474
1475       0x0000                       name-      defined to be 0 for this
1476                                    length     type, so part of 1setOf
1477
1478                                               no name (since name-length
1479                                               was 0)
1480
1481       0x000B                       value-     length of the "y-
1482                                    length     dimension" keyword
1483
1484       y-dimension  y-dimension     value      name of  2nd collection
1485                                               member attribute
1486
1487       0x21         integer type    value-tag  attribute type
1488
1489       0x0000                       name-      0 indicates 1setOf
1490                                    length
1491
1492                                               no name (since name-length
1493                                               was 0)
1494
1495       0x0004                       value-     length of an integer = 4
1496                                    length
1497
1498       0x0004                       value      value of  2nd collection
1499                                               member attribute
1500
1501       0x37         endCollection   value-tag  end of the collection
1502
1503       0x0000                       name-      defined to be 0 for this
1504                                    length     type, so part of 1setOf
1505
1506                                               no name (since name-length
1507                                               was 0)
1508
1509
1510
1511
1512
1513
1514 deBry, et. al.              Standards Track                    [Page 27]
1515 \f
1516 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1517
1518
1519       Octets       Symbolic Value  Protocol   comments
1520                                    field
1521
1522       0x0000                       value-     defined to be 0 for this
1523                                    length     type
1524
1525                                               no value (since value-
1526                                               length was 0)
1527
1528       0x34         begCollection   value-tag  beginning of the 2nd
1529                                               member of the 1setOf
1530                                               "sizes-avail " collection
1531                                               attribute
1532
1533       0x0000                       name-      Zero length name indicates
1534                                    length     this is member of previous
1535                                               attribute
1536
1537                                    name       no name (since name-length
1538                                               was 0)
1539
1540       0x0000                       value-     defined to be 0 for this
1541                                    length     type
1542
1543                                               no value (since value-
1544                                               length was 0)
1545
1546       0x4A         memberAttrName  value-tag  starts member attribute:
1547                                               "x-dimension"
1548
1549       0x0000                       name-      defined to be 0 for this
1550                                    length     type, so part of 1setOf
1551
1552                                               no name (since name-length
1553                                               was 0)
1554
1555       0x000B                       value-     length of "x-dimension"
1556                                    length     keyword
1557
1558       x-dimension  x-dimension     value      name of  1st collection
1559                                               member attribute
1560
1561       0x21         integer type    value-tag  attribute type
1562
1563
1564
1565
1566
1567
1568
1569
1570 deBry, et. al.              Standards Track                    [Page 28]
1571 \f
1572 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1573
1574
1575       Octets       Symbolic Value  Protocol   comments
1576                                    field
1577
1578       0x0000                       name-      0 indicates 1setOf
1579                                    length
1580
1581                                               no name (since name-length
1582                                               was 0)
1583
1584       0x0004                       value-     length of an integer = 4
1585                                    length
1586
1587       0x0003                       value      value of  1st collection
1588                                               member attribute
1589
1590       0x4A         memberAttrName  value-tag  starts member attribute:
1591                                               "y-dimension"
1592
1593       0x0000                       name-      defined to be 0 for this
1594                                    length     type, so part of 1setOf
1595
1596                                               no name (since name-length
1597                                               was 0)
1598
1599       0x000B                       value-     length of the "y-
1600                                    length     dimension" keyword
1601
1602       y-dimension  y-dimension     value      name of  2nd collection
1603                                               member attribute
1604
1605       0x21         integer type    value-tag  attribute type
1606
1607       0x0000                       name-      0 indicates 1setOf
1608                                    length
1609
1610                                               no name (since name-length
1611                                               was 0)
1612
1613       0x0004                       value-     length of an integer = 4
1614                                    length
1615
1616       0x0005                       value      value of  2nd collection
1617                                               member attribute
1618
1619
1620
1621
1622
1623
1624
1625
1626 deBry, et. al.              Standards Track                    [Page 29]
1627 \f
1628 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1629
1630
1631       Octets       Symbolic Value  Protocol   comments
1632                                    field
1633
1634       0x37         endCollection   value-tag  end of the 1setOf
1635                                               collection value
1636
1637       0x0000                       name-      defined to be 0 for this
1638                                    length     type, so part of 1setOf
1639
1640                                               no name (since name-length
1641                                               was 0)
1642
1643       0x0000                       value-     defined to be 0 for this
1644                                    length     type
1645
1646                                               no value (since value-
1647                                               length was 0)
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682 deBry, et. al.              Standards Track                    [Page 30]
1683 \f
1684 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1685
1686
1687 Appendix C: Encoding Example of Collection containing 1setOf XXX
1688             attribute (Informative)
1689
1690    The overall structure of the collection value can be pictorially
1691    represented as:
1692
1693       "wagons" =
1694         {  "colors" = red, blue;
1695            "sizes" = 4, 6, 8
1696         }
1697
1698    A simplified view of the encoding would look like this:
1699
1700        Table 10 - Overview Encoding of collection with 1setOf value
1701
1702             Tag Value                Name                Value
1703
1704             begCollection            wagons              ""
1705
1706             memberAttrName           ""                  colors
1707
1708             keyword                  ""                  red
1709
1710             keyword                  ""                  blue
1711
1712             memberAttrName           ""                  sizes
1713
1714             integer                  ""                  4
1715
1716             integer                  ""                  6
1717
1718             integer                  ""                  8
1719
1720             endCollection            ""                  ""
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738 deBry, et. al.              Standards Track                    [Page 31]
1739 \f
1740 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1741
1742
1743         Table 11 - Example Encoding of collection with 1setOf value
1744
1745       Octets       Symbolic Value  Protocol   comments
1746                                    field
1747
1748       0x34         begCollection   value-tag  beginning of the "wagons"
1749                                               collection attribute
1750
1751       0x0005                       name-      length of (collection)
1752                                    length     attribute name
1753
1754       wagons       wagons          name       name of (collection)
1755                                               attribute
1756
1757       0x0000                       value-     defined to be 0 for this
1758                                    length     type
1759
1760                                               no value (since value-
1761                                               length was 0)
1762
1763       0x4A         memberAttrName  value-tag  starts a new member
1764                                               attribute: "colors"
1765
1766       0x0000                       name-      defined to be 0 for this
1767                                    length     type, so part of 1setOf
1768
1769                                               no name (since name-length
1770                                               was 0)
1771
1772       0x0006                       value-     length of "colors" keyword
1773                                    length
1774
1775       colors       colors          value      value is name of 1st
1776                                               member attribute
1777
1778       0x44         keyword type    value-tag  keyword type
1779
1780       0x0000                       name-      0 indicates 1setOf wagons
1781                                    length
1782
1783                                               no name (since name-length
1784                                               was 0)
1785
1786       0x0004                       value-
1787                                    length
1788
1789
1790
1791
1792
1793
1794 deBry, et. al.              Standards Track                    [Page 32]
1795 \f
1796 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1797
1798
1799       Octets       Symbolic Value  Protocol   comments
1800                                    field
1801
1802       blue         blue            value      value of 1st member
1803                                               attribute
1804
1805       0x44         keyword type    value-tag  keyword type
1806
1807       0x0000                       name-      0 indicates 1setOf wagons
1808                                    length
1809
1810                                               no name (since name-length
1811                                               was 0)
1812
1813       0x0003                       value-
1814                                    length
1815
1816       red          red             value      value of 1st member
1817                                               attribute
1818
1819       0x4A         memberAttrName  value-tag  starts a new member
1820                                               attribute: "sizes"
1821
1822       0x0000                       name-      defined to be 0 for this
1823                                    length     type, so part of 1setOf
1824
1825                                               no name (since name-length
1826                                               was 0)
1827
1828       0x0005                       value-     length of "length-avail"
1829                                    length     keyword
1830
1831       sizes        sizes           value      Name of 2nd member
1832                                               attribute
1833
1834       0x21         integer type    value-tag  attribute type
1835
1836       0x0000                       name-      0 indicates 1setOf wagons
1837                                    length
1838
1839                                               no name (since name-length
1840                                               was 0)
1841
1842       0x0004                       value-     length of an integer = 4
1843                                    length
1844
1845
1846
1847
1848
1849
1850 deBry, et. al.              Standards Track                    [Page 33]
1851 \f
1852 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1853
1854
1855       Octets       Symbolic Value  Protocol   comments
1856                                    field
1857
1858       0x0004                       value      1st value for 1setOf
1859                                               integer attribute
1860
1861       0x21         integer type    value-tag  attribute type
1862
1863       0x0000                       name-      0 indicates 1setOf
1864                                    length
1865
1866                                               no name (since name-length
1867                                               was 0)
1868
1869       0x0004                       value-
1870                                    length     length of an integer = 4
1871
1872       0x0006                       value      2nd value for 1setOf
1873                                               integer attribute
1874
1875       0x21         integer type    value-tag  attribute type
1876
1877       0x0000                       name-      0 indicates 1setOf
1878                                    length
1879
1880                                               no name (since name-length
1881                                               was 0)
1882
1883       0x0004                       value-     length of an integer = 4
1884                                    length
1885
1886       0x0008                       value      3rd  value for 1setOf
1887                                               integer attribute
1888
1889       0x37         endCollection   value-tag  end of the collection
1890
1891       0x0000                       name-      defined to be 0 for this
1892                                    length     type, so part of 1setOf
1893
1894                                               no name (since name-length
1895                                               was 0)
1896
1897       0x0000                       value-     defined to be 0 for this
1898                                    length     type
1899
1900
1901
1902
1903
1904
1905
1906 deBry, et. al.              Standards Track                    [Page 34]
1907 \f
1908 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1909
1910
1911       Octets       Symbolic Value  Protocol   comments
1912                                    field
1913
1914                                               no value (since value-
1915                                               length was 0)
1916
1917 Appendix D: Description of the Base IPP Documents (Informative)
1918
1919    The base set of IPP documents includes:
1920
1921       Design Goals for an Internet Printing Protocol [RFC2567]
1922       Rationale for the Structure and Model and Protocol for the
1923       Internet Printing Protocol [RFC2568]
1924       Internet Printing Protocol/1.1: Model and Semantics [RFC2911]
1925       Internet Printing Protocol/1.1: Encoding and Transport [RFC2910]
1926       Internet Printing Protocol/1.1: Implementer's Guide [RFC3196]
1927       Mapping between LPD and IPP Protocols [RFC2569]
1928
1929    The "Design Goals for an Internet Printing Protocol" document takes a
1930    broad look at distributed printing functionality, and it enumerates
1931    real-life scenarios that help to clarify the features that need to be
1932    included in a printing protocol for the Internet.  It identifies
1933    requirements for three types of users: end users, operators, and
1934    administrators.  It calls out a subset of end user requirements that
1935    are satisfied in IPP/1.0 [RFC2566, RFC2565].  A few OPTIONAL operator
1936    operations have been added to IPP/1.1 [RFC2911, RFC2910].
1937
1938    The "Rationale for the Structure and Model and Protocol for the
1939    Internet Printing Protocol" document describes IPP from a high level
1940    view, defines a roadmap for the various documents that form the suite
1941    of IPP specification documents, and gives background and rationale
1942    for the IETF IPP working group's major decisions.
1943
1944    The "Internet Printing Protocol/1.1: Model and Semantics" document
1945    describes a simplified model with abstract objects, their attributes,
1946    and their operations.  The model introduces a Printer and a Job.  The
1947    Job supports multiple documents per Job.  The model document also
1948    addresses how security, internationalization, and directory issues
1949    are addressed.
1950
1951    The "Internet Printing Protocol/1.1: Encoding and Transport" document
1952    is a formal mapping of the abstract operations and attributes defined
1953    in the model document onto HTTP/1.1 [RFC2616].  It also defines the
1954    encoding rules for a new Internet MIME media type called
1955    "application/ipp".  This document also defines the rules for
1956    transporting over HTTP a message body whose Content-Type is
1957    "application/ipp".  This document defines the 'ipp' scheme for
1958    identifying IPP printers and jobs.
1959
1960
1961
1962 deBry, et. al.              Standards Track                    [Page 35]
1963 \f
1964 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
1965
1966
1967    The "Internet Printing Protocol/1.1: Implementer's Guide" document
1968    gives insight and advice to implementers of IPP clients and IPP
1969    objects.  It is intended to help them understand IPP/1.1 and some of
1970    the considerations that may assist them in the design of their client
1971    and/or IPP object implementations.  For example, a typical order of
1972    processing requests is given, including error checking.  Motivation
1973    for some of the specification decisions is also included.
1974
1975    The "Mapping between LPD and IPP Protocols" document gives some
1976    advice to implementers of gateways between IPP and LPD (Line Printer
1977    Daemon) implementations.
1978
1979 Authors' Addresses
1980
1981    Roger deBry
1982    Utah Valley State College
1983    Orem, UT 84058
1984
1985    Phone: (801) 222-8000
1986    EMail: debryro@uvsc.edu
1987
1988
1989    Tom Hastings
1990    Xerox Corporation
1991    737 Hawaii St.  ESAE 231
1992    El Segundo, CA  90245
1993
1994    Phone: 310-333-6413
1995    Fax: 310-333-5514
1996    EMail: hastings@cp10.es.xerox.com
1997
1998
1999    Robert Herriot
2000    Consultant
2001    706 Colorado Ave
2002    Palo Alto, CA 94303
2003
2004    Phone: 650-327-4466
2005    Fax: 650-327-4466
2006    EMail: bob@herriot.com
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018 deBry, et. al.              Standards Track                    [Page 36]
2019 \f
2020 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
2021
2022
2023    Kirk Ocke
2024    Xerox Corp.
2025    800 Phillips Rd
2026    M/S 128-30E
2027    Webster, NY 14580
2028
2029    Phone: (585) 442-4832
2030    EMail: KOcke@crt.xerox.com
2031
2032
2033    Peter Zehler
2034    Xerox Corp.
2035    800 Phillips Rd
2036    M/S 128-30E
2037    Webster, NY 14580
2038
2039    Phone: (585) 265-8755
2040    EMail: PZehler@crt.xerox.com
2041
2042    IPP Web Page:  http://www.pwg.org/ipp/
2043    IPP Mailing List:  ipp@pwg.org
2044
2045    To subscribe to the ipp mailing list, send the following email:
2046
2047      1) send it to majordomo@pwg.org
2048      2) leave the subject line blank
2049      3) put the following two lines in the message body:
2050           subscribe ipp
2051           end
2052
2053    Implementers of this specification document are encouraged to join
2054    the IPP Mailing List in order to participate in any discussions of
2055    clarification issues and review of registration proposals for
2056    additional attributes and values.  In order to reduce spam the
2057    mailing list rejects mail from non-subscribers, so you must subscribe
2058    to the mailing list in order to send a question or comment to the
2059    mailing list.
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074 deBry, et. al.              Standards Track                    [Page 37]
2075 \f
2076 RFC 3382         IPP: The 'collection' attribute syntax   September 2002
2077
2078
2079 Full Copyright Statement
2080
2081    Copyright (C) The Internet Society (2002).  All Rights Reserved.
2082
2083    This document and translations of it may be copied and furnished to
2084    others, and derivative works that comment on or otherwise explain it
2085    or assist in its implementation may be prepared, copied, published
2086    and distributed, in whole or in part, without restriction of any
2087    kind, provided that the above copyright notice and this paragraph are
2088    included on all such copies and derivative works.  However, this
2089    document itself may not be modified in any way, such as by removing
2090    the copyright notice or references to the Internet Society or other
2091    Internet organizations, except as needed for the purpose of
2092    developing Internet standards in which case the procedures for
2093    copyrights defined in the Internet Standards process must be
2094    followed, or as required to translate it into languages other than
2095    English.
2096
2097    The limited permissions granted above are perpetual and will not be
2098    revoked by the Internet Society or its successors or assigns.
2099
2100    This document and the information contained herein is provided on an
2101    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
2102    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
2103    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
2104    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
2105    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
2106
2107 Acknowledgement
2108
2109    Funding for the RFC Editor function is currently provided by the
2110    Internet Society.
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130 deBry, et. al.              Standards Track                    [Page 38]
2131 \f