Keith,
Great stuff!
Thanks for doing it.
I have some minor comments and an issue or 2.
Tom
At 11:07 04/22/97 PDT, Keith Carter wrote:
>Attached is a proposal for status code defintions. I
>borrowed the design approach and applicable text from the
>HTTP 1.1 RFC (RFC 2068). If this proposal is incorporated
>into the IPP Model document, maybe we should include an
>acknowledgement to the authors of HTTP 1.1 in the document.
>>I reviewed this proposal with Roger deBry and mapped the
>proposal to Roger's most recent white paper on conformance.
>Finally, I mapped the status conditions to scenarios
>explicitly or implicitly defined in the IPP internet drafts
>and used examples to relate the status codes to certain
>scenarios when appropriate.
>>Enjoy!
>>Keith
>>================= STATUS CODE PROPOSAL =============
>>4.3 Status and Message
>>The Status element is a 3-digit integer result code of the
>attempt to understand and satisfy the request. The Message is
>intended to give a short textual description of the Status. The
>Status is intended for use by automata and the Message is
>intended for the human user. An IPP application (i.e. a browser,
>GUI, print driver or gateway) is not required to examine or
>display the Message.
>>The first digit of the Status defines the class of response. The
>last two digits do not have any categorization role. There are 4
>values for the first digit:
>> o 0xx: Success - The request was successfully received,
> understood, and accepted
>> o 1xx: Client Error - The request contained bad syntax or
> cannot be fulfilled
>> o 2xx: Server Error - The IPP Printer failed to fulfill an
> apparently valid request
>> o 3xx: Communication Error - An error in communications
> occured during the transmission of a request - the request
> cannot be fulfilled
>>The individual values of the numeric status codes defined for
>IPP, and an example set of corresponding Messages, are presented
>below. The messages listed here are only recommended -- they may
>be replaced by local equivalents without affecting the protocol.
>> Status = "000" ; OK
> | "001" ; OK Attribute Substitution/
> Attribute Ignored
(1) I suggest that this be two separate success codes, since the user
has to do different things depending on which condition to figure out
what went wrong. Also need to make the description optionally plural,
since there could be one or more:
| "001" ; Unimplemented Attribute(s) Ignored
| "002" ; Unsupported Attribute Value(s) Substituted
> | "100" ; Bad Request
> | "101" ; User Authentication Required
> | "102" ; Payment Required
> | "103" ; Forbidden Operation
> | "104" ; Operation Not Allowed
> | "105" ; Operation Not Authorized
> | "106" ; URL Not Found
> | "107" ; URL Gone
> | "108" ; URL Too Large
> | "109" ; Attribute Not Implemented/
> Attribute Value Not Supported
(2) I suggest that these be two separate codes. How about:
| "109" ; Some Attribute(s) Unimplemented
| "110" ; Some Attribute Value(s) Unsupported
> | "200" ; Internal Server Error
> | "201" ; Service Unavailable
> | "202" ; IPP Version Not Supported
(3) I thought we had been counseled by Larry Masinter and the HTTP crowd to
design the protocol so that new versions were upwards compatible with
older versions. Therefore, this error should not be an error. The operation
not implemented might be the error if a newer client tries to work with
an older server.
Alternatively, we could include this error, but with the text that
a conforming server shall NOT return it. It is there just in case,
a future verson of the standard needs a conforming Printer to return it
to an older client. At that time this sentence will be change to allow
a conforming Printer to return this error code.
> | "203" ; Operation Not Implemented
> | "204" ; Printer Error
> | "300" ; Communications Error
> | extension-code
>> extension-code = 3DIGIT
>> Message = *<TEXT, excluding CR, LF>
>>IPP status codes are extensible. IPP applications are not
(4) I think we need to make them type 2 keywords, correct?
(5) ISSUE: Do we also need a way to allow implementors to have private
error codes as well?
>required to understand the meaning of all registered status
>codes, though such understanding is obviously desirable.
>However, applications shall understand the class of any status
>code, as indicated by the first digit, and treat any unrecognized
>response as being equivalent to the x00 status code of that
>class, with the exception that an unrecognized response shall NOT
>be cached. For example, if an unrecognized status code of 131 is
>received by the IPP application, it can safely assume that there
>was something wrong with its request and treat the response as if
>it had received a 100 status code. In such cases, IPP
>applications should present to the user the Message returned with
>the response, since that Message is likely to include
>human-readable information which will explain the unusual status.
>>4.4 Status Definitions
>>Each Status is described below, including a description of which
>operation(s) it can follow and any metainformation required in
>the response.
>>4.4.1 Successful 0xx
>>This class of status code indicates that the client's request was
>successfully received, understood, and accepted.
>>4.4.1.1 000 OK
>>The request has succeeded. The information returned with the
>response is dependent on the operation, for example:
>> Print The Job is submitted for printing and
> the Job URL is returned in the response;
>> Cancel The Job is cancelled;
>> Get-Jobs The Jobs currently belonging to the
> Printer are returned in the response;
>> Get-Attributes The values for the attributes specified
> in the request are returned in the
> response.
>>On a Get-Attributes operation, if an IPP Printer encounters any
>attributes in the request that are not implemented, the Printer
>shall return this status and indicate in the response which
>attributes are not supported by the Printer.
>>On a Get-Jobs operation, if an IPP Printer encounters any
>attributes in the request that are not implemented and the values
>(if specified) for Job Owner and Job States are supported by the
>Printer, the Printer shall return this status and indicate in the
>response which attributes are not supported by the Printer.
>>An IPP application may examine the attributes in the response
>to determine which attributes are not implemented by the Printer.
>>4.4.1.2 001 OK Attribute Substitution/Attribute Ignored
>>The operation has succeeded. On a Print operation, the request
>specifies substitute-as-needed for the best-effort attribute. In
>response to the Print operation, the IPP Printer substituted a
>value for at least one attribute value that is not supported
>and/or ignored at least one attribute that is not implemented.
(1') See above discussion on making this two separate warnings:
001 Unimplemented Attribute(s) Ignored
002 Unsuppored Attribute Value(s) Substituted
>>An IPP application may examine the attributes and/or attribute values
>in the response to determine which attributes are not implemented
>and/or which attribute values are not supported by a Printer.
(7) This previous paragraph only applies to Gets, not Print operation.
Need to clarify. The previous paragraph specifies the Print operation.
>>In practice, an IPP application should avoid this situation by
>querying an IPP object for its valid attributes and values
>before performing an operation on the object.
>>4.4.2 Client Error 1xx
>>The 1xx class of status code is intended for cases in which the
>client seems to have erred. IPP applications should display any
>included Message to the end-user. Unless otherwise noted, these
>status codes apply to all operations.
>>4.4.2.1 100 Bad Request
>>The request could not be understood by the IPP Printer due to
>malformed syntax. The IPP application should not repeat the
>request without modifications.
>>4.4.2.2 101 User Authentication Required
>>The request requires user authentication.
>>4.4.2.3 102 Payment Required
>>This request requires payment by the end-user to perform the
>Print operation.
>>4.4.2.4 103 Forbidden Operation
>>The IPP Printer understood the request, but is refusing to fulfill
>it. Authorization will not help and the request should not be
>repeated. This status code is commonly used when the IPP Printer
>does not wish to reveal exactly why the request has been refused
>or when no other response is applicable.
>>4.4.2.5 104 Operation Not Allowed
>>The operation is not allowed for the object identified by the
>URL. For example, a Print operation is not allowed on a Job
>object specified by a Job URL.
>>4.4.2.6 105 Operation Not Authorized
>>The request requires that an end-user have access to an object
>and the authorization to perform an operation on the object. For
>example, an end-user might be authorized to list others' Jobs but
>the end-user is not authorized to cancel others' Jobs. For
>another example, an end-user might not have access to a Printer
>either because the end-user is not defined in the access control
>list for the Printer or the end-user does not have access to the
>Printer across a firewall.
>>4.4.2.7 106 URL Not Found
>>The server name in the URL is not found or the server cannot find
>the object specified in the URL. No indication is given of
>whether the condition is temporary or permanent.
>>An application should use a Directory Service to return a list of
>valid Printer URLs and use the Get-Jobs operation to return a list
>of valid Job URLs for a Printer so an end-user can select from a
>valid list of URLs.
>>4.4.2.8 107 URL Gone
>>The requested object is no longer available to the server specified
>in the URL. This condition should be considered permanent. Clients
>with link editing capabilities should delete references to the URL
>after user approval. This response is cachable.
>>This response is primarily intended to notify the recipient that
>the resource is intentionally unavailable and that the server
>owners desire that remote links to that resource be removed. Such
>an event is common for resources belonging to individuals no
>longer working at a site.
>>4.4.2.9 108 URL Too Large
>>The server specified in the URL is refusing to service the request
>because the URL is longer than the server is willing to interpret.
>This condition is only likely to occur when an IPP application allows
>an end-user to type an invalid URL for an IPP object and then
>specifies that URL on an operation. An application should use a
>Directory Service to return a list of valid Printer URLs and use
>the Get-Jobs operation to return a list of valid Job URLs for a
>Printer so an end-user can select from a valid list of URLs.
>>4.4.2.10 109 Attribute Not Implemented/Attribute Value Not Supported
>>For a Print operation, if the IPP Printer does not implement at
>least one attribute and/or at least one attribute value in the
>request and either the request specifies do-not-substitute for
>the best-effort attribute or the Printer cannot process the
>request correctly, the Printer shall return this status and
>indicate in the response which attributes and/or attribute values
>are not supported by the Printer.
(2') See discusson above that suggests that we need two errors here:
109 Some Attribute(s) Not Implemented
110 Some Attribute Value(s) Not Supported
(6) Again, while this is good for the user, the group has agreed to require
the Printer to return the attributes in question in the response
to a Print operation. But its easy for a query response.
(7) Here is a case where the description needs to be clarified for Print
vs Get-Attributes/Get-Jobs operations.
>>For example, if an IPP Printer can only support 1 Document per
>Job and the Printer receives multiple documents in a Print
>operation, the Printer shall return this status.
(8) ISSUE:
Since multiple documents isn't indicated by an attribute, but rather
by the content that is sent, we need a distinct error code:
multiple-documents-not-supported
(if we allow a conforming Printer to reject a multiple document
job in a Print operation.)
> For another
>example, if the Print operation specifies do-not-substitute,
>the request requires A4 paper and that paper size is not
>available on the Printer, the Printer shall return this status.
(9) The word "available" has not been defined and has caused a lot of
confusing in the past as to whether it means "supported" (which could
be ready or not ready) or "ready" (can be used without human intervention).
>>For a Get-Jobs operation, if the IPP Printer does not support at
>least one attribute value for Job Owner and/or Job States in
>the request, the Printer shall return this status and indicate
>in the response which attributes and/or attribute values are not
>supported by the Printer.
>>An IPP application may examine the attributes and/or attribute values
>in the response to determine which attributes are not implemented
>and/or which attribute values are not supported by a Printer.
>>In practice, an IPP application should avoid this situation by
>querying an IPP Printer for its valid attributes and values
>before performing a Print operation on the Printer.
>>4.4.3 Server Error 2xx
>>Response status codes beginning with the digit "2" indicate cases
>in which the IPP Printer is aware that it has erred or is
>incapable of performing the request. IPP applications should
>display any included Message to the end-user. Unless otherwise
>noted, these status codes apply to all operations.
>>4.4.3.1 200 Internal Server Error
>>The IPP Printer encountered an unexpected condition which
>prevented it from fulfilling the request.
>>4.4.3.2 201 Service Unavailable
>>The IPP Printer is currently unable to handle the request due to a
>temporary overloading or maintenance of the Printer. The
>implication is that this is a temporary condition which will be
>alleviated after some delay. If known, the length of the delay
>may be indicated in the Message. If no delay is given, the IPP
>application should handle the response as it would for a 200
>response.
>>4.4.3.3 202 IPP Version Not Supported
>>The IPP Printer does not support, or refuses to support, the IPP
>protocol version that was used in the request message. The IPP
>Printer is indicating that it is unable or unwilling to complete
>the request using the same major version as the client other than
>with this error message. The response should contain a Message
>describing why that version is not supported and what other
>versions are supported by that IPP Printer.
(3') See discussion above that we shouldn't have such an error, unless
we make an incompatible change between versions of the protocol.
>4.4.3.4 203 Operation Not Implemented
>>The IPP Printer does not support the functionality required to
>fulfill the request. This is the appropriate response when the
>IPP Printer does not recognize an operation and is not capable of
>supporting it for any object.
>>4.4.3.5 204 Printer Error
>>A printer error, such as a paper jam or a memory overflow (i.e.
>the document data exceeds the memory of the Printer) occurs while
>the IPP Printer processes a Print operation. The response shall
>contain the Job Status with the specific error and should contain
>a Message describing the error. An IPP application should check
>the Job Status in the response for the specific error.
>>4.4.4 Communication Error 3xx
>>Response status codes beginning with the digit "3" indicate cases
>in which there are errors from the underlying transport services
>used to communicate IPP requests and responses between IPP
>clients and IPP servers. IPP applications should display any
>included Message to the end-user. Unless otherwise noted, these
>status codes apply to all operations.
>>There will be a set of error conditions that are specific to the
>transport service selected by an IPP implementor. An IPP
>implementor may choose to map all such transport errors to status
>code "300" or define additional status codes for the "3xx" class.
>>4.4.4.1 300 Communication Error
>>The IPP client encountered an unexpected condition which
>prevented it from fulfilling the request.
>>>>