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

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.5 by root, Thu Oct 23 02:46:20 2008 UTC vs.
Revision 1.10 by root, Wed Aug 5 16:43:47 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
62 differ from the requested URL when following redirects). 62 differ from the requested URL when following redirects).
63 63
64 If the server sends a header multiple lines, then their contents 64 If the server sends a header multiple times, then their contents
65 will be joined together with "\x00". 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) = @_;
… …
89 90
90 headers => hashref 91 headers => hashref
91 The request headers to use. Currently, "http_request" may 92 The request headers to use. Currently, "http_request" may
92 provide its own "Host:", "Content-Length:", "Connection:" and 93 provide its own "Host:", "Content-Length:", "Connection:" and
93 "Cookie:" headers and will provide defaults for "User-Agent:" 94 "Cookie:" headers and will provide defaults for "User-Agent:"
94 and "Referer:". 95 and "Referer:" (this can be suppressed by using "undef" for
96 these headers in which case they won't be sent at all).
95 97
96 timeout => $seconds 98 timeout => $seconds
97 The time-out to use for various stages - each connect attempt 99 The time-out to use for various stages - each connect attempt
98 will reset the timeout, as will read or write activity. Default 100 will reset the timeout, as will read or write activity. Default
99 timeout is 5 minutes. 101 timeout is 5 minutes.
… …
101 proxy => [$host, $port[, $scheme]] or undef 103 proxy => [$host, $port[, $scheme]] or undef
102 Use the given http proxy for all requests. If not specified, 104 Use the given http proxy for all requests. If not specified,
103 then the default proxy (as specified by $ENV{http_proxy}) is 105 then the default proxy (as specified by $ENV{http_proxy}) is
104 used. 106 used.
105 107
106 $scheme must be either missing or "http" for HTTP, or "https" 108 $scheme must be either missing, "http" for HTTP or "https" for
107 for HTTPS. 109 HTTPS.
108 110
109 body => $string 111 body => $string
110 The request body, usually empty. Will be-sent as-is (future 112 The request body, usually empty. Will be-sent as-is (future
111 versions of this module might offer more options). 113 versions of this module might offer more options).
112 114
… …
115 loosely based on the original netscape specification. 117 loosely based on the original netscape specification.
116 118
117 The $hash_ref must be an (initially empty) hash reference which 119 The $hash_ref must be an (initially empty) hash reference which
118 will get updated automatically. It is possible to save the 120 will get updated automatically. It is possible to save the
119 cookie_jar to persistent storage with something like JSON or 121 cookie_jar to persistent storage with something like JSON or
120 Storable, but this is not recommended, as expire times are 122 Storable, but this is not recommended, as expiry times are
121 currently being ignored. 123 currently being ignored.
122 124
123 Note that this cookie implementation is not of very high 125 Note that this cookie implementation is not of very high
124 quality, nor meant to be complete. If you want complete cookie 126 quality, nor meant to be complete. If you want complete cookie
125 management you have to do that on your own. "cookie_jar" is 127 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. 128 meant as a quick fix to get some cookie-using sites working.
127 Cookies are a privacy disaster, do not use them unless required 129 Cookies are a privacy disaster, do not use them unless required
128 to. 130 to.
131
132 tls_ctx => $scheme | $tls_ctx
133 Specifies the AnyEvent::TLS context to be used for https
134 connections. This parameter follows the same rules as the
135 "tls_ctx" parameter to AnyEvent::Handle, but additionally, the
136 two strings "low" or "high" can be specified, which give you a
137 predefined low-security (no verification, highest compatibility)
138 and high-security (CA and common-name verification) TLS context.
139
140 The default for this option is "low", which could be interpreted
141 as "give me the page, no matter what".
142
143 on_header => $callback->($headers)
144 When specified, this callback will be called with the header
145 hash as soon as headers have been successfully received from the
146 remote server (not on locally-generated errors).
147
148 It has to return either true (in which case AnyEvent::HTTP will
149 continue), or false, in which case AnyEvent::HTTP will cancel
150 the download (and call the finish callback with an error code of
151 598).
152
153 This callback is useful, among other things, to quickly reject
154 unwanted content, which, if it is supposed to be rare, can be
155 faster than first doing a "HEAD" request.
156
157 Example: cancel the request unless the content-type is
158 "text/html".
159
160 on_header => sub {
161 $_[0]{"content-type"} =~ /^text\/html\s*(?:;|$)/
162 },
163
164 on_body => $callback->($partial_body, $headers)
165 When specified, all body data will be passed to this callback
166 instead of to the completion callback. The completion callback
167 will get the empty string instead of the body data.
168
169 It has to return either true (in which case AnyEvent::HTTP will
170 continue), or false, in which case AnyEvent::HTTP will cancel
171 the download (and call the completion callback with an error
172 code of 598).
173
174 This callback is useful when the data is too large to be held in
175 memory (so the callback writes it to a file) or when only some
176 information should be extracted, or when the body should be
177 processed incrementally.
178
179 It is usually preferred over doing your own body handling via
180 "want_body_handle", but in case of streaming APIs, where HTTP is
181 only used to create a connection, "want_body_handle" is the
182 better alternative, as it allows you to install your own event
183 handler, reducing resource usage.
184
185 want_body_handle => $enable
186 When enabled (default is disabled), the behaviour of
187 AnyEvent::HTTP changes considerably: after parsing the headers,
188 and instead of downloading the body (if any), the completion
189 callback will be called. Instead of the $body argument
190 containing the body data, the callback will receive the
191 AnyEvent::Handle object associated with the connection. In error
192 cases, "undef" will be passed. When there is no body (e.g.
193 status 304), the empty string will be passed.
194
195 The handle object might or might not be in TLS mode, might be
196 connected to a proxy, be a persistent connection etc., and
197 configured in unspecified ways. The user is responsible for this
198 handle (it will not be used by this module anymore).
199
200 This is useful with some push-type services, where, after the
201 initial headers, an interactive protocol is used (typical
202 example would be the push-style twitter API which starts a
203 JSON/XML stream).
204
205 If you think you need this, first have a look at "on_body", to
206 see if that doesn't solve your problem in a better way.
129 207
130 Example: make a simple HTTP GET request for http://www.nethype.de/ 208 Example: make a simple HTTP GET request for http://www.nethype.de/
131 209
132 http_request GET => "http://www.nethype.de/", sub { 210 http_request GET => "http://www.nethype.de/", sub {
133 my ($body, $hdr) = @_; 211 my ($body, $hdr) = @_;
… …
165 $AnyEvent::HTTP::MAX_RECURSE 243 $AnyEvent::HTTP::MAX_RECURSE
166 The default value for the "recurse" request parameter (default: 10). 244 The default value for the "recurse" request parameter (default: 10).
167 245
168 $AnyEvent::HTTP::USERAGENT 246 $AnyEvent::HTTP::USERAGENT
169 The default value for the "User-Agent" header (the default is 247 The default value for the "User-Agent" header (the default is
170 "Mozilla/5.0 (compatible; AnyEvent::HTTP/$VERSION; 248 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
171 +http://software.schmorp.de/pkg/AnyEvent)"). 249 +http://software.schmorp.de/pkg/AnyEvent)").
172 250
173 $AnyEvent::HTTP::MAX_PERSISTENT 251 $AnyEvent::HTTP::MAX_PER_HOST
174 The maximum number of persistent connections to keep open (default: 252 The maximum number of concurrent connections to the same host
175 8). 253 (identified by the hostname). If the limit is exceeded, then the
254 additional requests are queued until previous connections are
255 closed.
176 256
177 Not implemented currently. 257 The default value for this is 4, and it is highly advisable to not
178 258 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 259
185 $AnyEvent::HTTP::ACTIVE 260 $AnyEvent::HTTP::ACTIVE
186 The number of active connections. This is not the number of 261 The number of active connections. This is not the number of
187 currently running requests, but the number of currently open and 262 currently running requests, but the number of currently open and
188 non-idle TCP connections. This number of can be useful for 263 non-idle TCP connections. This number of can be useful for
… …
193 268
194AUTHOR 269AUTHOR
195 Marc Lehmann <schmorp@schmorp.de> 270 Marc Lehmann <schmorp@schmorp.de>
196 http://home.schmorp.de/ 271 http://home.schmorp.de/
197 272
273 With many thanks to Дмитрий Шалашов, who provided
274 countless testcases and bugreports.
275

Diff Legend

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