1HTTP::DAV::Response(3)User Contributed Perl DocumentationHTTP::DAV::Response(3)
2
3
4

NAME

6       HTTP::DAV::Response - represents a WebDAV HTTP Response (ala
7       HTTP::Response)
8

SYNOPSIS

10       require HTTP::DAV::Response;
11

DESCRIPTION

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
17       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
21       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
25       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
30       HTTP::DAV::Response was created to handle two extra functions that
31       normal HTTP Responses don't require:
32
33        - 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
35        - 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
37       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
42       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
46       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
57       See "HTTP::Status" for the rest.
58

HANDLING A MULTISTATUS

60       So, many DAV requests may return a multistatus ("207 multistatus")
61       instead of, say, "200 OK" or "403 Forbidden".
62
63       The HTTP::DAV::Response object stores each "response" sent back in the
64       multistatus. You access them by array number.
65
66       The following code snippet shows what you will normally want to do:
67
68       ...  $response = $resource->lock();
69
70       if ( $response->is_multistatus() ) {
71
72          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
79       Would produce something like this:
80          Failed Dependency (424) for /test/directory
81          Locked (423) for /test/directory/file3
82
83       This says that we couldn't lock /test/directory because file3 which
84       exists inside is already locked by somebody else.
85

METHODS

87       is_multistatus
88           This function takes no arguments and returns a 1 or a 0.
89
90           For example: if ($response->is_multistatus() ) { }
91
92           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
96           In this event, you may be interested in knowing what the individual
97           messages were. To do this you would then use "messages".
98
99       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
104           foreach $num ( 0 .. $response->response_count() ) {
105              print $response->message_bynum(); }
106
107       response_bynum
108           Takes one argument, the "response number" that you're interested
109           in. And returns an array of details:
110
111              ($code,$message,$url,$description) = response_bynum(2);
112
113           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
122       code_bynum
123           Takes one argument, the "response number" that you're interested
124           in, and returns it's code. E.g:
125
126             $code = $response->code_bynum(1);
127
128           See response_bynum()
129
130       message_bynum
131           Takes one argument, the "response number" that you're interested
132           in, and returns it's message. E.g:
133
134             $code = $response->message_bynum(1);
135
136           See response_bynum()
137
138       url_bynum
139           Takes one argument, the "response number" that you're interested
140           in, and returns it's url. E.g:
141
142             $code = $response->message_bynum(1);
143
144           See response_bynum()
145
146       description_bynum
147           Takes one argument, the "response number" that you're interested
148           in, and returns it's description. E.g:
149
150             $code = $response->message_description(1);
151
152           See response_bynum()
153
154       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
160           $messages = $response->messages(); e.g. $messages eq
161           "Forbidden\nLocked";
162
163           @messages = $response->messages(); e.g. @messages eq ["Forbidden",
164           "Locked"];
165
166           This routine is a variant on the standard "HTTP::Response"
167           message().
168
169
170
171perl v5.36.0                      2023-01-20            HTTP::DAV::Response(3)
Impressum