IPP> MOD - Status codes

IPP> MOD - Status codes

IPP> MOD - Status codes

Keith_Carter at aussmtp.austin.ibm.com Keith_Carter at aussmtp.austin.ibm.com
Tue Apr 22 11:22:50 EDT 1997


  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
              | "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
              | "200"      ; Internal Server Error
              | "201"      ; Service Unavailable
              | "202"      ; IPP Version Not Supported
              | "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
  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.


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


  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.


  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.



More information about the Ipp mailing list