Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 2911

Internet Printing Protocol/1.1: Model and Semantics

Pages: 224
Obsoletes:  2566
Obsoleted by:  8011
Updated by:  33803382399639957472
Part 4 of 9 – Pages 66 to 91
First   Prev   Next

ToP   noToC   RFC2911 - Page 66   prevText

3.3.2 Send-URI Operation

This OPTIONAL operation is identical to the Send-Document operation (see section 3.3.1) except that a client MUST supply a URI reference ("document-uri" operation attribute) rather than the document data itself. If a Printer object supports this operation, clients can use both Send-URI or Send-Document operations to add new documents to an existing multi-document Job object. However, if a client needs to indicate that the previous Send-URI or Send-Document was the last document, the client MUST use the Send-Document operation with no document data and the "last-document" flag set to 'true' (rather than using a Send-URI operation with no "document-uri" operation attribute). If a Printer object supports this operation, it MUST also support the Print-URI operation (see section 3.2.2). The Printer object MUST validate the syntax and URI scheme of the supplied URI before returning a response, just as in the Print-URI operation. The IPP Printer MAY validate the accessibility of the document as part of the operation or subsequently (see section 3.2.2).

3.3.3 Cancel-Job Operation

This REQUIRED operation allows a client to cancel a Print Job from the time the job is created up to the time it is completed, canceled, or aborted. Since a Job might already be printing by the time a Cancel-Job is received, some media sheet pages might be printed before the job is actually terminated. The IPP object MUST accept or reject the request based on the job's current state and transition the job to the indicated new state as follows:
ToP   noToC   RFC2911 - Page 67
       Current "job-    New "job-     IPP object's response status
           state"         state"             code and action:

      'pending'       'canceled'     'successful-ok'
      'pending-held'  'canceled'     'successful-ok'
      'processing'    'canceled'     'successful-ok'
      'processing'    'processing'   'successful-ok'  See Rule 1
      'processing'    'processing'   'client-error-not-possible'
                                     See Rule 2
      'processing-    'canceled'     'successful-ok'
      stopped'
      'processing-    'processing-   'successful-ok'  See Rule 1
      stopped'        stopped'
      'processing-    'processing-   'client-error-not-possible'
      stopped'        stopped'       See Rule 2
      'completed'     'completed'    'client-error-not-possible'
      'canceled'      'canceled'     'client-error-not-possible'
      'aborted'       'aborted'      'client-error-not-possible'

   Rule 1:  If the implementation requires some measurable time to
   cancel the job in the 'processing' or 'processing-stopped' job
   states, the IPP object MUST add the 'processing-to-stop-point' value
   to the job's "job-state-reasons" attribute and then transition the
   job to the 'canceled' state when the processing ceases (see section
   4.3.8).

   Rule 2:  If the Job object already has the 'processing-to-stop-point'
   value in its "job-state-reasons" attribute, then the Printer object
   MUST reject a Cancel-Job operation.

   Access Rights: The authenticated user (see section 8.3) performing
   this operation must either be the job owner or an operator or
   administrator of the Printer object (see Sections 1 and 8.5).
   Otherwise, the IPP object MUST reject the operation and return:
    'client-error-forbidden', 'client-error-not-authenticated', or
   'client-error-not-authorized' as appropriate.

3.3.3.1 Cancel-Job Request
The following groups of attributes are part of the Cancel-Job Request: 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.
ToP   noToC   RFC2911 - Page 68
      Target:
         Either (1) the "printer-uri" (uri) plus "job-id"
         (integer(1:MAX))or (2) the "job-uri" (uri) operation
         attribute(s) which define the target for this operation as
         described in section 3.1.5.

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

      "message" (text(127)):
         The client OPTIONALLY supplies this attribute.  The Printer
         object OPTIONALLY supports this attribute. It is a message to
         the operator.  This "message" attribute is not the same as the
         "job-message-from-operator" attribute.  That attribute is used
         to report a message from the operator to the end user that
         queries that attribute.  This "message" operation attribute is
         used to send a message from the client to the operator along
         with the operation request.  It is an implementation decision
         of how or where to display this message to the operator (if at
         all).

3.3.3.2 Cancel-Job Response
The following sets of attributes are part of the Cancel-Job 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. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes. Once a successful response has been sent, the implementation guarantees that the Job will eventually end up in the 'canceled' state. Between the time of the Cancel-Job operation is accepted and when the job enters the 'canceled' job-state (see section 4.3.7), the "job-state-reasons" attribute SHOULD contain the 'processing-to- stop-point'
ToP   noToC   RFC2911 - Page 69
   value which indicates to later queries that although the Job might
   still be 'processing', it will eventually end up in the
   'canceled' state, not the 'completed' state.

3.3.4 Get-Job-Attributes Operation

This REQUIRED operation allows a client to request the values of attributes of a Job object and it is almost identical to the Get- Printer-Attributes operation (see section 3.2.5). The only differences are that the operation is directed at a Job object rather than a Printer object, there is no "document-format" operation attribute used when querying a Job object, and the returned attribute group is a set of Job object attributes rather than a set of Printer object attributes. For Jobs, the possible names of attribute groups are: - 'job-template': the subset of the Job Template attributes that apply to a Job object (the first column of the table in Section 4.2) that the implementation supports for Job objects. - 'job-description': the subset of the Job Description attributes specified in Section 4.3 that the implementation supports for Job objects. - 'all': the special group 'all' that includes all attributes that the implementation supports for Job objects. Since a client MAY request specific attributes or named groups, there is a potential that there is some overlap. For example, if a client requests, 'job-name' and 'job-description', the client is actually requesting the "job-name" attribute once by naming it explicitly, and once by inclusion in the 'job-description' group. In such cases, the Printer object NEED NOT return the attribute only once in the response even if it is requested multiple times. The client SHOULD NOT request the same attribute in multiple ways. It is NOT REQUIRED that a Job object support all attributes belonging to a group (since some attributes are OPTIONAL). However it is REQUIRED that each Job object support all these group names.
3.3.4.1 Get-Job-Attributes Request
The following groups of attributes are part of the Get-Job-Attributes Request when the request is directed at a Job object:
ToP   noToC   RFC2911 - Page 70
   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.

      Target:
        Either (1) the "printer-uri" (uri) plus "job-id"
        (integer(1:MAX)) or (2) the "job-uri" (uri) operation
        attribute(s) which define the target for this operation as
        described in section 3.1.5.

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

      "requested-attributes" (1setOf keyword):
        The client OPTIONALLY supplies this attribute.  The IPP object
        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 client omits this attribute, the IPP object
        MUST respond as if this attribute had been supplied with a value
        of 'all'.

