[Search] [txt|pdfized|bibtex] [Tracker] [WG] [Email] [Nits]
Versions: 00 01                                                         
There (3) issues in this document, each beginning 'ISSUE_n:'.

Internet Printing Protocol Working Group                    Tom Hastings
INTERNET DRAFT                                                     Xerox
Expires 7 January 2001                                      Ira McDonald
                                                              High North
                                                             7 July 2000

                   Internet Printing Protocol (IPP):
              Resource Objects and Get Resource Operations
                  <draft-ietf-ipp-get-resource-00.txt>

    Copyright (C) The Internet Society (2000). All Rights Reserved.


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 at
     http://www.ietf.org/shadow.html.


Abstract

   This document is a submission to the Internet Printing Protocol
   Working Group of the Internet Engineering Task Force (IETF).
   Comments should be submitted to the ipp@pwg.org mailing list.

   This IPP Get Resource document specifies an extension to IPP/1.0
   [RFC-2565] [RFC-2566] and IPP/1.1 [IPP-MOD] [IPP-PRO].  This document
   extends the current closed IPP object model with a passive
   polymorphic object that is intended to satisfy most needs for new
   object types in the long-term evolution of IPP via an extensible
   object framework.

   This document defines:  Resource object (passive polymorphic object);
   Resource get operations (e.g., Get-Resource-Attributes); Resource
   attributes (e.g., "resource-name"); new Printer attributes (e.g.,
   "resource-type-supported"); Resource type of Driver (a morph of the
   Resource object); methods for supporting 'driver download' to IPP
   Client systems.


Hastings, McDonald            Expires 7 January 2001            [Page 1]


Internet Draft          IPP Get Resource Operations          7 July 2000

                           Table of Contents

1.  Introduction ...............................................       4
2.  IPP Model for Resources ....................................       5
  2.1.  Resource Object ........................................       5
3.  Terminology ................................................       6
  3.1.  Conformance Terminology ................................       6
  3.2.  Model Terminology ......................................       6
4.  Resource Operations ........................................       7
  4.1.  Get-Resource-Attributes Operation ......................       7
    4.1.1.  Get-Resource-Attributes Request ....................       8
    4.1.2.  Get-Resource-Attributes Response ...................       9
  4.2.  Get-Resource-Data Operation ............................      10
    4.2.1.  Get-Resource-Data Request ..........................      10
    4.2.2.  Get-Resource-Data Response .........................      10
  4.3.  Get-Resources Operation ................................      11
    4.3.1.  Get-Resources Request ..............................      11
    4.3.2.  Get-Resources Response .............................      12
  4.4.  Resource Operation Response Status Codes ...............      13
5.  Resource Attributes ........................................      14
  5.1.  Table of Required Resource Attributes ..................      14
  5.2.  Table of Optional Resource Attributes ..................      15
  5.3.  Resource Template Attributes ...........................      16
    5.3.1.  resource-info (text(127)) ..........................      16
    5.3.2.  resource-charset (charset) .........................      16
    5.3.3.  resource-natural-language (naturalLanguage) ........      16
    5.3.4.  resource-document-formats (1setOf mimeMediaType) ...      17
    5.3.5.  resource-os-types (1setOf type2 keyword) ...........      17
    5.3.6.  resource-data-present (boolean) ....................      17
    5.3.7.  resource-data-uri (1setOf uri) .....................      18
    5.3.8.  resource-data-k-octets (integer(0:MAX)) ............      18
    5.3.9.  resource-data-compression (type3 keyword) ..........      18
    5.3.10.  resource-create-date-time (dateTime) ..............      19
    5.3.11.  resource-duration (integer(0:MAX)) ................      19
    5.3.12.  resource-persistence (boolean) ....................      19
  5.4.  Resource Description Attributes ........................      20
    5.4.1.  resource-type (type2 keyword) ......................      20
    5.4.2.  resource-name (name(127)) ..........................      20
    5.4.3.  resource-id (integer(1:MAX)) .......................      20
    5.4.4.  resource-printer-uri (uri) .........................      21
    5.4.5.  resource-create-user-name (name(MAX)) ..............      21
    5.4.6.  resource-create-time (integer(0:MAX)) ..............      21
    5.4.7.  resource-change-time (integer(0:MAX)) ..............      22
    5.4.8.  resource-refresh-time (integer(0:MAX)) .............      22
    5.4.9.  resource-expiration-time (integer(0:MAX)) ..........      22
6.  Driver Resource Type .......................................      23
  6.1.  Table of Required Driver Resource Attributes ...........      23
  6.2.  Table of Optional Driver Resource Attributes ...........      23
  6.3.  Driver Resource Template Attributes ....................      24
    6.3.1.  driver-charset (1setOf charset) ....................      24
    6.3.2.  driver-natural-language (1setOf naturalLanguage) ...      24

Hastings, McDonald            Expires 7 January 2001            [Page 2]


Internet Draft          IPP Get Resource Operations          7 July 2000

    6.3.3.  driver-file-type (type2 keyword) ...................      24
    6.3.4.  driver-file-name (name(MAX)) .......................      25
7.  Conformance Requirements ...................................      26
  7.1.  IPP Client Conformance Requirements ....................      26
  7.2.  IPP Printer Conformance Requirements ...................      26
    7.2.1.  Resource Operations ................................      26
    7.2.2.  Resource Attributes ................................      27
    7.2.3.  Driver Resource Attributes .........................      27
