Dear all,
This note contains the following:
I. Status Keyword Section for IPP Model Document
II. Mapping of HTTP 1.1 Status Codes to IPP Status Keywords
III. Status Keywords for IPP Operations
IV. Action Items from IPP Protocol Meeting on June 17
V. Issues
I believe the most efficient process is to schedule an item on
the agenda at the IPP Model meeting on June 25 to review the
status keywords, discuss the issues, and make the appropriate
changes at that time.
Scott,
Please add "Review IPP Status Keywords" to the agenda for the IPP
Model meeting on June 25. Thanks.
Keith
I. Status Keywords Section for IPP Model Document
--------------------------------------------------
This section contains the status keywords as defined on May 21 with
the following changes:
1. Removed successful-attribute-ignored per previous email.
2. Removed server-error-too-many-documents per previous email.
3. Marked status codes defined in the IPP Level 1 doc as (IPPL1).
4. Marked new status keywords as (NEW).
4.3 Status and Message
The Status keyword 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.
The prefix of the Status keyword defines the class of response as
follows:
o informational - Request received, continuing process
o successful - The action was successfully received, understood,
and accepted
o redirection - Further action must be taken in order to
complete the request
o client-error - The request contains bad syntax or cannot be
fulfilled
o server-error - The server failed to fulfill an apparently
valid request
IPP status codes are extensible. IPP applications are not 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 prefix,
and treat any unrecognized response as being equivalent to the first
status code of that class, with the exception that an unrecognized
response shall not be cached. For example, if an unrecognized status
code of client-error-foo-bar is received by the client, it can
safely assume that there was something wrong with its request and
treat the response as if it had received a client-error-bad-request
status code. In such cases, IPP applications should present the
Message to the user, since that Message is likely to include human-
readable information which will explain the unusual status.
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 Informational
This class of status code indicates a provisional response and
is to be used for informational purposes only. There are no
status codes defined in IPP 1.0 for this class of status code.
4.4.2 Successful
This class of status code indicates that the client's request was
successfully received, understood, and accepted.
4.4.2.1 successful-OK (IPPL1)
The request has succeeded.
NOTE TO REVIEWERS: IPPL1 only includes OK. IPPL1 does not include
Created nor No Content successful status codes. This is consistent
with our agreement at the IPP Model telecon on May 9, but I believe
we had this discussion before Bob Herriot joined the telecon.
4.4.3 Redirection Status Codes
This class of status code indicates that further action needs to
be taken to fulfill the request. There are no status codes
defined in IPP 1.0 for this class of status code.
4.4.4 Client Error Status Codes
This class of status code is intended for cases in which the client
seems to have erred. The server should return a Message containing
an explanation of the error situation and whether it is a temporary
or permanent condition. IPP applications should display any returned
Message to the end-user. Unless otherwise noted, these status codes
apply to all operations.
4.4.4.1 client-error-bad-request (IPPL1)
The request could not be understood by the server due to
malformed syntax. The IPP application should not repeat the
request without modifications.
4.4.4.2 client-error-unauthorized
The request requires user authentication. The IPP client may repeat
the request with suitable authorization credentials. If the request
already included authorization credentials, then this status code
indicates that authorization has been refused for those credentials.
If this response contains the same challenge as the prior response,
and the user agent has already attempted authentication at least once,
then the user should be presented the Message in the response, since
that Message may include relevant diagnostic information.
4.4.4.3 client-error-payment-required
This request requires payment by the end-user to perform the
operation.
4.4.4.4 client-error-forbidden (IPPL1)
The server 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 server
does not wish to reveal exactly why the request has been refused
or when no other response is applicable.
4.4.4.5 client-error-method-not-allowed
The operation specified in the request is not allowed for the object
identified by the request URI.
4.4.4.6 client-error-timeout (NEW)
The client did not produce a request within the time that the server was
prepared to wait. The client MAY repeat the request without modifications
at any later time.
4.4.4.7 client-error-not-found
The server has not found anything matching the request URI.
No indication is given of whether the condition is temporary or
permanent.
In practice, an application should avoid this situation by presenting
a list of valid Printer URIs and Job URIs to the end-user.
4.4.4.8 client-error-gone
The requested object is no longer available at the server and no
forwarding address is known. This condition should be considered
permanent. Clients with link editing capabilities should delete
references to the request URI after user approval. If the server
does not know or has no facility to determine,whether or not the
condition is permanent, the status code client-error-not-found
should be used instead. This response is cachable unless
indicated otherwise.
This response is primarily intended to assist the task of web
maintenance by notifying 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 limited-time, promotional services and for resources belonging
to individuals no longer working at the server's site. It is not
necessary to mark all permanently unavailable resources as "gone" or
to keep the mark for any length of time -- that is left to the
discretion of the server owner.
4.4.4.9 client-error-request-entity-too-large (IPPL1)
The server is refusing to process a request because the request
entity is larger than the server is willing or able to process.
An IPP Printer returns this status code when it limits the size
of print jobs and it receives a print job that exceeds that limit.
4.4.4.10 client-error-request-URI-too-long
The server is refusing to service the request because the request URI
is longer than the server is willing to interpret. This rare condition
is only likely to occur when a client has improperly submitted a request
with long query information (e.g. an IPP application allows an end-user
to enter an invalid URI), when the client has descended into a URL
"black hole" of redirection (e.g., a redirected URL prefix that points
to a suffix of itself), or when the server is under attack by a client
attempting to exploit security holes present in some servers using
fixed-length buffers for reading or manipulating the Request-URI.
4.4.4.11 client-error-unsupported-media-type (IPPL1)
The server is refusing to service the request because the print data
is in a format, as specified in document-format, not supported by the
IPP Printer.
4.4.4.12 client-error-attribute-value-not-supported
For a Create-Job, Print-Job or Validate operation, if the IPP Printer
does not support at least one attribute value specified in the request,
the Printer shall return this status. For example, if 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 an operation on the Printer.
4.4.5 Server Error Status Codes
This class of status codes indicates cases in which the server is aware
that it has erred or is incapable of performing the request. The
server should include a Message containing an explanation of the
error situation, and whether it is a temporary or permanent condition.
IPP applications should display any included Message to the user.
These response codes are applicable to any operation.
4.4.5.1 server-error-internal-server-error
The server encountered an unexpected condition which
prevented it from fulfilling the request.
4.4.5.2 server-error-operation-not-implemented
The server does not support the functionality required to
fulfill the request. This is the appropriate response when the
server does not recognize an operation and is not capable of
supporting it for any object.
4.4.5.3 server-error-service-unavailable
The server is currently unable to handle the request due to a
temporary overloading or maintenance of the server. 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
server-error-internal-server-error response.
4.4.5.4 server-error-timeout (NEW)
The server did not produce a response within the time that the
client was prepared to wait. The client MAY repeat the request
without modifications at any later time.
4.4.5.5 server-error-HTTP-version-not-supported (NEW)
The server does not support, or refuses to support, the HTTP
protocol version that was used in the request message. The
server 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 the version is not supported and what other
protocols are supported by that server.
4.4.5.6 server-error-IPP-version-not-supported
The server does not support, or refuses to support, the IPP
protocol version that was used in the request message. The server
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 server.
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.5.7 server-error-printer-error
A printer error, such as a paper jam, occurs while the IPP Printer
processes a Print or Send 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.5.8 server-error-write-fault
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 Print or Send operation.
II. Mapping of HTTP 1.1 Status Codes to IPP Status Keywords
-----------------------------------------------------------
HTTP 1.1 Status IPP Keyword
--------------- -----------
100 Continue none
101 Switching Protocols none
200 OK successful-OK
201 Created successful-OK
202 Accepted successful-OK
203 Non-Authoritive Information successful-OK
204 No Content successful-OK
205 Reset Content none
206 Partial Content (GET) none
300 Multiple Choices none
301 Moved Permanently none
302 Moved Temporarily none
303 See Other none
304 Not Modified (GET) none
305 Use Proxy none
400 Bad Request client-error-bad-request
401 Unauthorized client-error-unauthorized
402 Payment Required client-error-payment-required
403 Forbidden client-error-forbidden
404 Not Found client-error-not-found
405 Method Not Allowed client-error-method-not-allowed
406 Not Acceptable client-error-bad-request
407 Proxy Authentication Required client-error-unauthorized
408 Request Timeout client-error-timeout
409 Conflict (most likely PUT) client-error-bad-request
410 Gone client-error-gone
411 Length Required client-error-bad-request
412 Precondition Failed client-error-bad-request
413 Request Entity Too Large client-error-request-entity-too-large
414 Request-URI Too Long client-error-request-URI-too-long
415 Unsupported Media Type client-error-unsupported-media-type
none client-error-attribute-value-not-supported
500 Internal Server Error server-error-internal-server-error
501 Not Implemented server-error-not-implemented
502 Bad Gateway server-error-internal-server-error
503 Service Unavailable server-error-service-unavailable
504 Gateway Timeout server-error-timeout
505 HTTP Version Not Supported server-error-HTTP-version-not-supported
none server-error-IPP-version-not-supported
none server-error-printer-error
none server-error-write-fault
III. Status Keywords for IPP Operations
---------------------------------------
PJ = Print-Job, PU = Print-URI, CJ = Create-Job, SD = Send-Document
SU = Send-URI, V = Validate, GA = Get-Attributes, GJ = Get-Jobs
GO = Get-Operations, C = Cancel-Job
IPP Operations
IPP Status Keyword PJ PU CJ SD SU V GA GJ GO C
------------------ -- -- -- -- -- - -- -- -- -
successful-OK x x x x x x x x x x
client-error-bad-request x x x x x x x x x x
client-error-unauthorized x x x x x x x x x x
client-error-payment-required x x x x x x
client-error-forbidden x x x x x x x x x x
client-error-not-found x x x x x x x x x x
client-error-method-not-allowed x x x x x x x x x x
client-error-timeout x x x x x x x x x x
client-error-gone x x x x x x x x x x
client-error-request-entity-too-large x x
client-error-request-URI-too-long x x x x x x x x x x
client-error-unsupported-media-type x x x x
client-error-attribute-value-not-supported x x x x
server-error-internal-server-error x x x x x x x x x x
server-error-service-unavailable x x x x x x x x x x
server-error-timeout x x x x x x x x x x
server-error-HTTP-version-not-supported x x x x x x x x x x
server-error-IPP-version-not-supported x x x x x x x x x x
server-error-printer-error x x x x x
server-error-write-fault x x x x x
IV. Action Items from IPP Protocol Meeting on June 17
------------------------------------------------------
During the protocol meeting on June 17, I took the action item to
check the following error conditions:
1. An end-user tries to cancel a job that does not exist. Status
code client-error-not-found covers this condition in a Cancel
response.
2. An end-user tries to cancel a job which they do not have
authority to cancel. Status code client-error-unauthorized
covers this condition in a Cancel response. Status
client-error-forbidden might also be a possibility (see Issues).
3. An invalid URI syntax is specified on a Print-URI or Send-URI
request. Status code client-error-not-found and status code
client-error-request-URI-too-long cover this condition. If a
server sees that the syntax of the URI is incorrect, the server
can return client-error-not-found since that will be the case
when an actual "pull" occurs on the URI. I could not find a
specific HTTP 1.1 status code for "invalid URI syntax".
V. Issues
----------
Let's discuss these issues at the IPP Model meeting on June 25.
I listed the issues based on the archive of email on this topic.
For each issue, I included who opened the issue by name: and the
related comments verbatim (hopefully correctly) of the person listed
in () prior to each comment.
1. Bob: Should server-error-printer-error be a defined status?
(Bob) I'm not sure if this is a useful error, or even likely
to happen.
2. Bob: Should server-error-write-fault be a defined status?
(Bob) I would expect the client to block on a write and that
it wouldn't clear until the server got enough space to write
the data.
(Scott) But there are cases where the Printer experiences a
disk full condition but still has enough buffer space to return
a response packet. I wouldn't get rid of it.
(Bob) Maybe once we have the protocol better defined we will
know whether this is a possibility, but I would expect the
printer (to) wait for the disk-full condition to go away. Then
it would write the data and return a response of success. If it
returns this message instead, then the client has to go into some
recovery mode which makes the client more complicated.
(Tom) I agree with Bob, we don't want an error for disk full,
since that complicates clients that would have to take some
action. Instead the PrintJob or SendDocument blocks until the
disk space problem takes care of itself. The disk filling up is
similar to a non-spooled Printer jamming or running out of paper.
A really smart client could/should open up another channel on
the Printer URL and do periodic Get-Attribute for the
"printer-state" and "printer-state-reasons" attributes to watch
for the 'stopped' state and the reasons: 'media-needed' and
'paper-jam' on a non-spooled, non-queuing Printer. The Printer
shall just temporarily hang the data transfer until the condition
gets cleared up. (NOTE: RPC-time out problems, if IPP is ever
layered on RPC).
3. Tom: Should we add a value to the "printer-state-reasons"
attribute: 'spool-space-full' so that a smart client could tell
on a Get-Attributes operation (before it attempts to Print/Send
data to a Printer)?
4. Tom: Should we add a Printer attribute that indicates the amount
of spooling space available, in K octets? Say:
'spooling-space-available"? Then a smart client could tell
whether to even try when it has a really large amount of document
data to send.
5. Keith: HTTP 1.1 designates "402 Payment Required" as reserved
for future use. Should IPP do the same?
6. Keith: For "405 Method Not Allowed", HTTP 1.1 further states :
"The Reponse MUST include an Allow header containing a list of
valid methods for the requested resource." Should IPP over
HTTP 1.1 support this?
7. Keith: Must decide if client-error-unauthorized or
client-error-forbidden should be returned when an end-user tries
to cancel a Job that they do not own.
7. Keith: If we re-instate "best-effort", what, if any, changes are
required? Reference minutes from IPP Protocol meeting on June 16.
8. Keith: Are there other HTTP 1.1 status codes that should have IPP
status keywords? Some candidates are "301 Moved Permanently" and
"302 Moved Temporarily" since both require end-user action to
approve the redirected URI in the response. See RFC 2068 for more
information.
**** End of Note ****