Enjoy,
Keith
---- Start of Status Section ----
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.
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 (SWP)
The request has succeeded. The information returned with the
response is dependent on the operation, for example:
Print-Job A Job is created and the Job URI is returned
in the response;
Validate A validation request is fully supported by
an IPP Printer;
Create-Job A Job is created and the Job URI is returned
in the response;
Send-Data Data is written in a Job;
Cancel The Job is cancelled;
Get-Jobs The Jobs currently belonging to the IPP
Printer are returned in the response;
Get-Attributes The values for the attributes specified
in the request are returned in the
response.
NOTE TO REVIEWERS: SWP only includes OK. SWP 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.2.2 successful-attribute-ignored (IPP)
For the Get-Attributes or Get-Jobs operation, if an IPP Printer does
not implement an attribute specified in the request, the Printer
shall ignore the attribute and return this status.
For all other operations, if an IPP Printer does not implement an
attribute specified in the request, the Printer shall return
client-error-attribute-value-not-supported. Note that for these
operations, an unimplemented attribute will have an unsupported value
in the request since the intent is to set or validate a value.
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 object.
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 (SWP)
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.
NOTE TO REVIEWERS: HTTP 1.1 designates this status as reserved
for future use. Should IPP do the same?
4.4.4.4 client-error-forbidden (SWP)
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.
NOTE TO REVIEWERS: HTTP 1.1 further states: "The Reponse MUST
include an Allow header containing a list of valid methods for the
requested resource." Will IPP over HTTP 1.1 support this?
4.4.4.6 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.7 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.8 client-error-request-entity-too-large (SWP)
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.9 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.10 client-error-unsupported-media-type (SWP)
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.11 client-error-attribute-value-not-supported (IPP)
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-IPP-version-not-supported (IPP)
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.4.5 server-error-printer-error (IPP)
A printer error, such as a paper jam, occurs while the IPP Printer
processes a Print-Job or Send-Data 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.6 server-error-write-fault (IPP)
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-Job or Send-Data operation.
4.4.4.7 server-error-too-many-documents-in-job (IPP)
For a Create-Job operation, the number-of-documents specified in the
request exceeds the number-of-documents supported by the Printer.
For a Send-Data operation, the IPP Printer cannot process a Document
in a Job because the document exceeds the number-of-documents
supported by the Printer.
If an IPP application receives this status, the application shall
send multiple documents as separate Jobs using the Print-Job
operation for each document.
---- End of Status Section ----