8.  IANA Considerations ........................................      28
9.  Internationalization Considerations ........................      28
10.  Security Considerations ...................................      28
11.  Encodings of Additional Resource Tags .....................      28
12.  References ................................................      28
13.  Authors' Addresses ........................................      29
14.  Appendix A - Change History ...............................      30
  14.1.  7 July 2000 - draft-ietf-ipp-get-resource-00.txt ......      30
15.  Full Copyright Statement ..................................      30



































Hastings, McDonald            Expires 7 January 2001            [Page 3]


Internet Draft          IPP Get Resource Operations          7 July 2000



1.  Introduction

   See section 1 'Introduction' in [IPP-MOD] for a full description of
   the IPP document set and overview information about IPP.

   This document is a submission to the Internet Printing Protocol
   Working Group of the Internet Engineering Task Force (IETF).
   Comments should be submitted to the ipp@pwg.org mailing list.

   This IPP Get Resource document specifies an extension to IPP/1.0
   [RFC-2565] [RFC-2566] and IPP/1.1 [IPP-MOD] [IPP-PRO].  This document
   extends the current closed IPP object model with a passive
   polymorphic object which is intended to satisfy most growth needs for
   new object types in the long-term evolution of IPP via an extensible
   object framework.

   This document defines:  Resource object (passive polymorphic object);
   Resource get operations (e.g., Get-Resource-Attributes); Resource
   attributes (e.g., "resource-name"); new Printer attributes (e.g.,
   "resource-type-supported"); Resource type of Driver (a morph of the
   Resource object); methods for supporting 'driver download' to IPP
   Client systems.

   This document does not specify other possible Resource operations
   (e.g., 'Create-Resource') or Resource types (e.g., 'font').  A future
   document may specify a complete set of system admin operations for
   Resource objects.

   This document is laid out as follows:
   - Section 2 adds the Resource object to the IPP object model.

   - Section 3 is the terminology used throughout the document.

   - Section 4 specifies the operations on Resource objects, including
     new status codes for Resource operations.

   - Section 5 specifies the attributes common to all Resource objects.

   - Section 6 specifies the Driver Resource type and its additional
     attributes - to allow client print support (e.g., driver) download
     (all or part of an IPP Client) from an IPP Printer.

   - Section 7 specifies the conformance requirements for this document.

   - Section 8, 9, and 10 specify IANA, internationalization, and
     security considerations.

   - Section 11 allocates new protocol encoding values for this
     document.

Hastings, McDonald            Expires 7 January 2001            [Page 4]


Internet Draft          IPP Get Resource Operations          7 July 2000


   - Sections 12, 13, 14, and 15 list references, authors' addresses,
     change history, and full IETF copyright statement.



2.  IPP Model for Resources

   See section 2 'IPP Objects' in [IPP-MOD] for a full description of
   the IPP object model and terminology.



   2.1.  Resource Object

   IPP Resource objects are used to model installed features or
   capabilities of IPP Printers (e.g., 'font').  All Resource object
   instances contain a common set of base Resource object attributes.

   Resource object instances MAY have an additional set of attributes,
   according to their "resource-type" and IPP Printer implementation.

   Resource objects instances MAY also have associated data, according
   to their "resource-type" and IPP Printer implementation.  Resource
   data (if any) is available by reference in "resource-data-uri" or by
   value if "resource-data-present" is 'true' (i.e., a local copy of the
   Resource data is available on the IPP Printer).

   Section 4 describes each of the Resource operations in detail.























Hastings, McDonald            Expires 7 January 2001            [Page 5]


Internet Draft          IPP Get Resource Operations          7 July 2000



3.  Terminology

   This specification document uses the terminology defined in this
   section.


   3.1.  Conformance Terminology

   The terms "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
   "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
   interpreted as described in [RFC-2119].  These terms are used to
   specify conformance requirements which apply if this specification is
   implemented (in addition to IPP/1.0 or higher).


   3.2.  Model Terminology

   See section 12.2 'Model Terminology' in [IPP-MOD].
































Hastings, McDonald            Expires 7 January 2001            [Page 6]


Internet Draft          IPP Get Resource Operations          7 July 2000



4.  Resource Operations

   The common semantics of all IPP Resource operations are the ones
   defined for all IPP operations in [IPP-MOD], e.g., "operation-id",
   "status-code", "attributes-charset", etc.

   See section 3.1 'Common Semantics' in [IPP-MOD].

   The following three Resource operations are REQUIRED for all IPP
   Printers to implement, if they implement Resource objects.



   4.1.  Get-Resource-Attributes Operation

   REQUIRED - for IPP Printers to implement.

   This operation allows an IPP Client to request the values of
   attributes of a Resource object instance and is similar to the
   Get-Job-Attributes operation (see section 3.2.5 in [IPP-MOD]).  The
   only differences are that the operation is directed at a Resource
   object instance rather than a Job object instance, there is a
   "resource-type" operation attribute required when querying a Resource
   object, and the returned attribute group is a set of Resource object
   attributes rather than a set of Job object attributes.

   For Resources, the possible names of attribute groups are:

   - 'resource-template':  the subset of the Resource Template
     attributes that the implementation supports for Resource objects.
   - 'resource-description':  the subset of the Resource Description
     attributes that the implementation supports for Resource objects.
   - 'all':  the special group 'all' that includes all attributes that
     the implementation supports for Resource objects.


   Since an IPP Client MAY request specific attributes or named groups,
   there is a potential that there is some overlap.  For example, if an
   IPP Client requests 'resource-create-time' and
   'resource-description', the IPP Client is actually requesting the
   "resource-create-time" attribute once by naming it explicitly, and
   once by inclusion in the 'resource-description' group.  In such
   cases, the IPP Printer object NEED NOT return the attribute only once
   in the response even if it is requested multiple times.  The IPP
   Client SHOULD NOT request the same attribute in multiple ways.

   It is NOT REQUIRED that a Resource object instance support all
   attributes belonging to a group (since some attributes are OPTIONAL).
   However it is REQUIRED that each Resource object instance support all

