This note contains:
1) Proposed status code keyword definitions for the Model document
2) Mapping of Bob Herriot's analysis of HTTP 1.1 to Model status
codes
3) Issues (and in some cases proposed answers)
Note that I added a prefix "OK" or "error" to each status keyword so an
IPP application can detect the class of status code upfront.
Enjoy,
Keith
1.0 PROPOSED STATUS CODE DEFINITIONS FOR THE MODEL DOCUMENT
-----------------------------------------------------------
4.3 Status and Message
The Status code provides information on the results of a request.
The Message provides 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.
4.4 Status Codes (type2 keyword)
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 Status Codes
This class of status code indicates that the client's request was
successfully received, understood, and accepted.
4.4.1.1 OK
The request has succeeded. The information returned with the
response is dependent on the operation, for example:
CreateJob A Job is created and the Job URL is returned
in the response;
SendDocument Data is written to a Document in a Job;
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.
4.4.1.2 OK-attribute-not-implemented (NEW)
The operation has succeeded.
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.
4.4.1.3 OK-attribute-ignored-or-value-substituted
The operation has succeeded. On a CreateJob operation, the request
specifies substitute-as-needed for the best-effort attribute. In
response to the CreateJob, 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.
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 Error Status Codes
This class of status code is intended for cases in which there is
an error. 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 error-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 error-user-authentication-required
The request requires user authentication.
4.4.2.3 error-payment-required
This request requires payment by the end-user to perform the
CreateJob operation.
4.4.2.4 error-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 error-operation-not-allowed
The operation is not allowed for the object identified by the
URL. For example, a CreateJob operation is not allowed on a Job
object specified by a Job URL.
4.4.2.6 error-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 error-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 GetJobs 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 error-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 error-URL-too-long
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 error-attribute-not-implemented-or-value-not-supported
For a CreateJob 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.
For example, if the Print operation specifies do-not-substitute
for the best-effort attribute, the request requires A4 paper and
that paper size is not supported by the Printer, the Printer shall
return this status.
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.
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.2.11 error-internal-server-error
The IPP Printer encountered an unexpected condition which
prevented it from fulfilling the request.
4.4.2.12 error-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.2.13 error-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.
A conforming IPP client shall specify the valid version for IPP 1.0
on each request. A conforming IPP server shall not return this
status code to a conforming IPP 1.0 client. An IPP server shall
return this status code to a non-conforming IPP client.
4.4.2.14 error-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.2.15 error-printer-error
A printer error, such as a paper jam, occurs while the IPP Printer
processes a SendDocument 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.2.16 error-write-fault (NEW)
A write error, such as a memory overflow (i.e. the document data
exceeds the memory of the Printer) or a disk full condition, occurs
while the IPP Printer processes a SendDocument operation. The
IPP application must check the Bytes Written in the response to
determine how many bytes were actually successfully processed by the
Printer.
4.4.2.17 error-document-rejected (NEW)
The Printer cannot process a Document in a Job for one of the
following reasons: (1) the document-format of a document is not
supported by the Printer (2) the document exceeds number-of-documents
supported by the Printer. For example, if a Job contains multiple
documents and the Printer supports the document-format(s) of some,
but not all, of these documents, then the Printer returns this Status
when it first encounters an unsupported document-format.
4.4.2.18 error-unknown (NEW)
The IPP client encountered an unexpected condition which prevented
it from fulfilling the request. The response should contain a
Message describing the error.
2.0 UPDATE TO BOB'S ANALYSIS OF HTTP 1.1 AND MODEL STATUS CODES
---------------------------------------------------------------
This section is a copy of Bob's note with his analysis of my original
proposal except that I have replaced the IPP status code values with
IPP status code keywords. I have tried to capture differences in the
Issues section of this note.
Marks in column 1 denote:
x should be in IPP Version 1.0
f may be in a future version, do don't reuse error code
i new concept in IPP not in HTTP (these error codes start at x51)
<blank> HTTP codes that IPP probably doesn't need but don't
suggest reusing them
A k in column 2 indicates the status code is in Keith's proposal as
defined in this note.
The proposed IPP status code keyword is to the right of its
corresponding HTTP 1.1 status code where appropriate.
Informational 1xx
f 100 Continue
f 101 Switching Protocols
Successful 2xx
xk 200 OK -> OK
x 201 Created (for CreateJob instead of 200) -> OK (see Issue #1)
f 202 Accepted
203 Non-Authoritative Information
x 204 No Content (e.g. CancelJob) -> OK (see Issue #1)
205 Reset Content
206 Partial Content
ik 251 Attribute Substitution/Ignored ->
OK-attribute-ignored-or-value-substituted
Redirection 3xx
300 Multiple Choices
f 301 Moved Permanently
f 302 Moved Temporarily
303 See Other
f 304 Not Modified
305 Use Proxy
Client Error 4xx
xk 400 Bad Request -> error-bad-request
xk 401 Unauthorized -> error-user-authentication-required
xk 402 Payment Required -> error-payment-required
xk 403 Forbidden -> error-forbidden-operation
xk 404 Not Found -> error-URL-not-found
xk 405 Method Not Allowed -> error-operation-not-allowed
x 406 Not Acceptable (see Issue #2)
407 Proxy Authentication Required
f 408 Request Timeout
409 Conflict
xk 410 Gone -> error-URL-gone
x 411 Length Required (see Issue #3)
412 Precondition Failed
x 413 Request Entity Too Large (see Issue #3)
xk 414 Request-URI Too Long -> error-URL-too-long
415 Unsupported Media Type
ik 451 Attribute Not Implement/Value Not Supported ->
error-attribute-not-implemented-or-value-not-supported
k 45x not defined -> error-operation-not-authorized (see Issue #4)
Server Error 5xx
xk 500 Internal Server Error -> error-internal-server-error
xk 501 Not Implemented -> error-operation-not-implemented
502 Bad Gateway
xk 503 Service Unavailable -> error-service-unavailable
504 Gateway Timeout
xk 505 HTTP Version Not Supported ->
error-ipp-version-not-supported
k 551 Printer Error -> error-printer-error
3.0 ISSUES
----------
Based on previous email on my original proposal, I documented the
following issues. Any mistakes in articulating the issue are mine.
1. Should there be a single OK status returned for all operations
that are performed successfully (i.e. asserting there is no
attribute or value substitution) or should there be more granular
status codes in the following cases?
Operation IPP HTTP 1.1
--------- --- --------
CreateJob OK vs. Created (201) (i.e. a Job is created)
SendDocument OK vs. Created? (201) (i.e. a Document is created)
CancelJob OK vs. No Content (204) (i.e. no entity body
returned)
PROPOSAL: Use a single OK status keyword in IPP for all
operations. Other implementations might not have the same
underlying status codes as HTTP 1.1. An HTTP 1.1 implementation
can map Created and No Content to OK.
2. HTTP 1.1 defines a status code of Not Acceptable (406). The HTTP
RFC states: "The resource identified by the request is only
capable of generating response entities which have content
characteristics not acceptable according to the accept headers
sent in the request."
Should there be an IPP status code for this error?
3. HTTP 1.1 defines status codes Length Required (411) and Request
Entity Too Large (413).
Length Required means the "The server refuses to accept the
request without a defined Content-Length". This seems like a
bug in the implementation of an IPP client.
Request Entity Too Large means "The server is refusing to process
a request because the Request-URI is longer than the server is
willing to interpret."
Should there be IPP status codes for these errors?
4. This proposal defines Status codes user-authentication-required,
operation-not-authorized and operation-forbidden.
HTTP 1.1 defines Unauthorized (401) which maps to
user-authentication-required and Forbidden (403) which maps to
operation-forbidden. I added operation-not-authorized because I
believe this is a separate error per the definition of
authentication and authorization in the IPP Security internet
draft.
Should all 3 status codes be in the IPP Model, a subset or a
superset?
PROPOSAL: Keith will request a position from the Security group.
5. Should there be a status code for attribute-substition and
another status for attribute-ignored instead of a single status
code?
ANSWER: Use 1 status code,
OK-attribute-ignored-or-value-substituted
since both conditions can occur for the same operation.
6. Should there be a status code for attribute-not-implemented and
another status for attribute-value-not-supported instead of a
single status code?
ANSWER: Use 1 status code,
error-attribute-not-implemented-or-value-not-supported,
since both conditions can occur for the same operation.
7. Should there be a status code ipp-version-not-supported?
PROPOSAL: Yes. Keith will write up a section for the Model
document on IPP version.
8. Should there be a way for implementors to have private error
codes?
PROPOSAL: Since Status codes are type2 keywords, "implementors
can,at any time, add new values by proposing them to the PWG for
registration (or an IANA-appointed registry advisor after the PWG
is no longer certified) where these are reviewed for approval".
Is this sufficient?
9. 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).
The description of number-of-documents states the following: "The
printer shall reject a job if the number of documents is not in
the range of this attribute".
PROPOSAL: The error is really that a Printer receives a Job with
n+1 documents where the Printer can only support n documents per
Job. So the error isn't limited to whether one or more than one
Document is supported per job. I added document-rejected
(see above) to cover this and another case.