HTTP::DAV::Response (3pm)

require HTTP::DAV::Response;

The HTTP::DAV::Response class encapsulates \s-1HTTP\s0 style responses. A response consists of a response line, some headers, and (potentially empty) content.

HTTP::DAV::Response is a subclass of \*(C`HTTP::Response\*(C' and therefore inherits its methods. (HTTP::Response in turn inherits it's methods from \*(C`HTTP::Message\*(C').

Therefore, this class actually inherits a rich library of functions. You are more likely wanting to read the \*(C`HTTP::Response\*(C' class as opposed to this class.

Instances of this class are usually created by a \*(C`HTTP::DAV::Resource\*(C' object after it has performed some request (such as get, lock, delete, etc). You use the object to analyse the success or otherwise of the request.

HTTP::DAV::Response was created to handle two extra functions that normal \s-1HTTP\s0 Responses don't require:

 - WebDAV reponses have 6 extra error codes: 102, 207, 422, 423, 424 and 507. Older versions of the LWP's C<HTTP::Status> class did not have these extra codes. These were added.

 - WebDAV responses can actually contain more than one response (and often DO contain more than one) in the form of a "Multistatus". These multistatus responses come in the form of an XML document. HTTP::DAV::Response can accurately parse these XML responses and emulate the normal of the C<HTTP::Response>.

HTTP::DAV::Response transparently implements these extra features without the user having to be aware, so you really should be reading the \*(C`HTTP::Response\*(C' documentation for most of the things you want to do (have I already said that?).

There are only a handful of custom functions that HTTP::DAV::Response returns and those are to handle multistatus requests, \*(C`messages()\*(C' and \*(C`codes()\*(C'.

The six extra status codes that \s-1DAV\s0 servers can be returned in an \s-1HTTP\s0 Response are:

  102 => \*(L"Processing. Server has accepted the request, but has not yet completed it\*(R",
  207 => \*(L"Multistatus\*(R",
  422 => \*(L"Unprocessable Entity. Bad client \s-1XML\s0 sent?\*(R",
  423 => \*(L"Locked. The source or destination resource is locked\*(R",
  424 => \*(L"Failed Dependency\*(R",
  507 => \*(L"Insufficient Storage. The server is unable to store the request\*(R",

See \*(C`HTTP::Status\*(C' for the rest.

So, many \s-1DAV\s0 requests may return a multistatus (\*(L"207 multistatus\*(R") instead of, say, \*(L"200 \s-1OK\s0\*(R" or \*(L"403 Forbidden\*(R".

The HTTP::DAV::Response object stores each \*(L"response\*(R" sent back in the multistatus. You access them by array number.

The following code snippet shows what you will normally want to do:

... $response = $resource->lock();

if ( $response->is_multistatus() ) {

foreach $num ( 0 .. $response->response_count() ) { ($err_code,$mesg,$url,$desc) = $response->response_bynum($num); print "$mesg ($err_code) for $url\n"; } }

Would produce something like this:

   Failed Dependency (424) for /test/directory
   Locked (423) for /test/directory/file3

This says that we couldn't lock /test/directory because file3 which exists inside is already locked by somebody else.

is_multistatus

This function takes no arguments and returns a 1 or a 0. For example: if ($response->is_multistatus() ) { } If the \s-1HTTP\s0 reply had \*(L"207 Multistatus\*(R" in the header then that indicates that there are multiple status messages in the \s-1XML\s0 content that was returned. In this event, you may be interested in knowing what the individual messages were. To do this you would then use \*(C`messages\*(C'.

response_count

Takes no arguments and returns \*(L"the number of error responses -1\*(R" that we got. Why -1? Because usually you will want to use this like an array operator: foreach $num ( 0 .. $response->response_count() ) {

   print $response->message_bynum();

}

response_bynum

Takes one argument, the \*(L"response number\*(R" that you're interested in. And returns an array of details: ($code,$message,$url,$description) = response_bynum(2); where

   $code - is the \s-1HTTP\s0 error code (e.g. 403, 423, etc).
   $message - is the associated message for that error code.
   $url - is the url that this error applies to (recall that there can be multiple responses within one response and they all relate to one \s-1URL\s0)
   $description - is server's attempt at an english description of what happened.

code_bynum

Takes one argument, the \*(L"response number\*(R" that you're interested in, and returns it's code. E.g: $code = $response->code_bynum(1); See \*(C`response_bynum()\*(C'

message_bynum

Takes one argument, the \*(L"response number\*(R" that you're interested in, and returns it's message. E.g: $code = $response->message_bynum(1); See \*(C`response_bynum()\*(C'

url_bynum

Takes one argument, the \*(L"response number\*(R" that you're interested in, and returns it's url. E.g: $code = $response->message_bynum(1); See \*(C`response_bynum()\*(C'

description_bynum

Takes one argument, the \*(L"response number\*(R" that you're interested in, and returns it's description. E.g: $code = $response->message_description(1); See \*(C`response_bynum()\*(C'

messages

Takes no arguments and returns all of the messages returned in a multistatus response. If called in a scalar context then all of the messages will be returned joined together by newlines. If called in an array context the messages will be returned as an array. $messages = $response->messages(); e.g. $messages eq \*(L"Forbidden\nLocked\*(R"; @messages = $response->messages(); e.g. @messages eq [\*(L"Forbidden\*(R", \*(L"Locked\*(R"]; This routine is a variant on the standard \*(C`HTTP::Response\*(C' \*(C`message()\*(C'.