Hastings, McDonald            Expires 7 January 2001            [Page 7]


Internet Draft          IPP Get Resource Operations          7 July 2000

   group names.



   4.1.1.  Get-Resource-Attributes Request

   The following groups of attributes are part of the
   Get-Resource-Attributes Request when the request is directed at a
   Resource object:


   Group 1:  Operation Attributes

   Natural Language and Character Set:
     The "attributes-charset" and "attributes-natural-language"
     attributes as described in section 3.1.4.1 in [IPP-MOD].

   Target:
     The "printer-uri" (uri) operation attribute which is the target for
     this operation as described in section 3.1.5 in [IPP-MOD].

     ISSUE_1:  The target of all IPP Resource operations is always
     simply "printer-uri" and separate required operation attributes are
     used to specify resource type and name or ID.  This is like IPP
     Subscription objects but unlike the earlier IPP Job objects.
     Should we continue to follow the IPP Subscription object model?

   Resource Type:
     The "resource-type (type2 keyword)" attribute as described in
     section 5.2.1 in this document.

   Resource Name or ID:
     The "resource-name (name(127))" attribute as described in section
     5.2.2 in this document OR
     the "resource-id (integer(1:MAX))" attribute as described in
     section 5.2.3 in this document.

   Requesting User Name:
     The "requesting-user-name" (name(MAX)) attribute SHOULD be supplied
     by the IPP Client as described in section 8.3 in [IPP-MOD].

   "requested-attributes" (1setOf keyword):
     The IPP Client OPTIONALLY supplies this attribute.  The IPP Printer
     MUST support this attribute.  It is a set of attribute names and/or
     attribute group names in whose values the requester is interested.
     If the IPP Client omits this attribute, the IPP Printer MUST
     respond as if this attribute had been supplied with a value of
     'all'.




Hastings, McDonald            Expires 7 January 2001            [Page 8]


Internet Draft          IPP Get Resource Operations          7 July 2000



   4.1.2.  Get-Resource-Attributes Response

   The Printer object returns the following sets of attributes as part
   of the Get-Resource-Attributes Response:


   Group 1:  Operation Attributes

   Status Message:
     In addition to the REQUIRED status code returned in every response,
     the response OPTIONALLY includes a "status-message" (text(255))
     and/or a "detailed-status-message" (text(MAX)) operation attribute
     as described in sections 13 and 3.1.6 in [IPP-MOD].

   Natural Language and Character Set:
     The "attributes-charset" and "attributes-natural-language"
     attributes as described in section 3.1.4.2 in [IPP-MOD].  The
     "attributes-natural-language" MAY be the natural language of the
     Resource object, rather than the one requested.


   Group 2:  Unsupported Attributes

     See section 3.1.7 in [IPP-MOD] for details on returning Unsupported
     Attributes.

     The response NEED NOT contain the "requested-attributes" operation
     attribute with any supplied values (attribute keywords) that were
     requested by the IPP Client but are not supported by the IPP
     Printer.  If the Printer object does include unsupported attributes
     referenced in "requested-attributes" and such attributes include
     group names, such as 'all', the unsupported attributes MUST NOT
     include attributes described in this document but not supported by
     the implementation.


   Group 3:  Resource Object Attributes

     This is the set of requested attributes and their current values.
     The IPP Printer ignores (does not respond with) any requested
     attribute or value which is not supported or which is restricted by
     the security policy in force, including whether the requesting user
     is the user that created the Resource.  However, the IPP Printer
     MUST respond with the 'unknown' value for any supported attribute
     (including all REQUIRED attributes) for which the IPP Printer does
     not know the value, unless it would violate the security policy.
     See the description of the "out-of-band" values in the beginning of
     Section 4.1 in [IPP-MOD].


Hastings, McDonald            Expires 7 January 2001            [Page 9]


Internet Draft          IPP Get Resource Operations          7 July 2000




   4.2.  Get-Resource-Data Operation

   REQUIRED - for IPP Printers to implement.

   This operation allows an IPP Client to request the values of
   attributes of a Resource object instance AND the value of associated
   Resource data (i.e., this operation is like 'Print-Job').  This
   operation is a strict superset of the Get-Resource-Attributes
   operation above.  The only difference is that the operation returns
   Resource data in addition to Resource attributes.  This operation is
   only legal for certain values of "resource-type".

   Note:  This operation is defined (rather than overloading the
   'Get-Resource-Attributes' operation above) to simplify access control
   policies.  Note that many possible future Resource types (e.g,
   'font') have copyright and intellectual property considerations with
   respect to IPP Clients reading their associated data.


   4.2.1.  Get-Resource-Data Request

   See section 4.1.1 'Get-Resource-Attributes Request' in this document.

   The following groups of attributes are part of the Get-Resources
   request:


   Group 1:  Operation Attributes

     See 'Group 1:  Operation Attributes' in section 4.1.1
     'Get-Resource-Attributes Request'.


   4.2.2.  Get-Resource-Data Response

   See section 4.1.2 'Get-Resource-Attributes Response' in this
   document.


   Group 1:  Operation Attributes

     See 'Group 1:  Operation Attributes' in section 4.1.2
     'Get-Resource-Attributes Response'.


   Group 2:  Unsupported Attributes



Hastings, McDonald           Expires 7 January 2001            [Page 10]


Internet Draft          IPP Get Resource Operations          7 July 2000

     See 'Group 2:  Unsupported Attributes' in section 4.1.2
     'Get-Resource-Attributes Response'.


   Group 3:  Resource Object Attributes

     See 'Group 3:  Resource Object Attributes' in section 4.1.2
     'Get-Resource-Attributes Response'.

   Group 4:  Resource Data Content

     See section 5.3.6 'resource-data-present' in this document.
     See section 3.2.1.1 'Print-Job Request' in [IPP-MOD].

     The IPP Printer MUST return the Resource data content (if any) to
     the IPP Client, within the constraints of administratively
     configured access control policies and any applicable copyright or
     other intellectual property considerations.



   4.3.  Get-Resources Operation

   REQUIRED - for IPP Printers to implement.

   This operation allows an IPP Client to retrieve the list of Resource
   object instances (of a specified resource type) belonging to the
   target Printer object.  The IPP Client may also supply a list of
   Resource attribute names and/or attribute group names.  A group of
   Resource object attributes will be returned for each Resource object
   instance that is returned.

   This operation is similar to the Get-Resource-Attributes operation,
   except that this Get-Resources operation returns attributes from
   possibly more than one object.

   See section 3.2.6 'Get-Jobs Operation' in [IPP-MOD].



   4.3.1.  Get-Resources Request

   The IPP Client submits the Get-Resources request to an IPP Printer
   object.

   The following groups of attributes are part of the Get-Resources
   request:


   Group 1:  Operation Attributes


Hastings, McDonald           Expires 7 January 2001            [Page 11]


Internet Draft          IPP Get Resource Operations          7 July 2000


     See 'Group 1:  Operation Attributes' in section 4.1.1
     'Get-Resource-Attributes Request'.

   Resource Name or ID:
     [omitted]

   "limit" (integer(1:MAX)):
     [added]
     The IPP Client OPTIONALLY supplies this attribute.  The IPP Printer
     MUST MUST support this attribute.  It is an integer value that
     determines the maximum number of resources that an IPP Client will
     receive from the IPP Printer.


   Groups 2 to N:  Resource Filter Attributes
   [added]

     See 'Group 3:  Resource Object Attributes' in section 4.1.2
     'Get-Resource-Attributes Response'.

     This is the set of filter attributes and their filter values.  The
     IPP Printer ignores Resources which do not satisfy the specified
     filter.  A multi-valued filter attribute matches if the
     corresponding Resource object instance attribute contains all of
     the one or more values of the multi-valued filter attribute.

     The filter criteria in each Resource Filter Attribute group MUST
     all be true for a match (logical AND within the set).  But only ONE
     Resource Filter Group need be true for a match (logical OR across
     the sets).



   4.3.2.  Get-Resources Response

   The Printer object returns all of the Resource object instances, up
   to the number specified by the "limit" attribute, that match the
   criteria as defined by the filter attribute values supplied by the
   IPP Client in the request.  It is possible that no Resource objects
   are returned since there may literally be none at the Printer, or
   there may be no Resource objects that match the criteria supplied by
   the IPP Client.  If the IPP Client requests any Resource attributes
   at all, there is a set of Resource Object Attributes returned for
   each Resource object instance.

   It is not an error for the IPP Printer to return 0 Resources.  If the
   response returns 0 Resources because there are no Resources matching
   the criteria, and the request would have returned 1 or more Resources
   with a status code of 'successful-ok' if there had been Resources
   matching the criteria, then the status code for 0 Resources MUST be

Hastings, McDonald           Expires 7 January 2001            [Page 12]


Internet Draft          IPP Get Resource Operations          7 July 2000

   'successful-ok'.


   Group 1:  Operation Attributes

     See 'Group 1:  Operation Attributes' in section 4.3.1
     'Get-Resources Request'.


   Group 2:  Unsupported Attributes

     See 'Group 2:  Unsupported Attributes' in section 4.1.2
     'Get-Resource-Attributes Response'.


   Groups 3 to N:  Resource Object Attributes

     See 'Group 3:  Resource Object Attributes' in section 4.1.2
     'Get-Resource-Attributes Response'.

     Resource object instances are returned sorted by "resource-id".

   ISSUE_2:  Resource object instances are always returned sorted by
   "resource-id" and not by "resource-name" (more user-friendly).
   Should we add an operation attribute to control the sort order?



   4.4.  Resource Operation Response Status Codes

   client-error-not-authenticated
   client-error-not-authorized
   client-error-resource-type-not-supported
   client-error-resource-data-not-supported
   client-error-resource-data-not-present

















