ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-HTTP/README
(Generate patch)

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.6 by root, Fri Oct 24 01:27:29 2008 UTC vs.
Revision 1.9 by root, Sat Jul 25 01:29:09 2009 UTC

… …
49 "http_request" returns a "cancellation guard" - you have to keep the 49 "http_request" returns a "cancellation guard" - you have to keep the
50 object at least alive until the callback get called. If the object 50 object at least alive until the callback get called. If the object
51 gets destroyed before the callbakc is called, the request will be 51 gets destroyed before the callbakc is called, the request will be
52 cancelled. 52 cancelled.
53 53
54 The callback will be called with the response data as first argument 54 The callback will be called with the response body data as first
55 (or "undef" if it wasn't available due to errors), and a hash-ref 55 argument (or "undef" if an error occured), and a hash-ref with
56 with response headers as second argument. 56 response headers as second argument.
57 57
58 All the headers in that hash are lowercased. In addition to the 58 All the headers in that hash are lowercased. In addition to the
59 response headers, the "pseudo-headers" "HTTPVersion", "Status" and 59 response headers, the "pseudo-headers" "HTTPVersion", "Status" and
60 "Reason" contain the three parts of the HTTP Status-Line of the same 60 "Reason" contain the three parts of the HTTP Status-Line of the same
61 name. The pseudo-header "URL" contains the original URL (which can 61 name. The pseudo-header "URL" contains the original URL (which can
… …
64 If the server sends a header multiple times, then their contents 64 If the server sends a header multiple times, then their contents
65 will be joined together with a comma (","), as per the HTTP spec. 65 will be joined together with a comma (","), as per the HTTP spec.
66 66
67 If an internal error occurs, such as not being able to resolve a 67 If an internal error occurs, such as not being able to resolve a
68 hostname, then $data will be "undef", "$headers->{Status}" will be 68 hostname, then $data will be "undef", "$headers->{Status}" will be
69 599 and the "Reason" pseudo-header will contain an error message. 69 "59x" (usually 599) and the "Reason" pseudo-header will contain an
70 error message.
70 71
71 A typical callback might look like this: 72 A typical callback might look like this:
72 73
73 sub { 74 sub {
74 my ($body, $hdr) = @_; 75 my ($body, $hdr) = @_;
… …
115 loosely based on the original netscape specification. 116 loosely based on the original netscape specification.
116 117
117 The $hash_ref must be an (initially empty) hash reference which 118 The $hash_ref must be an (initially empty) hash reference which
118 will get updated automatically. It is possible to save the 119 will get updated automatically. It is possible to save the
119 cookie_jar to persistent storage with something like JSON or 120 cookie_jar to persistent storage with something like JSON or
120 Storable, but this is not recommended, as expire times are 121 Storable, but this is not recommended, as expiry times are
121 currently being ignored. 122 currently being ignored.
122 123
123 Note that this cookie implementation is not of very high 124 Note that this cookie implementation is not of very high
124 quality, nor meant to be complete. If you want complete cookie 125 quality, nor meant to be complete. If you want complete cookie
125 management you have to do that on your own. "cookie_jar" is 126 management you have to do that on your own. "cookie_jar" is
126 meant as a quick fix to get some cookie-using sites working. 127 meant as a quick fix to get some cookie-using sites working.
127 Cookies are a privacy disaster, do not use them unless required 128 Cookies are a privacy disaster, do not use them unless required
128 to. 129 to.
130
131 tls_ctx => $scheme | $tls_ctx
132 Specifies the AnyEvent::TLS context to be used for https
133 connections. This parameter follows the same rules as the
134 "tls_ctx" parameter to AnyEvent::Handle, but additionally, the
135 two strings "low" or "high" can be specified, which give you a
136 predefined low-security (no verification, highest compatibility)
137 and high-security (CA and common-name verification) TLS context.
138
139 The default for this option is "low", which could be interpreted
140 as "give me the page, no matter what".
141
142 on_header => $callback->($headers)
143 When specified, this callback will be called with the header
144 hash as soon as headers have been successfully received from the
145 remote server (not on locally-generated errors).
146
147 It has to return either true (in which case AnyEvent::HTTP will
148 continue), or false, in which case AnyEvent::HTTP will cancel
149 the download (and call the finish callback with an error code of
150 598).
151
152 This callback is useful, among other things, to quickly reject
153 unwanted content, which, if it is supposed to be rare, can be
154 faster than first doing a "HEAD" request.
155
156 Example: cancel the request unless the content-type is
157 "text/html".
158
159 on_header => sub {
160 $_[0]{"content-type"} =~ /^text\/html\s*(?:;|$)/
161 },
162
163 on_body => $callback->($partial_body, $headers)
164 When specified, all body data will be passed to this callback
165 instead of to the completion callback. The completion callback
166 will get the empty string instead of the body data.
167
168 It has to return either true (in which case AnyEvent::HTTP will
169 continue), or false, in which case AnyEvent::HTTP will cancel
170 the download (and call the completion callback with an error
171 code of 598).
172
173 This callback is useful when the data is too large to be held in
174 memory (so the callback writes it to a file) or when only some
175 information should be extracted, or when the body should be
176 processed incrementally.
177
178 It is usually preferred over doing your own body handling via
179 "want_body_handle", but in case of streaming APIs, where HTTP is
180 only used to create a connection, "want_body_handle" is the
181 better alternative, as it allows you to install your own event
182 handler, reducing resource usage.
183
184 want_body_handle => $enable
185 When enabled (default is disabled), the behaviour of
186 AnyEvent::HTTP changes considerably: after parsing the headers,
187 and instead of downloading the body (if any), the completion
188 callback will be called. Instead of the $body argument
189 containing the body data, the callback will receive the
190 AnyEvent::Handle object associated with the connection. In error
191 cases, "undef" will be passed. When there is no body (e.g.
192 status 304), the empty string will be passed.
193
194 The handle object might or might not be in TLS mode, might be
195 connected to a proxy, be a persistent connection etc., and
196 configured in unspecified ways. The user is responsible for this
197 handle (it will not be used by this module anymore).
198
199 This is useful with some push-type services, where, after the
200 initial headers, an interactive protocol is used (typical
201 example would be the push-style twitter API which starts a
202 JSON/XML stream).
203
204 If you think you need this, first have a look at "on_body", to
205 see if that doesn't solve your problem in a better way.
129 206
130 Example: make a simple HTTP GET request for http://www.nethype.de/ 207 Example: make a simple HTTP GET request for http://www.nethype.de/
131 208
132 http_request GET => "http://www.nethype.de/", sub { 209 http_request GET => "http://www.nethype.de/", sub {
133 my ($body, $hdr) = @_; 210 my ($body, $hdr) = @_;
… …
165 $AnyEvent::HTTP::MAX_RECURSE 242 $AnyEvent::HTTP::MAX_RECURSE
166 The default value for the "recurse" request parameter (default: 10). 243 The default value for the "recurse" request parameter (default: 10).
167 244
168 $AnyEvent::HTTP::USERAGENT 245 $AnyEvent::HTTP::USERAGENT
169 The default value for the "User-Agent" header (the default is 246 The default value for the "User-Agent" header (the default is
170 "Mozilla/5.0 (compatible; AnyEvent::HTTP/$VERSION; 247 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
171 +http://software.schmorp.de/pkg/AnyEvent)"). 248 +http://software.schmorp.de/pkg/AnyEvent)").
172 249
173 $AnyEvent::HTTP::MAX_PERSISTENT 250 $AnyEvent::HTTP::MAX_PER_HOST
174 The maximum number of persistent connections to keep open (default: 251 The maximum number of concurrent conenctions to the same host
175 8). 252 (identified by the hostname). If the limit is exceeded, then the
253 additional requests are queued until previous connections are
254 closed.
176 255
177 Not implemented currently. 256 The default value for this is 4, and it is highly advisable to not
178 257 increase it.
179 $AnyEvent::HTTP::PERSISTENT_TIMEOUT
180 The maximum time to cache a persistent connection, in seconds
181 (default: 2).
182
183 Not implemented currently.
184 258
185 $AnyEvent::HTTP::ACTIVE 259 $AnyEvent::HTTP::ACTIVE
186 The number of active connections. This is not the number of 260 The number of active connections. This is not the number of
187 currently running requests, but the number of currently open and 261 currently running requests, but the number of currently open and
188 non-idle TCP connections. This number of can be useful for 262 non-idle TCP connections. This number of can be useful for
… …
193 267
194AUTHOR 268AUTHOR
195 Marc Lehmann <schmorp@schmorp.de> 269 Marc Lehmann <schmorp@schmorp.de>
196 http://home.schmorp.de/ 270 http://home.schmorp.de/
197 271
272 With many thanks to Дмитрий Шалашов, who provided
273 countless testcases and bugreports.
274

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines