Subject: IPP> MOD - UPDATE FOR STATUS CODE KEYWORDS IN THE MODEL DOCUMENT

From: Keith Carter <[email-masked]>
Date: Wed, 21 May 1997 15:30:56 -0400

Here is the update for the status code section based on the
IPP telecon on 5/9 and IPP meetings on 5/14 and 5/15.  The
status code classes match HTTP 1.1 and the keyword names should
map easily to the 3 digit status codes in HTTP 1.1 (e.g. IPP
status "client-error-bad-request" maps to HTTP 1.1 status
"400 Bad Request" where 4xx is the class for "Client Error" in
HTTP 1.1).  I marked IPP-specific status codes as "(IPP)".  FYI,
I also marked the HTTP 1.1 status codes specifically described in
SWP as "(SWP)".  Finally, I included notes to reviewers inline.

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 ----

---

From: [email-masked] (Robert Herriot)
Date: Wed, 21 May 1997 13:48:43 -0700

Good job. I have some comments below

Bob Herriot

> From [email-masked] Wed May 21 12:48:36 1997
> 
Is this really necessary, especially if the returned attributes indicate
which are unsupported.  This is a case of half-full versus half-empty.

> 4.4.2.2 successful-attribute-ignored (IPP)

I'm not sure if this is a useful error, or even likely to happen.

> in the response for the specific error.

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.

> while the IPP Printer processes a Print-Job or Send-Data operation.

With the changes from last week where all Printers support PrintJob
(1 document per job) and some support CreateJob/SendJobData (1 or
more documents per job), this message isn't needed. The error
server-error-operation-not-implemented handles this problem instead.

---

From: [email-masked] (Robert Herriot)
Date: Thu, 22 May 1997 15:28:12 -0700

> From [email-masked] Thu May 22 08:45:15 1997
> 
> Bob,
> 
> I thought this was necessary since a Printer could implement the "should"
> best-effort case and simple ignore some attributes that were not supported. 
> It still prints, the printer is just trying to tell the client some possibly
> interesting info.

No, this was for GetAttributes and GetJobs which should report OK and
return unsupported attributes with a value of 'unsupported'.

In the case of print submission with "should-honor-attributes", the
server hopes it can honor, but it doesn't know what it will fail on.

> 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.

Maybe once we have the protocol better defined we will know whether this
is a possibility, but I would expect the printer 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.

> Is there a case where the Printer supports both Print-Job and
> Create-Job/Send-Job-Data but for some reason has an implementation limit of
> N documents per job?  It would be helpful to have this error code for that
> case.  We have no way (nor do I propose) to query the printer to find out
> how many multiple docs per job it supports.
> 

The PrintJob has a limit of one document. CreateJob/SendJobData should
have no job limit. It may have an octet-limit for an entire job.