Hastings, McDonald           Expires 7 January 2001            [Page 13]


Internet Draft          IPP Get Resource Operations          7 July 2000



5.  Resource Attributes



   5.1.  Table of Required Resource Attributes

   All IPP Printers that support Resource objects MUST implement the
   following REQUIRED attributes defined in this specification (on the
   Resource object or the Printer object):

   Resource Attribute                      Resource Attribute Type
       Operation or Resource Group
       Printer Attribute                       Printer Attribute Type
   -----------------------------------     --------------------------
   resource-type                           (type2 keyword)
       resource-type                           [Operation group]
       resource-type-supported                 (1setOf type2 keyword)

   resource-name                           (name(127))
       resource-name                           [Operation group]
       [none]

   resource-id                             (integer(1:MAX))
       resource-id                             [Operation group]
       max-resources-supported                 (integer(0:MAX))

   resource-printer-uri                    (uri)
       printer-uri                             [Operation group]
       printer-uri-supported                   (1setOf uri)

   resource-charset                        (charset)
       attributes-charset                      [Operation group]
       charset-configured                      (charset)
       charset-supported                       (1setOf charset)

   resource-natural-language               (naturalLanguage)
       attributes-natural-language             [Operation group]
       natural-language-configured             (naturalLanguage)
       generated-natural-language-supported    (1setOf naturalLanguage)

   resource-data-present                   (boolean)
       resource-data-present                   [Resource group]
       resource-data-present-supported         (1setOf boolean)

   resource-data-uri                       (1setOf uri)
       resource-data-uri                       [Resource group]
       resource-data-schemes-supported         (1setOf uri)

   resource-data-k-octets                  (integer(0:MAX))

Hastings, McDonald           Expires 7 January 2001            [Page 14]


Internet Draft          IPP Get Resource Operations          7 July 2000

       resource-data-k-octets                  [Resource group]
       resource-data-k-octets-supported        (rangeOfInteger (0:MAX))

   resource-data-compression               (type3 keyword)
       resource-data-compression               [Resource group]
       compression-supported                   (1setOf type3 keyword)

   resource-create-user-name               (name(MAX))
       requesting-user-name                    [Operation group]
       [none]

   resource-create-date-time               (dateTime)
       resource-create-date-time               [Resource group]
       [none]

   resource-create-time                    (integer(0:MAX))
       [none]
       printer-current-time                    (integer(0:MAX))

   resource-expiration-time                (integer(0:MAX))
       [none]
       [printer-current-time + duration]

   resource-duration                       (integer(0:MAX))
       resource-duration                       [Resource group]
       resource-duration-default               (integer(0:MAX))
       resource-duration-supported             (rangeOfInteger(0:MAX))

   resource-persistence                    (boolean)
       resource-persistence                    [Resource group]
       resource-persistence-supported          (boolean)


   5.2.  Table of Optional Resource Attributes

   All IPP Printers that support Resource objects MAY implement the
   following OPTIONAL attributes defined in this specification (on the
   Resource object or the Printer object):

   Resource Attribute                      Resource Attribute Type
       Operation or Resource Group
       Printer Attribute                       Printer Attribute Type
   -----------------------------------     --------------------------
   resource-info                           (text(127))
       resource-info                           [Resource group]
       [none]
   resource-document-formats               (1setOf mimeMediaType)
       document-format-default                 (mimeMediaType)
       document-format-supported               (1setOf mimeMediaType)

   resource-os-types                       (1setOf type2 keyword)

Hastings, McDonald           Expires 7 January 2001            [Page 15]


Internet Draft          IPP Get Resource Operations          7 July 2000

       resource-os-types-default               (1setOf type2 keyword)
       resource-os-types-supported             (1setOf type2 keyword)

   resource-change-time                    (integer(0:MAX))
       [none]
       [none]

   resource-refresh-time                   (integer(0:MAX))
       [none]
       [none]


   5.3.  Resource Template Attributes



   5.3.1.  resource-info (text(127))

   OPTIONAL - for IPP Printers to implement.

   This attribute specifies descriptive information about this Resource
   object.  This may include manufacturer, version, copyright, etc.

   See section 4.4.6 'printer-info' and section 4.4.9
   'printer-make-and-model' in [IPP-MOD].



   5.3.2.  resource-charset (charset)

   REQUIRED - for IPP Printers to implement.

   This attribute specifies the charset of 'text' and 'name' attributes
   of the Resource and of textual data in the associated Resource data
   (if any).



   5.3.3.  resource-natural-language (naturalLanguage)

   REQUIRED - for IPP Printers to implement.

   This attribute specifies the natural language of 'text' and 'name'
   attributes of the Resource and of textual data in the associated
   Resource data (if any).







Hastings, McDonald           Expires 7 January 2001            [Page 16]


