1HTTP::DAV::Response(3)User Contributed Perl DocumentationHTTP::DAV::Response(3)
2
6 HTTP::DAV::Response - represents a WebDAV HTTP Response (ala
7 HTTP::Response)
8
10 require HTTP::DAV::Response;
11
13 The HTTP::DAV::Response class encapsulates HTTP style responses. A
14 response consists of a response line, some headers, and (potentially
15 empty) content.
16 HTTP::DAV::Response is a subclass of "HTTP::Response" and therefore
18 inherits its methods. (HTTP::Response in turn inherits it's methods
19 from "HTTP::Message").
20 Therefore, this class actually inherits a rich library of functions.
22 You are more likely wanting to read the "HTTP::Response" class as
23 opposed to this class.
24 Instances of this class are usually created by a "HTTP::DAV::Resource"
26 object after it has performed some request (such as get, lock, delete,
27 etc). You use the object to analyse the success or otherwise of the
28 request.
29 HTTP::DAV::Response was created to handle two extra functions that
31 normal HTTP Responses don't require:
32 - WebDAV responses 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.
34 - 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>.
36 HTTP::DAV::Response transparently implements these extra features
38 without the user having to be aware, so you really should be reading
39 the "HTTP::Response" documentation for most of the things you want to
40 do (have I already said that?).
41 There are only a handful of custom functions that HTTP::DAV::Response
43 returns and those are to handle multistatus requests, "messages()" and
44 "codes()".
45 The six extra status codes that DAV servers can be returned in an HTTP
47 Response are:
48 102 => "Processing. Server has accepted the request, but has not yet
49 completed it",
50 207 => "Multistatus",
51 422 => "Unprocessable Entity. Bad client XML sent?",
52 423 => "Locked. The source or destination resource is locked",
53 424 => "Failed Dependency",
54 507 => "Insufficient Storage. The server is unable to store the
55 request",
56 See "HTTP::Status" for the rest.
58
60 So, many DAV requests may return a multistatus ("207 multistatus")
61 instead of, say, "200 OK" or "403 Forbidden".
62 The HTTP::DAV::Response object stores each "response" sent back in the
64 multistatus. You access them by array number.
65 The following code snippet shows what you will normally want to do:
67 ... $response = $resource->lock();
69 if ( $response->is_multistatus() ) {
71 foreach $num ( 0 .. $response->response_count() ) {
73 ($err_code,$mesg,$url,$desc) =
74 $response->response_bynum($num);
75 print "$mesg ($err_code) for $url\n";
76 }
77 }
78 Would produce something like this:
80 Failed Dependency (424) for /test/directory
81 Locked (423) for /test/directory/file3
82 This says that we couldn't lock /test/directory because file3 which
84 exists inside is already locked by somebody else.
85
87 is_multistatus
88 This function takes no arguments and returns a 1 or a 0.
89 For example: if ($response->is_multistatus() ) { }
91 If the HTTP reply had "207 Multistatus" in the header then that
93 indicates that there are multiple status messages in the XML
94 content that was returned.
95 In this event, you may be interested in knowing what the individual
97 messages were. To do this you would then use "messages".
98 response_count
100 Takes no arguments and returns "the number of error responses -1"
101 that we got. Why -1? Because usually you will want to use this
102 like an array operator:
103 foreach $num ( 0 .. $response->response_count() ) {
105 print $response->message_bynum(); }
106 response_bynum
108 Takes one argument, the "response number" that you're interested
109 in. And returns an array of details:
110 ($code,$message,$url,$description) = response_bynum(2);
112 where
114 $code - is the HTTP error code (e.g. 403, 423, etc).
115 $message - is the associated message for that error code.
116 $url - is the url that this error applies to (recall that there
117 can be multiple responses within one response and they all relate
118 to one URL)
119 $description - is server's attempt at an english description of
120 what happened.
121 code_bynum
123 Takes one argument, the "response number" that you're interested
124 in, and returns it's code. E.g:
125 $code = $response->code_bynum(1);
127 See "response_bynum()"
129 message_bynum
131 Takes one argument, the "response number" that you're interested
132 in, and returns it's message. E.g:
133 $code = $response->message_bynum(1);
135 See "response_bynum()"
137 url_bynum
139 Takes one argument, the "response number" that you're interested
140 in, and returns it's url. E.g:
141 $code = $response->message_bynum(1);
143 See "response_bynum()"
145 description_bynum
147 Takes one argument, the "response number" that you're interested
148 in, and returns it's description. E.g:
149 $code = $response->message_description(1);
151 See "response_bynum()"
153 messages
155 Takes no arguments and returns all of the messages returned in a
156 multistatus response. If called in a scalar context then all of the
157 messages will be returned joined together by newlines. If called in
158 an array context the messages will be returned as an array.
159 $messages = $response->messages(); e.g. $messages eq
161 "Forbidden\nLocked";
162 @messages = $response->messages(); e.g. @messages eq ["Forbidden",
164 "Locked"];
165 This routine is a variant on the standard "HTTP::Response"
167 "message()".
168perl v5.36.0 2022-07-22 HTTP::DAV::Response(3)