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

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.8 by root, Tue Jul 7 00:15:32 2009 UTC vs.
Revision 1.12 by root, Sat Dec 5 15:37:07 2009 UTC

… …
90 90
91 headers => hashref 91 headers => hashref
92 The request headers to use. Currently, "http_request" may 92 The request headers to use. Currently, "http_request" may
93 provide its own "Host:", "Content-Length:", "Connection:" and 93 provide its own "Host:", "Content-Length:", "Connection:" and
94 "Cookie:" headers and will provide defaults for "User-Agent:" 94 "Cookie:" headers and will provide defaults for "User-Agent:"
95 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).
96 97
97 timeout => $seconds 98 timeout => $seconds
98 The time-out to use for various stages - each connect attempt 99 The time-out to use for various stages - each connect attempt
99 will reset the timeout, as will read or write activity. Default 100 will reset the timeout, as will read or write activity, i.e.
101 this is not an overall timeout.
102
100 timeout is 5 minutes. 103 Default timeout is 5 minutes.
101 104
102 proxy => [$host, $port[, $scheme]] or undef 105 proxy => [$host, $port[, $scheme]] or undef
103 Use the given http proxy for all requests. If not specified, 106 Use the given http proxy for all requests. If not specified,
104 then the default proxy (as specified by $ENV{http_proxy}) is 107 then the default proxy (as specified by $ENV{http_proxy}) is
105 used. 108 used.
106 109
107 $scheme must be either missing or "http" for HTTP, or "https" 110 $scheme must be either missing, "http" for HTTP or "https" for
108 for HTTPS. 111 HTTPS.
109 112
110 body => $string 113 body => $string
111 The request body, usually empty. Will be-sent as-is (future 114 The request body, usually empty. Will be-sent as-is (future
112 versions of this module might offer more options). 115 versions of this module might offer more options).
113 116
… …
137 and high-security (CA and common-name verification) TLS context. 140 and high-security (CA and common-name verification) TLS context.
138 141
139 The default for this option is "low", which could be interpreted 142 The default for this option is "low", which could be interpreted
140 as "give me the page, no matter what". 143 as "give me the page, no matter what".
141 144
145 on_prepare => $callback->($fh)
146 In rare cases you need to "tune" the socket before it is used to
147 connect (for exmaple, to bind it on a given IP address). This
148 parameter overrides the prepare callback passed to
149 "AnyEvent::Socket::tcp_connect" and behaves exactly the same way
150 (e.g. it has to provide a timeout). See the description for the
151 $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
152 details.
153
142 on_header => $callback->($headers) 154 on_header => $callback->($headers)
143 When specified, this callback will be called with the header 155 When specified, this callback will be called with the header
144 hash as soon as headers have been successfully received from the 156 hash as soon as headers have been successfully received from the
145 remote server (not on locally-generated errors). 157 remote server (not on locally-generated errors).
146 158
… …
174 memory (so the callback writes it to a file) or when only some 186 memory (so the callback writes it to a file) or when only some
175 information should be extracted, or when the body should be 187 information should be extracted, or when the body should be
176 processed incrementally. 188 processed incrementally.
177 189
178 It is usually preferred over doing your own body handling via 190 It is usually preferred over doing your own body handling via
179 "want_body_handle". 191 "want_body_handle", but in case of streaming APIs, where HTTP is
192 only used to create a connection, "want_body_handle" is the
193 better alternative, as it allows you to install your own event
194 handler, reducing resource usage.
180 195
181 want_body_handle => $enable 196 want_body_handle => $enable
182 When enabled (default is disabled), the behaviour of 197 When enabled (default is disabled), the behaviour of
183 AnyEvent::HTTP changes considerably: after parsing the headers, 198 AnyEvent::HTTP changes considerably: after parsing the headers,
184 and instead of downloading the body (if any), the completion 199 and instead of downloading the body (if any), the completion
… …
197 initial headers, an interactive protocol is used (typical 212 initial headers, an interactive protocol is used (typical
198 example would be the push-style twitter API which starts a 213 example would be the push-style twitter API which starts a
199 JSON/XML stream). 214 JSON/XML stream).
200 215
201 If you think you need this, first have a look at "on_body", to 216 If you think you need this, first have a look at "on_body", to
202 see if that doesn'T solve your problem in a better way. 217 see if that doesn't solve your problem in a better way.
203 218
204 Example: make a simple HTTP GET request for http://www.nethype.de/ 219 Example: make a simple HTTP GET request for http://www.nethype.de/
205 220
206 http_request GET => "http://www.nethype.de/", sub { 221 http_request GET => "http://www.nethype.de/", sub {
207 my ($body, $hdr) = @_; 222 my ($body, $hdr) = @_;
… …
232 undef $request; 247 undef $request;
233 248
234 GLOBAL FUNCTIONS AND VARIABLES 249 GLOBAL FUNCTIONS AND VARIABLES
235 AnyEvent::HTTP::set_proxy "proxy-url" 250 AnyEvent::HTTP::set_proxy "proxy-url"
236 Sets the default proxy server to use. The proxy-url must begin with 251 Sets the default proxy server to use. The proxy-url must begin with
237 a string of the form "http://host:port" (optionally "https:..."). 252 a string of the form "http://host:port" (optionally "https:..."),
253 croaks otherwise.
254
255 To clear an already-set proxy, use "undef".
238 256
239 $AnyEvent::HTTP::MAX_RECURSE 257 $AnyEvent::HTTP::MAX_RECURSE
240 The default value for the "recurse" request parameter (default: 10). 258 The default value for the "recurse" request parameter (default: 10).
241 259
242 $AnyEvent::HTTP::USERAGENT 260 $AnyEvent::HTTP::USERAGENT
243 The default value for the "User-Agent" header (the default is 261 The default value for the "User-Agent" header (the default is
244 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION; 262 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
245 +http://software.schmorp.de/pkg/AnyEvent)"). 263 +http://software.schmorp.de/pkg/AnyEvent)").
246 264
247 $AnyEvent::HTTP::MAX_PER_HOST 265 $AnyEvent::HTTP::MAX_PER_HOST
248 The maximum number of concurrent conenctions to the same host 266 The maximum number of concurrent connections to the same host
249 (identified by the hostname). If the limit is exceeded, then the 267 (identified by the hostname). If the limit is exceeded, then the
250 additional requests are queued until previous connections are 268 additional requests are queued until previous connections are
251 closed. 269 closed.
252 270
253 The default value for this is 4, and it is highly advisable to not 271 The default value for this is 4, and it is highly advisable to not

Diff Legend

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