Internet Draft          IPP Get Resource Operations          7 July 2000



   5.3.4.  resource-document-formats (1setOf mimeMediaType)

   OPTIONAL - for IPP Printers to implement.

   This attribute specifies the list of document formats supported by
   the Resource.



   5.3.5.  resource-os-types (1setOf type2 keyword)

   OPTIONAL - for IPP Printers to implement.

   This attribute specifies the list of target operating system types of
   the Resource.

   See IANA registry of operating system names at [OS-TYPE].



   5.3.6.  resource-data-present (boolean)

   REQUIRED - for IPP Printers to implement.

   The attribute indicates whether or not a local copy of the Resource
   data is present at the IPP Printer.

   When "resource-data-present" is 'true' on a Resource object instance,
   it indicates that the IPP Printer has stored a local copy of the
   Resource data or has fetched a local copy of the Resource data that
   was specified by reference in "resource-data-uri".

   When "resource-data-present" is 'false' on a Resource object instance
   and "resource-data-uri" is empty, it indicates that there is no
   Resource data.

   When "resource-data-present" is 'false' on a Resource object instance
   and "resource-data-uri" is non-empty, it indicates that the IPP
   Printer has NOT yet fetched a local copy of the Resource data that
   was specified by reference and the value of "resource-data-k-octets"
   is unverified.

   See section 5.3.7 "resource-data-uri" in this document.
   See section 5.3.8 "resource-data-k-octets" in this document.






Hastings, McDonald           Expires 7 January 2001            [Page 17]


