At the IPP WG meeting on 5/26-27 we discussed the following IPP/1.1 issue
raised by Carl Kugler as part of the IPP WG Last call concerning the error
information returned on a Print-URI or Send-URI response or later when a
document access error was detected. We also discussed the more general case
as well.
The editors will be updating the IPP/1.1 Model and Semantics document and
the Encoding and Transport document to reflect these agreements. Any
comments should be send to the mailing list by Thursday, June 10, 1999.
Then the resulting documents will be sent as Internet-Drafts on Friday, June
11, 1999 for review by the IESG as proposed standards.
ISSUE 35: What error code to return on Print-URI or Send-URI if document
not accessible?
2. Add OPTIONAL "job-document-access-errors (1setOf text)" Job Description
and "document-access-error (text(MAX))" Print-URI/Send-URI operation
attribute. For protocol errors, such as HTTP or FTP errors, standard values
would be the error code in parentheses, followed by the URL For example:
(XXX)
http://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-model-v11-990510.pdf
(XXX)
ftp://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-model-v11-990510.pdf
For example, the value: (404) http://... would indicate that the HTTP
server could not find the resource. (Note: most Internet protocols use
decimal error codes (unlike IPP), so the ASCII keyword representation is in
decimal.)
3. Instead of adding "debug-info", add the "detailed-status-message
(text(MAX))" operation attribute and "job-detailed-status-messages (1setOf
text(MAX))" Job Description attribute which contains detailed information
that is not localized by the client or Printer.
Reorganize section 3.1.6 Operation Status Codes and Messages and add:
3.1.6 Operation Response Status Code and Status Messages:
Every operation response includes a REQUIRED "status-code" parameter and an
OPTIONAL "status-message" operation attribute, and an OPTIONAL
"detailed-status-message" operation attribute. The Print-URI and Send-URI
response MAY include an OPTIONAL "document-access-error" operation
attribute.
3.1.6.1 "status-code" (type2 enum)
The REQUIRED "status-code" parameter provides information on the processing
of a request.
The status code is intended for use by automata. A client implementation of
IPP SHOULD convert status code values into any localized message that has
semantic meaning to the end user.
The "status-code" value is a numeric value that has semantic meaning. The
"status-code" syntax is similar to a "type2 enum" (see section 4.1 on
"Attributes Syntaxes") except that values can range only from 0x0000 to
0x7FFF. Section 13 describes the status codes, assigns the numeric values,
and suggests a corresponding status message for each status code for use by
the client when the user's natural language is English.
3.1.6.2 "status-message" (text(255))
The OPTIONAL "status-message" operation attribute provides a short textual
description of the status of the operation. The "status-message"
attribute's syntax is "text(255)", so the maximum length is 255 octets (see
section 4.1.1). The status message is intended for the human end user.
If a response does include a "status-message" attribute, an IPP client NEED
NOT examine or display the messages, however it SHOULD do so in some
implementation specific manner. The "status-message" is especially useful
for a later version of a Printer object to return as supplemental
information for the human user to accompany a status code that an earlier
version of a client might not understand.
If the Printer object supports the "status-message" operation attribute, the
Printer object MUST be able to generate this message in any of the natural
languages identified by the Printer object's
"generated-natural-language-supported" attribute (see the
"attributes-natural-language" operation attribute specified in section
3.1.4.1. Section 13 suggests the text for the status message returned by
the Printer for use with the English natural language.
As described in section 3.1.4.1 for any returned 'text' attribute, if there
is a choice for generating this message, the Printer object uses the natural
language indicated by the value of the "attributes-natural-language" in the
client request if supported, otherwise the Printer object uses the value in
the Printer object's own "natural-language-configured" attribute.
If the Printer object supports the "status-message" operation attribute, it
SHOULD use the REQUIRED 'utf-8' charset to return a status message for the
following error status codes (see section 13): 'client-error-bad-request',
'client-error-charset-not-supported', 'server-error-internal-error',
'server-error-operation-not-supported', and
'server-error-version-not-supported'. In this case, it MUST set the value
of the "attributes-charset" operation attribute to 'utf-8' in the error
response.
3.1.6.3 "detailed-status-message" (text(MAX))
The OPTIONAL "detailed-status-message" operation attribute provides
additional more detailed technical and implementation-specific information
about the operation. The "detailed-status-message" attribute's syntax is
"text(MAX)", so the maximum length is 1023 octets (see section 4.1.1). If
the Printer objects supports the "detailed-status-message" operation
attribute, neither the Printer nor the client localizes the message, since
it is intended for use by the system administrator or other experienced
technical persons. Clients MUST NOT attempt to parse the value of this
attribute. See "document-access-error" operation attribute (section
3.1.6.4) for additional errors that a program can process.
3.1.6.4 document-access-error(text(MAX))
This OPTIONAL operation attribute provides additional information about any
document access errors encountered by the Printer before it returned a
response to the Print-URI (section 3.2.2) or Send-URI (section 3.3.1)
operation. For errors in the protocol identified by the URI scheme in the
"document-uri" operation attribute, such as 'http:' or 'ftp:', the error
code is returned in parentheses, followed by the URI. For example:
(404)
http://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-model-v11-990510.pdf
Most Internet protocols use decimal error codes (unlike IPP), so the ASCII
error code representation is in decimal.
Suggested text for section 3.2.2 Print-URI Operation:
Replace the sentences:
See The Implementer's Guide [IPP-IIG] for suggested additional checks. The
Printer NEED NOT follow the reference and validate the contents of the
reference.
with:
The IPP Printer MAY validate the accessibility of the document as part of
the operation or subsequently. If the Printer determines an accessibility
problem before returning an operation response, it rejects the request and
returns the 'client-error-document-access-error' status code. The Printer
MAY also return a specific document access error code using the
"document-access-error" operation attribute (see section 3.1.6.4).
If the Printer determines this document accessibility problem after
accepting the request and returning an operation response with one of the
successful status codes, the Printer adds the 'document-access-error' value
to the job's "job-state-reasons" attribute and MAY populate the job's
"job-document-access-errors" Job Description attribute (see section 4.3.11).
See The Implementer's Guide [IPP-IIG] for suggested additional checks.
Add two new sections after section 4.3.9 job-state-message (text(MAX)):
4.3.10 job-detailed-status-messages (1setOf text(MAX))
This attribute specifies additional detailed and technical information about
the job. Neither the Printer nor the client localizes the message(s), since
they are intended for use by the system administrator or other experienced
technical persons. Clients MUST NOT attempt to parse the value of this
attribute. See "document-access-error" (section 4.3.11) for additional
errors that a program can process.
4.3.11 job-document-access-errors (1setOf text(MAX))
This attribute provides additional information about each document access
error for this job encountered by the Printer after it returned a response
to the Print-URI or Send-URI operation and subsequently attempted to access
document(s) supplied in the Print-URI or Send-URI operation. For errors in
the protocol that is identified by the URI scheme in the "document-uri"
operation attribute, such as 'http:' or 'ftp:', the error code is returned
in parentheses, followed by the URI. For example:
(404)
http://ftp.pwg.org/pub/pwg/ipp/new_MOD/ipp-model-v11-990510.pdf
Most Internet protocols use decimal error codes (unlike IPP), so the ASCII
error code representation is in decimal.