3.3.4.2 Get-Job-Attributes Response
The Printer object returns the following sets of attributes as part of the Get-Job-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. Natural Language and Character Set: The "attributes-charset" and "attributes-natural-language" attributes as described in section 3.1.4.2. The "attributes- natural-language" MAY be the natural language of the Job object, rather than the one requested. Group 2: Unsupported Attributes See section 3.1.7 for details on returning Unsupported Attributes.
ToP   noToC   RFC2911 - Page 71
      The response NEED NOT contain the "requested-attributes" operation
      attribute with any supplied values (attribute keywords) that were
      requested by the client but are not supported by the IPP object.
      If the Printer object does return unsupported attributes
      referenced in the "requested-attributes" operation attribute and
      that attribute included group names, such as 'all', the
      unsupported attributes MUST NOT include attributes described in
      the standard but not supported by the implementation.

   Group 3: Job Object Attributes

      This is the set of requested attributes and their current values.
      The IPP object 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 submitted the job (job originating user) or
      not (see section 8).  However, the IPP object MUST respond with
      the 'unknown' value for any supported attribute (including all
      REQUIRED attributes) for which the IPP object 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.

3.3.5 Hold-Job Operation

This OPTIONAL operation allows a client to hold a pending job in the queue so that it is not eligible for scheduling. If the Hold-Job operation is supported, then the Release-Job operation MUST be supported, and vice-versa. The OPTIONAL "job-hold-until" operation attribute allows a client to specify whether to hold the job indefinitely or until a specified time period, if supported. The IPP object MUST accept or reject the request based on the job's current state and transition the job to the indicated new state as follows:
ToP   noToC   RFC2911 - Page 72
        Current "job-     New "job-state"   IPP object's response status
            state"                                 code and action:

      'pending'         'pending-held'     'successful-ok'  See Rule 1
      'pending'         'pending'          'successful-ok'  See Rule 2
      'pending-held'    'pending-held'     'successful-ok'  See Rule 1
      'pending-held'    'pending'          'successful-ok'  See Rule 2
      'processing'      'processing'       'client-error-not-possible'
      'processing-      'processing-       'client-error-not-possible'
      stopped'          stopped'
      'completed'       'completed'        'client-error-not-possible'
      'canceled'        'canceled'         'client-error-not-possible'
      'aborted'         'aborted'          'client-error-not-possible'

   Rule 1:  If the implementation supports multiple reasons for a job to
   be in the 'pending-held' state, the IPP object MUST add the 'job-
   hold-until-specified' value to the job's "job-state-reasons"
   attribute.

   Rule 2:  If the IPP object supports the "job-hold-until" operation
   attribute, but the specified time period has already started (or is
   the 'no-hold' value) and there are no other reasons to hold the job,
   the IPP object MUST make the job be a candidate for processing
   immediately (see Section 4.2.2) by putting the job in the 'pending'
   state.

   Note:  In order to keep the Hold-Job operation simple, such a request
   is rejected when the job is in the 'processing' or 'processing-
   stopped' states.  If an operation is needed to hold jobs while in
   these states, it will be added as an additional operation, rather
   than overloading the Hold-Job operation.  Then it is clear to clients
   by querying the Printer object's "operations-supported" (see Section
   4.4.15) and the Job object's "job-state" (see Section 4.3.7)
   attributes which operations are possible.

   Access Rights: The authenticated user (see section 8.3) performing
   this operation must either be the job owner or an operator or
   administrator of the Printer object (see Sections 1 and 8.5).
   Otherwise, the IPP object MUST reject the operation and return:
   'client-error-forbidden', 'client-error-not-authenticated', or
   'client-error-not-authorized' as appropriate.

3.3.5.1 Hold-Job Request
The groups and operation attributes are the same as for a Cancel-Job request (see section 3.3.3.1), with the addition of the following Group 1 Operation attribute:
ToP   noToC   RFC2911 - Page 73
      "job-hold-until" (type3 keyword | name(MAX)):
         The client OPTIONALLY supplies this Operation attribute.  The
         IPP object MUST support this operation attribute in a Hold-Job
         request, if it supports the "job-hold-until" Job template
         attribute in create operations.  See section 4.2.2.  The IPP
         object SHOULD support the "job-hold-until" Job Template
         attribute for use in job create operations with at least the
         'indefinite' value, if it supports the Hold-Job operation.
         Otherwise, a client cannot create a job and hold it immediately
         (without picking some supported time period in the future).

         If supplied and supported as specified in the Printer's "job-
         hold-until-supported" attribute, the IPP object copies the
         supplied operation attribute to the Job object, replacing the
         job's previous "job-hold-until" attribute, if present, and
         makes the job a candidate for scheduling during the supplied
         named time period.

         If supplied, but either the "job-hold-until" Operation
         attribute itself or the value supplied is not supported, the
         IPP object accepts the request, returns the unsupported
         attribute or value in the Unsupported Attributes Group
         according to section 3.1.7, returns the 'successful-ok-
         ignored-or-substituted-attributes, and holds the job
         indefinitely until a client performs a subsequent Release-Job
         operation.

         If the client (1) supplies a value that specifies a time period
         that has already started or the 'no-hold' value (meaning don't
         hold the job) and (2) the IPP object supports the "job-hold-
         until" operation attribute and there are no other reasons to
         hold the job, the IPP object MUST accept the operation and make
         the job be a candidate for processing immediately (see Section
         4.2.2).

         If the client does not supply a "job-hold-until" Operation
         attribute in the request, the IPP object MUST populate the job
         object with a "job-hold-until" attribute with the 'indefinite'
         value (if IPP object supports the "job-hold-until" attribute)
         and hold the job indefinitely, until a client performs a
         Release-Job operation.