Internet Draft          IPP Get Resource Operations          7 July 2000



   5.3.7.  resource-data-uri (1setOf uri)

   REQUIRED - for IPP Printers to implement.

   This attribute contains the URI of associated Resource data (if any)
   as a reference.

   Lazy Refresh:
   An IPP Printer NEED NOT immediately fetch a local copy of the
   Resource data specified by reference in "resource-data-uri", but MUST
   set "resource-data-present" to 'false' until a local copy is fetched.

   When an IPP Printer does fetch a local copy of the Resource data, it
   MUST set (REQUIRED) "resource-data-present" to 'true', set (REQUIRED)
   "resource-data-k-octets" to the actual size, and update the timestamp
   in the (OPTIONAL) "resource-refresh-time" attribute.

   ISSUE_3:  This 'lazy refresh' behavior may have performance and
   'stale data' consequences for IPP Clients.  Because the manufacturer
   may also be slow to inform installed IPP Printers of a new version of
   a Resource (for update by means outside of this specification) the
   'stale data' problem may also apply to IPP Printers.  Should we add
   an operation attribute to prevent this 'lazy refresh' behavior?

   See section 5.3.6 "resource-data-present" in this document.
   See section 4.4.27 'reference-uri-schemes-supported' in [IPP-MOD].
   See section 3.2.2 'Print-URI' in [IPP-MOD].



   5.3.8.  resource-data-k-octets (integer(0:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute contains the size of associated Resource data (if
   any).

   See 'Lazy Refresh' in section 5.3.7 'resource-data-uri' for IPP
   Printer behavior with respect to "resource-data-k-octets".

   See section 5.3.6 "resource-data-present" in this document.



   5.3.9.  resource-data-compression (type3 keyword)

   REQUIRED - for IPP Printers to implement.

   This attribute identifies the compression of the associated Resource

Hastings, McDonald           Expires 7 January 2001            [Page 18]


Internet Draft          IPP Get Resource Operations          7 July 2000

   data (if any).

   See section 4.4.32 'compression-supported' in [IPP-MOD] for standard
   keyword values.



   5.3.10.  resource-create-date-time (dateTime)

   REQUIRED - for IPP Printers to implement.

   This attribute indicates the date and time at which the Resource
   object instance was created.

   Note:  This time SHOULD reflect the actual 'build date' of the
   Resource data rather than simply the 'install date' on the IPP
   Printer, because this is more informative for the end user.

   See section 4.4.30 'printer-current-time' in [IPP-MOD].
   See section 4.3.14.5 'date-time-at-creation' in [IPP-MOD].



   5.3.11.  resource-duration (integer(0:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute indicates length of the Resource object instance lease
   in seconds.

   See section 5.4.6 "resource-create-time" in this document.
   See section 5.4.9 "resource-expiration-time" in this document.



   5.3.12.  resource-persistence (boolean)

   REQUIRED - for IPP Printers to implement.

   This attribute indicates whether or not this Resource object instance
   is persistent (preserved by the IPP Printer across power cycles).

   A 'true' value specifies an infinite lease and supersedes
   "resource-duration" and "resource-expiration-time".  A 'false' value
   specifies a finite lease and selects use of "resource-duration" and
   "resource-expiration-time".

   See section 5.3.11 "resource-duration" in this document.
   See section 5.4.9 "resource-expiration-time" in this document.



Hastings, McDonald           Expires 7 January 2001            [Page 19]


Internet Draft          IPP Get Resource Operations          7 July 2000



   5.4.  Resource Description Attributes



   5.4.1.  resource-type (type2 keyword)

   REQUIRED - for IPP Printers to implement.

   This attribute identifies the type of this Resource object instance
   which determines additional Resource attributes specific to the named
   type.

   The following standard keyword values are defined:

       'driver':  The Resource contains client print support files
       (e.g., a driver) for an IPP Client (see section 6 'Driver
       Resource Type' in this document) for this IPP Printer.



   5.4.2.  resource-name (name(127))

   REQUIRED - for IPP Printers to implement.

   This attribute is the human-readable name of the Resource.  This name
   is more user-friendly than the integer "resource-id" attribute.

   This name MUST be unique among Resources of the SAME "resource-type".
   IPP Printers MUST not allow Resource object instances of the SAME
   "resource-type" with duplicate "resource-name" values.

   Note:  This attribute has been specified as REQUIRED (unlike
   "job-name") in the interests of ease-of-use.  IPP Printers are
   expected to implement large numbers of Resource objects and the
   guaranteed presence of the user-friendly name will benefit
   ease-of-use.

   See section 4.3.5 'job-name' in [IPP-MOD].



   5.4.3.  resource-id (integer(1:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute contains the locally unique ID of the Resource.  The
   IPP Printer, on creation of a new Resource (by means outside of this
   specification), generates an ID which identifies the new Resource on
   that Printer (but not globally).  The zero '0' value is not included

Hastings, McDonald           Expires 7 January 2001            [Page 20]


Internet Draft          IPP Get Resource Operations          7 July 2000

   to allow for compatibility with SNMP index values which also cannot
   be zero '0'.

   See section 4.3.2 'job-id' in [IPP-MOD].



   5.4.4.  resource-printer-uri (uri)

   REQUIRED - for IPP Printers to implement.

   This attribute identifies the IPP Printer that hosts this Resource
   object instance.

   See section 4.3.3 'job-printer-uri' in [IPP-MOD].



   5.4.5.  resource-create-user-name (name(MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute contains the name of the end user that created this
   Resource object instance.

   For factory-installed resources, "resource-create-user-name" MUST be
   set to the empty string to prevent namespace conflicts in end user
   networks.

   See section 4.3.6 'job-originating-user-name' in [IPP-MOD].



   5.4.6.  resource-create-time (integer(0:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute indicates the time at which the Resource object
   instance was created.

   Note:  This time SHOULD reflect the actual 'build time' of the
   Resource data rather than simply the 'install time' on the IPP
   Printer, because this is more informative for the end user.

   See section 4.4.29 'printer-up-time' in [IPP-MOD].
   See section 4.3.14.1 'time-at-creation' in [IPP-MOD].






Hastings, McDonald           Expires 7 January 2001            [Page 21]


Internet Draft          IPP Get Resource Operations          7 July 2000



   5.4.7.  resource-change-time (integer(0:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute indicates the time at which the Resource object
   instance was last changed.

   See section 5.4.6 "resource-create-time" in this document.
   See section 4.4.29 'printer-up-time' in [IPP-MOD].



   5.4.8.  resource-refresh-time (integer(0:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute indicates the time at which the Resource object
   instance was last refreshed (i.e., a local copy of the Resource data
   was made).

   See section 5.4.6 "resource-create-time" in this document.
   See section 4.4.29 'printer-up-time' in [IPP-MOD].



   5.4.9.  resource-expiration-time (integer(0:MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute indicates the time at which the Resource object
   instance lease will expire.

   See section 5.4.6 "resource-create-time" in this document.
   See section 5.3.11 "resource-duration" in this document.
   See section 4.4.29 'printer-up-time' in [IPP-MOD].
   See section 4.3.14.5 'date-time-at-creation' in [IPP-MOD].














Hastings, McDonald           Expires 7 January 2001            [Page 22]


Internet Draft          IPP Get Resource Operations          7 July 2000



6.  Driver Resource Type




   6.1.  Table of Required Driver Resource Attributes

   All IPP Printers that support Driver Resource objects MUST implement
   the following REQUIRED attributes defined in this specification (on
   the Driver Resource object or the Printer object):

   Driver Resource Attribute               Driver Attribute Type
       Operation or Resource Group
       Printer Attribute                       Printer Attribute Type
   -------------------------------         --------------------------
   driver-file-type                        (type2 keyword)
       driver-file-type                        [Resource group]
       driver-file-type-default                (type2 keyword)
       driver-file-type-supported              (1setOf type2 keyword)

   driver-file-name                        (name(MAX))
       driver-file-name                        [Resource group]
       [none]


   6.2.  Table of Optional Driver Resource Attributes

   All IPP Printers that support Driver Resource objects MAY implement
   the following OPTIONAL attributes defined in this specification (on
   the Driver Resource object or the Printer object):

   Driver Resource Attribute               Driver Attribute Type
       Operation or Resource Group
       Printer Attribute                       Printer Attribute Type
   -------------------------------         --------------------------
   driver-charset                          (1setOf charset)
       driver-charset                          [Resource group]
       charset-configured                      (charset)
       charset-supported                       (1setOf charset)

   driver-natural-language                 (1setOf naturalLanguage)
       driver-natural-language                 [Resource group]
       natural-language-configured             (naturalLanguage)
       generated-natural-language-configured   (1setOf naturalLanguage)






Hastings, McDonald           Expires 7 January 2001            [Page 23]


Internet Draft          IPP Get Resource Operations          7 July 2000



   6.3.  Driver Resource Template Attributes



   6.3.1.  driver-charset (1setOf charset)

   OPTIONAL - for IPP Printers to implement.

   This attribute specifies the list of client charsets
   supported by the Driver Resource (when installed on the client system



   6.3.2.  driver-natural-language (1setOf naturalLanguage)

   OPTIONAL - for IPP Printers to implement.

   This attribute specifies the list of client natural languages
   supported by the Driver Resource (when installed on the client system



   6.3.3.  driver-file-type (type2 keyword)

   REQUIRED - for IPP Printers to implement.

   This attribute specifies the client file type of
   this Driver Resource (when installed on the client system).

   The following standard keyword values are defined:

       'none': The Driver Resource contains client print support files i
       unspecified (opaque) format.

       'exec': The Driver Resource contains client print support files i
       native executable format of the operating system(s) specified in
       "resource-os-types" attribute, for example '.exe' on Microsoft sy

       'gpd': The Driver Resource contains client print support files in
       Microsoft GPD format.

       'java': The Driver Resource contains client print support files i

       'ppd': The Driver Resource contains client print support files in
       Adobe PPD format.

       'printcap': The Driver Resource contains client print support fil
       the UNIX 'printcap' format.


Hastings, McDonald           Expires 7 January 2001            [Page 24]


Internet Draft          IPP Get Resource Operations          7 July 2000


       'script': The Driver Resource contains client print support files
       native script format of the operating system(s) specified in the
       "resource-os-types" attribute, for example Bourne shell on UNIX s
       Note:  This type may be ambiguous on some target operating system

       'updf': The Driver Resource contains client print support files i
       (work-in-progress) PWG UPDF format.



   6.3.4.  driver-file-name (name(MAX))

   REQUIRED - for IPP Printers to implement.

   This attribute specifies the client file name of
   this Driver Resource (when installed on the client system)
   or the empty string (if none configured).
   If this Driver Resource contains multiple client print support files,
   then "driver-file-name" SHOULD specify an 'install directory path'.
































Hastings, McDonald           Expires 7 January 2001            [Page 25]


Internet Draft          IPP Get Resource Operations          7 July 2000



7.  Conformance Requirements



   7.1.  IPP Client Conformance Requirements

   IPP Clients MUST supply the required operation attributes in Resource
   operations.


   7.2.  IPP Printer Conformance Requirements



   7.2.1.  Resource Operations

   All IPP Printers that support Resource objects MUST implement
   the following REQUIRED operations defined in this specification:

   Resource Operation
   ------------------
   Get-Resources
   Get-Resource-Attributes
   Get-Resource-Data


























Hastings, McDonald           Expires 7 January 2001            [Page 26]


Internet Draft          IPP Get Resource Operations          7 July 2000



   7.2.2.  Resource Attributes

   See section 5.1 'Table of Required Resource Attributes' and section
   5.2 'Table of Optional Resource Attributes'.



   7.2.3.  Driver Resource Attributes

   See section 6.1 'Table of Required Driver Resource Attributes' and
   section 6.2 'Table of Optional Driver Resource Attributes'.







































Hastings, McDonald           Expires 7 January 2001            [Page 27]


Internet Draft          IPP Get Resource Operations          7 July 2000



8.  IANA Considerations

   See section 6 'IANA Considerations' in [IPP-MOD].



9.  Internationalization Considerations

   This IPP Resource Objects and Get Resource Operations specification
   continues support for the internationalization in [IPP-MOD]
   attributes containing text strings and names.

   See section 7 'Internationalization Considerations' in [IPP-MOD].



10.  Security Considerations

   This IPP Resource Objects and Get Resource Operations specification
   inherits the same security considerations for Resources as are
   specified for Jobs in [IPP-MOD].

   See section 8 'Security Considerations' in [IPP-MOD].



11.  Encodings of Additional Resource Tags

The section assigns values to new protocol tags as extensions to the
encoding defined in [IPP-PRO].

The resource-attributes-tag delimits Resource Template Attributes Groups
in requests and Resource Attributes Groups in responses.

Tag Value (Hex)     Tag Meaning
---------------     -----------
0x08                resource-attributes-tag

0x1E                Get-Resource-Attributes operation
0x1F                Get-Resource-Data operation
0x20                Get-Resources operation



12.  References

   See section 9 'References' in [IPP-MOD].

   [IPP-MOD] R. deBry, T. Hastings, R. Herriot, S. Isaacson, P. Powell.

Hastings, McDonald           Expires 7 January 2001            [Page 28]


Internet Draft          IPP Get Resource Operations          7 July 2000

   IPP/1.1 Model and Semantics, <draft-ietf-ipp-model-v11-07.txt>, May
   2000 (adopted by IESG as Proposed Standard in June 2000).

   [IPP-NOT] S. Isaacson, J. Martin, R. deBry, T. Hastings, M. Shepherd,
   R. Bergman.  IPP Event Notification Specification,
   <draft-ietf-ipp-not-spec-02.txt> (work-in-progress), March 2000.

   [OS-TYPE] IANA Registry of Operating System Names at
   ftp://ftp.isi.edu/in-notes/iana/assignments/operating-system-names.



13.  Authors' Addresses

   Tom Hastings
   Xerox Corporation
   701 S Aviation Blvd, MS 834-03E
   El Segundo, CA  90245

   Phone: +1 310-333-6413
   Email: hastings@cp10.es.xerox.com


   Ira McDonald
   High North Inc
   221 Ridge Ave
   Grand Marais, MI  49839

   Phone: +1 906-494-2434 or +1 906-494-2697
   Email: imcdonald@sharplabs.com
   Email: imcdonal@sdsp.mc.xerox.com





















Hastings, McDonald           Expires 7 January 2001            [Page 29]


Internet Draft          IPP Get Resource Operations          7 July 2000



14.  Appendix A - Change History

   [To be deleted before RFC publication]



   14.1.  7 July 2000 - draft-ietf-ipp-get-resource-00.txt

   initial version



15.  Full Copyright Statement

   Copyright (C) The Internet Society (2000).  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.











Hastings, McDonald           Expires 7 January 2001            [Page 30]