3.3.5.2 Hold-Job Response
The groups and attributes are the same as for a Cancel-Job response (see section 3.3.3.2).
ToP   noToC   RFC2911 - Page 74

3.3.6 Release-Job Operation

This OPTIONAL operation allows a client to release a previously held job so that it is again eligible for scheduling. If the Hold-Job operation is supported, then the Release-Job operation MUST be supported, and vice-versa. This operation removes the "job-hold-until" job attribute, if present, from the job object that had been supplied in the create or most recent Hold-Job or Restart-Job operation and removes its effect on the job. The IPP object MUST remove the 'job-hold-until- specified' value from the job's "job-state-reasons" attribute, if present. See section 4.3.8. The IPP object MUST accept or reject the request based on the job's current state and transition the job to the indicated new state as follows: Current "job- New "job-state" IPP object's response status state" code and action: 'pending' 'pending' 'successful-ok' No effect on the job. 'pending-held' 'pending-held' 'successful-ok' See Rule 1 'pending-held' 'pending' 'successful-ok' 'processing' 'processing' 'successful-ok' No effect on the job. 'processing- 'processing- 'successful-ok' stopped' stopped' No effect on the job. 'completed' 'completed' 'client-error-not-possible' 'canceled' 'canceled' 'client-error-not-possible' 'aborted' 'aborted' 'client-error-not-possible' Rule 1: If there are other reasons to keep the job in the 'pending- held' state, such as 'resources-are-not-ready', the job remains in the 'pending-held' state. Thus the 'pending-held' state is not just for jobs that have the 'job-hold-until' applied to them, but are for any reason to keep the job from being a candidate for scheduling and processing, such as 'resources-are-not-ready'. See the "job-hold- until" attribute (section 4.2.2). Access Rights: The authenticated user (see section 8.3) performing this operation must either be the job owner or an operator or administrator of the Printer object (see Sections 1 and 8.5). Otherwise, the IPP object MUST reject the operation and return: 'client-error-forbidden', 'client-error-not-authenticated', or 'client-error-not-authorized' as appropriate.
ToP   noToC   RFC2911 - Page 75
   The Release-Job Request and Release-Job Response have the same
   attribute groups and attributes as the Cancel-Job operation (see
   section 3.3.3.1 and 3.3.3.2).

3.3.7 Restart-Job Operation

This OPTIONAL operation allows a client to restart a job that is retained in the queue after processing has completed (see section 4.3.7.2). The job is moved to the 'pending' or 'pending-held' job state and restarts at the beginning on the same IPP Printer object with the same attribute values. If any of the documents in the job were passed by reference (Print-URI or Send-URI), the Printer MUST re- fetch the data, since the semantics of Restart-Job are to repeat all Job processing. The Job Description attributes that accumulate job progress, such as "job-impressions-completed", "job-media-sheets- completed", and "job-k-octets-processed", MUST be reset to 0 so that they give an accurate record of the job from its restart point. The job object MUST continue to use the same "job-uri" and "job-id" attribute values. Note: If in the future an operation is needed that does not reset the job progress attributes, then a new operation will be defined which makes a copy of the job, assigns a new "job-uri" and "job-id" to the copy and resets the job progress attributes in the new copy only. The IPP object MUST accept or reject the request based on the job's current state, transition the job to the indicated new state as follows:
ToP   noToC   RFC2911 - Page 76
        Current "job-   New "job-state"    IPP object's response status
           state"                                code and action:

      'pending'        'pending'        'client-error-not-possible'
      'pending-held'   'pending-held'   'client-error-not-possible'
      'processing'     'processing'     'client-error-not-possible'
      'processing-     'processing-     'client-error-not-possible'
      stopped'         stopped'
      'completed'      'pending' or     'successful-ok' - job is started
                        'pending-held'   over.
      'completed'      'completed'      'client-error-not-possible' -
                                         see Rule 1
      'canceled'       'pending' or     'successful-ok' - job is started
                        'pending-held'   over.
      'canceled'       'canceled'       'client-error-not-possible' -
                                         see Rule 1
      'aborted'        'pending' or     'successful-ok' - job is started
                        'pending-held'   over.
      'aborted'        'aborted'        'client-error-not-possible' -
                                         see Rule 1

   Rule 1:  If the Job Retention Period has expired for the job in this
   state, then the IPP object rejects the operation.  See section
   4.3.7.2.

   Note:  In order to prevent a user from inadvertently restarting a job
   in the middle, the Restart-Job request is rejected when the job is in
   the 'processing' or 'processing-stopped' states.  If in the future an
   operation is needed to hold or restart jobs while in these states, it
   will be added as an additional operation, rather than overloading the
   Restart-Job operation, so that it is clear that the user intended
   that the current job not be completed.

   Access Rights: The authenticated user (see section 8.3) performing
   this operation must either be the job owner or an operator or
   administrator of the Printer object (see Sections 1 and 8.5).
   Otherwise, the IPP object MUST reject the operation and return:
   'client-error-forbidden', 'client-error-not-authenticated', or
   'client-error-not-authorized' as appropriate.

3.3.7.1 Restart-Job Request
The groups and attributes are the same as for a Cancel-Job request (see section 3.3.3.1), with the addition of the following Group 1 Operation attribute:
ToP   noToC   RFC2911 - Page 77
      "job-hold-until" (type3 keyword | name(MAX)):
         The client OPTIONALLY supplies this attribute.  The IPP object
         MUST support this Operation attribute in a Restart-Job request,
         if it supports the "job-hold-until" Job Template attribute in
         create operations.  See section 4.2.2.  Otherwise, the IPP
         object NEED NOT support the "job-hold-until" Operation
         attribute in a Restart-Job request.

         If supplied and supported as specified in the Printer's "job-
         hold-until-supported" attribute, the IPP object copies the
         supplied Operation attribute to the Job object, replacing the
         job's previous "job-hold-until" attribute, if present, and
         makes the job a candidate for scheduling during the supplied
         named time period.  See section 4.2.2.

         If supplied, but the value is not supported, the IPP object
         accepts the request, returns the unsupported attribute or value
         in the Unsupported Attributes Group according to section 3.1.7,
         returns the 'successful-ok-ignored-or-substituted-attributes'
         status code, and holds the job indefinitely until a client
         performs a subsequent Release-Job operation.

         If supplied, but the "job-hold-until" Operation attribute
         itself is not supported, the IPP object accepts the request,
         returns the unsupported attribute with the out-of-band
         'unsupported' value in the Unsupported Attributes Group
         according to section 3.1.7, returns the 'successful-ok-
         ignored-or-substituted-attributes' status code, and restarts
         the job, i.e., ignores the "job-hold-until" attribute.

         If the client (1) supplies a value that specifies a time period
         that has already started or the 'no-hold' value (meaning don't
         hold the job) and (2) the IPP object supports the "job-hold-
         until" operation attribute and there are no other reasons to
         hold the job, the IPP object makes the job a candidate for
         processing immediately (see Section 4.2.2).

         If the client does not supply a "job-hold-until" operation
         attribute in the request, the IPP object removes the "job-
         hold-until" attribute, if present, from the job.  If there are
         no other reasons to hold the job, the Restart-Job operation
         makes the job a candidate for processing immediately (see
         Section 4.2.2).
ToP   noToC   RFC2911 - Page 78
3.3.7.2 Restart-Job Response
The groups and attributes are the same as for a Cancel-Job response (see section 3.3.3.2). Note: In the future an OPTIONAL Modify-Job or Set-Job-Attributes operation may be specified that allows the client to modify other attributes before releasing the restarted job.

4. Object Attributes

This section describes the attributes with their corresponding attribute syntaxes and values that are part of the IPP model. The sections below show the objects and their associated attributes which are included within the scope of this protocol. Many of these attributes are derived from other relevant documents: - Document Printing Application (DPA) [ISO10175] - RFC 1759 Printer MIB [RFC1759] Each attribute is uniquely identified in this document using a "keyword" (see section 12.2.1) which is the name of the attribute. The keyword is included in the section header describing that attribute. Note: Not only are keywords used to identify attributes, but one of the attribute syntaxes described below is "keyword" so that some attributes have keyword values. Therefore, these attributes are defined as having an attribute syntax that is a set of keywords.

4.1 Attribute Syntaxes

This section defines the basic attribute syntax types that all clients and IPP objects MUST be able to accept in responses and accept in requests, respectively. Each attribute description in sections 3 and 4 includes the name of attribute syntax(es) in the heading (in parentheses). A conforming implementation of an attribute MUST include the semantics of the attribute syntax(es) so identified. Section 6.3 describes how the protocol can be extended with new attribute syntaxes. The attribute syntaxes are specified in the following sub-sections, where the sub-section heading is the keyword name of the attribute syntax inside the single quotes. In operation requests and responses each attribute value MUST be represented as one of the attribute syntaxes specified in the sub-section heading for the attribute. In addition, the value of an attribute in a response (but not in a
ToP   noToC   RFC2911 - Page 79
   request) MAY be one of the "out-of-band" values whose special
   encoding rules are defined in the "Encoding and Transport" document
   [RFC2910].   Standard "out-of-band" values are:

      'unknown': The attribute is supported by the IPP object, but the
         value is unknown to the IPP object for some reason.
      'unsupported': The attribute is unsupported by the IPP object.
         This value MUST be returned only as the value of an attribute
         in the Unsupported Attributes Group.
      'no-value': The attribute is supported by the Printer object, but
         the administrator has not yet configured a value.

   All attributes in a request MUST have one or more values as defined
   in Sections 4.2 to 4.4.  Thus clients MUST NOT supply attributes with
   "out-of-band" values for operations defined in this document.  All
   attributes in a response MUST have one or more values as defined in
   Sections 4.2 to 4.4 or a single "out-of-band" value.

   Most attributes are defined to have a single attribute syntax.
   However, a few attributes (e.g., "job-sheet", "media", "job-hold-
   until") are defined to have several attribute syntaxes, depending on
   the value.  These multiple attribute syntaxes are separated by the
   "|" character in the sub-section heading to indicate the choice.
   Since each value MUST be tagged as to its attribute syntax in the
   protocol, a single-valued attribute instance may have any one of its
   attribute syntaxes and a multi-valued attribute instance may have a
   mixture of its defined attribute syntaxes.

4.1.1 'text'

A text attribute is an attribute whose value is a sequence of zero or more characters encoded in a maximum of 1023 ('MAX') octets. MAX is the maximum length for each value of any text attribute. However, if an attribute will always contain values whose maximum length is much less than MAX, the definition of that attribute will include a qualifier that defines the maximum length for values of that attribute. For example: the "printer-location" attribute is specified as "printer-location (text(127))". In this case, text values for "printer-location" MUST NOT exceed 127 octets; if supplied with a longer text string via some external interface (other than the protocol), implementations are free to truncate to this shorter length limitation. In this document, all text attributes are defined using the 'text' syntax. However, 'text' is used only for brevity; the formal interpretation of 'text' is: 'textWithoutLanguage | textWithLanguage'. That is, for any attribute defined in this document using the 'text' attribute syntax, all IPP objects and
ToP   noToC   RFC2911 - Page 80
   clients MUST support both the 'textWithoutLanguage' and
   'textWithLanguage' attribute syntaxes.  However, in actual usage and
   protocol execution, objects and clients accept and return only one of
   the two syntax per attribute.  The syntax 'text' never appears "on-
   the-wire".

   Both 'textWithoutLanguage' and 'textWithLanguage' are needed to
   support the real world needs of interoperability between sites and
   systems that use different natural languages as the basis for human
   communication.  Generally, one natural language applies to all text
   attributes in a given request or response. The language is indicated
   by the "attributes-natural-language" operation attribute defined in
   section 3.1.4 or "attributes-natural-language" job attribute defined
   in section 4.3.20, and there is no need to identify the natural
   language for each text string on a value-by-value basis.  In these
   cases, the attribute syntax 'textWithoutLanguage' is used for text
   attributes.  In other cases, the client needs to supply or the
   Printer object needs to return a text value in a natural language
   that is different from the rest of the text values in the request or
   response.  In these cases, the client or Printer object uses the
   attribute syntax 'textWithLanguage' for text attributes (this is the
   Natural Language Override mechanism described in section 3.1.4).

   The 'textWithoutLanguage' and 'textWithLanguage' attribute syntaxes
   are described in more detail in the following sections.

4.1.1.1 'textWithoutLanguage'
The 'textWithoutLanguage' syntax indicates a value that is sequence of zero or more characters encoded in a maximum of 1023 (MAX) octets. Text strings are encoded using the rules of some charset. The Printer object MUST support the UTF-8 charset [RFC2279] and MAY support additional charsets to represent 'text' values, provided that the charsets are registered with IANA [IANA-CS]. See Section 4.1.7 for the definition of the 'charset' attribute syntax, including restricted semantics and examples of charsets.
4.1.1.2 'textWithLanguage'
The 'textWithLanguage' attribute syntax is a compound attribute syntax consisting of two parts: a 'textWithoutLanguage' part encoded in a maximum of 1023 (MAX) octets plus an additional 'naturalLanguage' (see section 4.1.8) part that overrides the natural language in force. The 'naturalLanguage' part explicitly identifies the natural language that applies to the text part of that value and that value alone. For any give text attribute, the 'textWithoutLanguage' part is limited to the maximum length defined for that 'text' attribute, and the 'naturalLanguage' part is always
ToP   noToC   RFC2911 - Page 81
   limited to 63 (additional) octets.  Using the 'textWithLanguage'
   attribute syntax rather than the normal 'textWithoutLanguage' syntax
   is the so-called Natural Language Override mechanism and MUST be
   supported by all IPP objects and clients.

   If the attribute is multi-valued (1setOf text), then the
   'textWithLanguage' attribute syntax MUST be used to explicitly
   specify each attribute value whose natural language needs to be
   overridden.  Other values in a multi-valued 'text' attribute in a
   request or a response revert to the natural language of the operation
   attribute.

   In a create request, the Printer object MUST accept and store with
   the Job object any natural language in the "attributes-natural-
   language" operation attribute, whether the Printer object supports
   that natural language or not.  Furthermore, the Printer object MUST
   accept and store any 'textWithLanguage' attribute value, whether the
   Printer object supports that natural language or not.  These
   requirements are independent of the value of the "ipp-attribute-
   fidelity" operation attribute that the client MAY supply.

   Example:  If the client supplies the "attributes-natural-language"
   operation attribute with the value: 'en' indicating English, but the
   value of the "job-name" attribute is in French, the client MUST use
   the 'textWithLanguage' attribute syntax with the following two
   values:

      'fr': Natural Language Override indicating French
      'Rapport Mensuel': the job name in French

   See the "Encoding and Transport" document [RFC2910] section 3.9 for
   the encoding of the two parts and Appendix A for a detailed example
   of the 'textWithLanguage' attribute syntax.

4.1.2 'name'

This syntax type is used for user-friendly strings, such as a Printer name, that, for humans, are more meaningful than identifiers. Names are never translated from one natural language to another. The 'name' attribute syntax is essentially the same as 'text', including the REQUIRED support of UTF-8 except that the sequence of characters is limited so that its encoded form MUST NOT exceed 255 (MAX) octets. Also like 'text', 'name' is really an abbreviated notation for either 'nameWithoutLanguage' or 'nameWithLanguage'. That is, all IPP objects and clients MUST support both the 'nameWithoutLanguage' and 'nameWithLanguage' attribute syntaxes. However, in actual usage and
ToP   noToC   RFC2911 - Page 82
   protocol execution, objects and clients accept and return only one of
   the two syntax per attribute.  The syntax 'name' never appears "on-
   the-wire".

   Only the 'text' and 'name' attribute syntaxes permit the Natural
   Language Override mechanism.

   Some attributes are defined as 'type3 keyword | name'.  These
   attributes support values that are either type3 keywords or names.
   This dual-syntax mechanism enables a site administrator to extend
   these attributes to legally include values that are locally defined
   by the site administrator.  Such names are not registered with IANA.

4.1.2.1 'nameWithoutLanguage'
The 'nameWithoutLanguage' syntax indicates a value that is sequence of zero or more characters encoded in a maximum of 255 (MAX) octets.
4.1.2.2 'nameWithLanguage'
The 'nameWithLanguage' attribute syntax is a compound attribute syntax consisting of two parts: a 'nameWithoutLanguage' part encoded in a maximum of 1023 (MAX) octets plus an additional 'naturalLanguage' (see section 4.1.8) part that overrides the natural language in force. The 'naturalLanguage' part explicitly identifies the natural language that applies to that name value and that name value alone. For any give text attribute, the 'textWithoutLanguage' part is limited to the maximum length defined for that 'text' attribute, and the 'naturalLanguage' part is always limited to 63 (additional) octets. Using the 'textWithLanguage' attribute syntax rather than the normal 'textWithoutLanguage' syntax is the so-called Natural Language Override mechanism and MUST be supported by all IPP objects and clients. The 'nameWithLanguage' attribute syntax behaves the same as the 'textWithLanguage' syntax. Using the 'textWithLanguage' attribute syntax rather than the normal 'textWithoutLanguage' syntax is the so-called Natural Language Override mechanism and MUST be supported by all IPP objects and clients. If a name is in a language that is different than the rest of the object or operation, then this 'nameWithLanguage' syntax is used rather than the generic 'nameWithoutLanguage' syntax. If the attribute is multi-valued (1setOf text), then the 'nameWithLanguage' attribute syntax MUST be used to explicitly specify each attribute value whose natural language needs to be overridden.
ToP   noToC   RFC2911 - Page 83
   Other values in a multi-valued 'name' attribute in a request or a
   response revert to the natural language of the operation attribute.

   In a create request, the Printer object MUST accept and store with
   the Job object any natural language in the "attributes-natural-
   language" operation attribute, whether the Printer object supports
   that natural language or not.  Furthermore, the Printer object MUST
   accept and store any 'nameWithLanguage' attribute value, whether the
   Printer object supports that natural language or not.  These
   requirements are independent of the value of the "ipp-attribute-
   fidelity" operation attribute that the client MAY supply.

   Example:  If the client supplies the "attributes-natural-language"
   operation attribute with the value:  'en' indicating English, but the
   "printer-name" attribute is in German, the client MUST use the
   'nameWithLanguage' attribute syntax as follows:

      'de':  Natural Language Override indicating German
      'Farbdrucker':  the Printer name in German

   See the "Encoding and Transport" document [RFC2910] section 3.9 for
   the encoding of the two parts and Appendix A for a detailed example
   of the 'nameWithLanguage' attribute syntax.

4.1.2.3 Matching 'name' attribute values
For purposes of matching two 'name' attribute values for equality, such as in job validation (where a client-supplied value for attribute "xxx" is checked to see if the value is among the values of the Printer object's corresponding "xxx-supported" attribute), the following match rules apply: 1. 'keyword' values never match 'name' values. 2. 'name' (nameWithoutLanguage and nameWithLanguage) values match if (1) the name parts match and (2) the Associated Natural- Language parts (see section 3.1.4.1) match. The matching rules are: a. the name parts match if the two names are identical character by character, except it is RECOMMENDED that case be ignored. For example: 'Ajax-letter-head-white' MUST match 'Ajax-letter-head-white' and SHOULD match 'ajax- letter-head-white' and 'AJAX-LETTER-HEAD-WHITE'.
ToP   noToC   RFC2911 - Page 84
         b. the Associated Natural-Language parts match if the shorter
            of the two meets the syntactic requirements of RFC 1766
            [RFC1766] and matches byte for byte with the longer.  For
            example, 'en' matches 'en', 'en-us' and 'en-gb', but matches
            neither 'fr' nor 'e'.

4.1.3 'keyword'

The 'keyword' attribute syntax is a sequence of characters, length: 1 to 255, containing only the US-ASCII [ASCII] encoded values for lowercase letters ("a" - "z"), digits ("0" - "9"), hyphen ("-"), dot ("."), and underscore ("_"). The first character MUST be a lowercase letter. Furthermore, keywords MUST be in U.S. English. This syntax type is used for enumerating semantic identifiers of entities in the abstract protocol, i.e., entities identified in this document. Keywords are used as attribute names or values of attributes. Unlike 'text' and 'name' attribute values, 'keyword' values MUST NOT use the Natural Language Override mechanism, since they MUST always be US-ASCII and U.S. English. Keywords are for use in the protocol. A user interface will likely provide a mapping between protocol keywords and displayable user- friendly words and phrases which are localized to the natural language of the user. While the keywords specified in this document MAY be displayed to users whose natural language is U.S. English, they MAY be mapped to other U.S. English words for U.S. English users, since the user interface is outside the scope of this document. In the definition for each attribute of this syntax type, the full set of defined keyword values for that attribute are listed. When a keyword is used to represent an attribute (its name), it MUST be unique within the full scope of all IPP objects and attributes. When a keyword is used to represent a value of an attribute, it MUST be unique just within the scope of that attribute. That is, the same keyword MUST NOT be used for two different values within the same attribute to mean two different semantic ideas. However, the same keyword MAY be used across two or more attributes, representing different semantic ideas for each attribute. Section 6.1 describes how the protocol can be extended with new keyword values. Examples of attribute name keywords: "job-name" "attributes-charset"
ToP   noToC   RFC2911 - Page 85
   Note:  This document uses "type1", "type2", and "type3" prefixes to
   the "keyword" basic syntax to indicate different levels of review for
   extensions (see section 6.1).

4.1.4 'enum'

The 'enum' attribute syntax is an enumerated integer value that is in the range from 1 to 2**31 - 1 (MAX). Each value has an associated 'keyword' name. In the definition for each attribute of this syntax type, the full set of possible values for that attribute are listed. This syntax type is used for attributes for which there are enum values assigned by other standards, such as SNMP MIBs. A number of attribute enum values in this document are also used for corresponding attributes in other standards [RFC1759]. This syntax type is not used for attributes to which the administrator may assign values. Section 6.1 describes how the protocol can be extended with new enum values. Enum values are for use in the protocol. A user interface will provide a mapping between protocol enum values and displayable user- friendly words and phrases which are localized to the natural language of the user. While the enum symbols specified in this document MAY be displayed to users whose natural language is U.S. English, they MAY be mapped to other U.S. English words for U.S. English users, since the user interface is outside the scope of this document. Note: SNMP MIBs use '2' for 'unknown' which corresponds to the IPP "out-of-band" value 'unknown'. See the description of the "out-of- band" values at the beginning of Section 4.1. Therefore, attributes of type 'enum' start at '3'. Note: This document uses "type1", "type2", and "type3" prefixes to the "enum" basic syntax to indicate different levels of review for extensions (see section 6.1).

4.1.5 'uri'

The 'uri' attribute syntax is any valid Uniform Resource Identifier or URI [RFC2396]. Most often, URIs are simply Uniform Resource Locators or URLs. The maximum length of URIs used as values of IPP attributes is 1023 octets. Although most other IPP attribute syntax types allow for only lower-cased values, this attribute syntax type conforms to the case-sensitive and case-insensitive rules specified in [RFC2396]. See also [IPP-IIG] for a discussion of case in URIs.
ToP   noToC   RFC2911 - Page 86

4.1.6 'uriScheme'

The 'uriScheme' attribute syntax is a sequence of characters representing a URI scheme according to RFC 2396 [RFC2396]. Though RFC 2396 requires that the values be case-insensitive, IPP requires all lower case values in IPP attributes to simplify comparing by IPP clients and Printer objects. Standard values for this syntax type are the following keywords: 'ipp': for IPP schemed URIs (e.g., "ipp:...") 'http': for HTTP schemed URIs (e.g., "http:...") 'https': for use with HTTPS schemed URIs (e.g., "https:...") (not on IETF standards track) 'ftp': for FTP schemed URIs (e.g., "ftp:...") 'mailto': for SMTP schemed URIs (e.g., "mailto:...") 'file': for file schemed URIs (e.g., "file:...") A Printer object MAY support any URI 'scheme' that has been registered with IANA [IANA-MT]. The maximum length of URI 'scheme' values used to represent IPP attribute values is 63 octets.

4.1.7 'charset'

The 'charset' attribute syntax is a standard identifier for a charset. A charset is a coded character set and encoding scheme. Charsets are used for labeling certain document contents and 'text' and 'name' attribute values. The syntax and semantics of this attribute syntax are specified in RFC 2046 [RFC2046] and contained in the IANA character-set Registry [IANA-CS] according to the IANA procedures [RFC2278]. Though RFC 2046 requires that the values be case-insensitive US-ASCII [ASCII], IPP requires all lower case values in IPP attributes to simplify comparing by IPP clients and Printer objects. When a character-set in the IANA registry has more than one name (alias), the name labeled as "(preferred MIME name)", if present, MUST be used. The maximum length of 'charset' values used to represent IPP attribute values is 63 octets. Some examples are: 'utf-8': ISO 10646 Universal Multiple-Octet Coded Character Set (UCS) represented as the UTF-8 [RFC2279] transfer encoding scheme in which US-ASCII is a subset charset. 'us-ascii': 7-bit American Standard Code for Information Interchange (ASCII), ANSI X3.4-1986 [ASCII]. That standard
ToP   noToC   RFC2911 - Page 87
         defines US-ASCII, but RFC 2045 [RFC2045] eliminates most of the
         control characters from conformant usage in MIME and IPP.
      'iso-8859-1':  8-bit One-Byte Coded Character Set, Latin Alphabet
         Nr 1 [ISO8859-1].  That standard defines a coded character set
         that is used by Latin languages in the Western Hemisphere and
         Western Europe.  US-ASCII is a subset charset.

   Some attribute descriptions MAY place additional requirements on
   charset values that may be used, such as REQUIRED values that MUST be
   supported or additional restrictions, such as requiring that the
   charset have US- ASCII as a subset charset.

4.1.8 'naturalLanguage'

The 'naturalLanguage' attribute syntax is a standard identifier for a natural language and optionally a country. The values for this syntax type are defined by RFC 1766 [RFC1766]. Though RFC 1766 requires that the values be case-insensitive US-ASCII [ASCII], IPP requires all lower case to simplify comparing by IPP clients and Printer objects. Examples include: 'en': for English 'en-us': for US English 'fr': for French 'de': for German The maximum length of 'naturalLanguage' values used to represent IPP attribute values is 63 octets.

4.1.9 'mimeMediaType'

The 'mimeMediaType' attribute syntax is the Internet Media Type (sometimes called MIME type) as defined by RFC 2046 [RFC2046] and registered according to the procedures of RFC 2048 [RFC2048] for identifying a document format. The value MAY include a charset, or other, parameter, depending on the specification of the Media Type in the IANA Registry [IANA-MT]. Although most other IPP syntax types allow for only lower-cased values, this syntax type allows for mixed-case values which are case-insensitive. Examples are: 'text/html': An HTML document 'text/plain': A plain text document in US-ASCII (RFC 2046 indicates that in the absence of the charset parameter MUST mean US-ASCII rather than simply unspecified) [RFC2046]. 'text/plain; charset=US-ASCII': A plain text document in US-ASCII [52, 56].
ToP   noToC   RFC2911 - Page 88
      'text/plain; charset=ISO-8859-1':  A plain text document in ISO
         8859-1 (Latin 1) [ISO8859-1].
      'text/plain; charset=utf-8':  A plain text document in ISO 10646
         represented as UTF-8 [RFC2279]
      'application/postscript':  A PostScript document [RFC2046]
      'application/vnd.hp-PCL':  A PCL document [IANA-MT] (charset
         escape sequence embedded in the document data)
      'application/pdf':  Portable Document Format - see IANA MIME Media
         Type registry
      'application/octet-stream': Auto-sense - see section 4.1.9.1

   The maximum length of a 'mimeMediaType' value to represent IPP
   attribute values is 255 octets.

4.1.9.1 Application/octet-stream -- Auto-Sensing the document format
One special type is 'application/octet-stream'. If the Printer object supports this value, the Printer object MUST be capable of auto-sensing the format of the document data using an implementation-dependent method that examines some number of octets of the document data, either as part of the create operation and/or at document processing time. During auto-sensing, a Printer may determine that the document-data has a format that the Printer doesn't recognize. If the Printer determines this problem before returning an operation response, it rejects the request and returns the 'client-error-document-format-not-supported' status code. If the Printer determines this problem after accepting the request and returning an operation response with one of the successful status codes, the Printer adds the 'unsupported-document-format' value to the job's "job-state-reasons" attribute. If the Printer object's default value attribute "document-format- default" is set to 'application/octet-stream', the Printer object not only supports auto-sensing of the document format, but will depend on the result of applying its auto-sensing when the client does not supply the "document-format" attribute. If the client supplies a document format value, the Printer MUST rely on the supplied attribute, rather than trust its auto-sensing algorithm. To summarize: 1. If the client does not supply a document format value, the Printer MUST rely on its default value setting (which may be 'application/octet-stream' indicating an auto-sensing mechanism). 2. If the client supplies a value other than 'application/octet- stream', the client is supplying valid information about the format of the document data and the Printer object MUST trust the client supplied value more than the outcome of applying an
ToP   noToC   RFC2911 - Page 89
         automatic format detection mechanism.  For example, the client
         may be requesting the printing of a PostScript file as a
         'text/plain' document.  The Printer object MUST print a text
         representation of the PostScript commands rather than interpret
         the stream of PostScript commands and print the result.
      3. If the client supplies a value of 'application/octet-stream',
         the client is indicating that the Printer object MUST use its
         auto-sensing mechanism on the client supplied document data
         whether auto-sensing is the Printer object's default or not.

   Note:  Since the auto-sensing algorithm is probabilistic, if the
   client requests both auto-sensing ("document-format" set to
   'application/octet-stream') and true fidelity ("ipp-attribute-
   fidelity" set to 'true'), the Printer object might not be able to
   guarantee exactly what the end user intended (the auto-sensing
   algorithm might mistake one document format for another), but it is
   able to guarantee that its auto-sensing mechanism be used.

   When a Printer performs auto-sensing of a document in a submitted
   job, it is RECOMMENDED that the Printer indicate to the user that
   such auto-sensing has occurred and which document-format was auto-
   sensed by printing that information on the job's job-start-sheet.

4.1.10 'octetString'

The 'octetString' attribute syntax is a sequence of octets encoded in a maximum of 1023 octets which is indicated in sub-section headers using the notation: octetString(MAX). This syntax type is used for opaque data.

4.1.11 'boolean'

The 'boolean' attribute syntax has only two values: 'true' and 'false'.

4.1.12 'integer'

The 'integer' attribute syntax is an integer value that is in the range from -2**31 (MIN) to 2**31 - 1 (MAX). Each individual attribute may specify the range constraint explicitly in sub-section headers if the range is different from the full range of possible integer values. For example: job-priority (integer(1:100)) for the "job-priority" attribute. However, the enforcement of that additional constraint is up to the IPP objects, not the protocol.
ToP   noToC   RFC2911 - Page 90

4.1.13 'rangeOfInteger'

The 'rangeOfInteger' attribute syntax is an ordered pair of integers that defines an inclusive range of integer values. The first integer specifies the lower bound and the second specifies the upper bound. If a range constraint is specified in the header description for an attribute in this document whose attribute syntax is 'rangeOfInteger' (i.e., 'X:Y' indicating X as a minimum value and Y as a maximum value), then the constraint applies to both integers.

4.1.14 'dateTime'

The 'dateTime' attribute syntax is a standard, fixed length, 11 octet representation of the "DateAndTime" syntax as defined in RFC 2579 [RFC2579]. RFC 2579 also identifies an 8 octet representation of a "DateAndTime" value, but IPP objects MUST use the 11 octet representation. A user interface will provide a mapping between protocol dateTime values and displayable user-friendly words or presentation values and phrases which are localized to the natural language and date format of the user, including time zone.

4.1.15 'resolution'

The 'resolution' attribute syntax specifies a two-dimensional resolution in the indicated units. It consists of 3 values: a cross feed direction resolution (positive integer value), a feed direction resolution (positive integer value), and a units value. The semantics of these three components are taken from the Printer MIB [RFC1759] suggested values. That is, the cross feed direction component resolution component is the same as the prtMarkerAddressabilityXFeedDir object in the Printer MIB, the feed direction component resolution component is the same as the prtMarkerAddressabilityFeedDir in the Printer MIB, and the units component is the same as the prtMarkerAddressabilityUnit object in the Printer MIB (namely, '3' indicates dots per inch and '4' indicates dots per centimeter). All three values MUST be present even if the first two values are the same. Example: '300', '600', '3' indicates a 300 dpi cross-feed direction resolution, a 600 dpi feed direction resolution, since a '3' indicates dots per inch (dpi).

4.1.16 '1setOf X'

The '1setOf X' attribute syntax is 1 or more values of attribute syntax type X. This syntax type is used for multi-valued attributes. The syntax type is called '1setOf' rather than just 'setOf' as a reminder that the set of values MUST NOT be empty (i.e., a set of
ToP   noToC   RFC2911 - Page 91
   size 0).  Sets are normally unordered.  However each attribute
   description of this type may specify that the values MUST be in a
   certain order for that attribute.



(page 91 continued on part 5)

Next Section