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

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.9 by root, Sat Jul 25 01:29:09 2009 UTC vs.
Revision 1.14 by root, Fri Dec 31 03:47:32 2010 UTC

… …
46 URL must be an absolute http or https URL. 46 URL must be an absolute http or https URL.
47 47
48 When called in void context, nothing is returned. In other contexts, 48 When called in void context, nothing is returned. In other contexts,
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 callback is called, the request will be
52 cancelled. 52 cancelled.
53 53
54 The callback will be called with the response body data as first 54 The callback will be called with the response body data as first
55 argument (or "undef" if an error occured), and a hash-ref with 55 argument (or "undef" if an error occured), and a hash-ref with
56 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" (uppercase to avoid clashing
60 with possible response headers) "HTTPVersion", "Status" and "Reason"
60 "Reason" contain the three parts of the HTTP Status-Line of the same 61 contain the three parts of the HTTP Status-Line of the same name. If
62 an error occurs during the body phase of a request, then the
63 original "Status" and "Reason" values from the header are available
64 as "OrigStatus" and "OrigReason".
65
61 name. The pseudo-header "URL" contains the original URL (which can 66 The pseudo-header "URL" contains the actual URL (which can differ
62 differ from the requested URL when following redirects). 67 from the requested URL when following redirects - for example, you
68 might get an error that your URL scheme is not supported even though
69 your URL is a valid http URL because it redirected to an ftp URL, in
70 which case you can look at the URL pseudo header).
71
72 The pseudo-header "Redirect" only exists when the request was a
73 result of an internal redirect. In that case it is an array
74 reference with the "($data, $headers)" from the redirect response.
75 Note that this response could in turn be the result of a redirect
76 itself, and "$headers->{Redirect}[1]{Redirect}" will then contain
77 the original response, and so on.
63 78
64 If the server sends a header multiple times, then their contents 79 If the server sends a header multiple times, then their contents
65 will be joined together with a comma (","), as per the HTTP spec. 80 will be joined together with a comma (","), as per the HTTP spec.
66 81
67 If an internal error occurs, such as not being able to resolve a 82 If an internal error occurs, such as not being able to resolve a
… …
90 105
91 headers => hashref 106 headers => hashref
92 The request headers to use. Currently, "http_request" may 107 The request headers to use. Currently, "http_request" may
93 provide its own "Host:", "Content-Length:", "Connection:" and 108 provide its own "Host:", "Content-Length:", "Connection:" and
94 "Cookie:" headers and will provide defaults for "User-Agent:" 109 "Cookie:" headers and will provide defaults for "User-Agent:"
95 and "Referer:". 110 and "Referer:" (this can be suppressed by using "undef" for
111 these headers in which case they won't be sent at all).
96 112
97 timeout => $seconds 113 timeout => $seconds
98 The time-out to use for various stages - each connect attempt 114 The time-out to use for various stages - each connect attempt
99 will reset the timeout, as will read or write activity. Default 115 will reset the timeout, as will read or write activity, i.e.
116 this is not an overall timeout.
117
100 timeout is 5 minutes. 118 Default timeout is 5 minutes.
101 119
102 proxy => [$host, $port[, $scheme]] or undef 120 proxy => [$host, $port[, $scheme]] or undef
103 Use the given http proxy for all requests. If not specified, 121 Use the given http proxy for all requests. If not specified,
104 then the default proxy (as specified by $ENV{http_proxy}) is 122 then the default proxy (as specified by $ENV{http_proxy}) is
105 used. 123 used.
106 124
107 $scheme must be either missing or "http" for HTTP, or "https" 125 $scheme must be either missing, "http" for HTTP or "https" for
108 for HTTPS. 126 HTTPS.
109 127
110 body => $string 128 body => $string
111 The request body, usually empty. Will be-sent as-is (future 129 The request body, usually empty. Will be-sent as-is (future
112 versions of this module might offer more options). 130 versions of this module might offer more options).
113 131
… …
136 predefined low-security (no verification, highest compatibility) 154 predefined low-security (no verification, highest compatibility)
137 and high-security (CA and common-name verification) TLS context. 155 and high-security (CA and common-name verification) TLS context.
138 156
139 The default for this option is "low", which could be interpreted 157 The default for this option is "low", which could be interpreted
140 as "give me the page, no matter what". 158 as "give me the page, no matter what".
159
160 on_prepare => $callback->($fh)
161 In rare cases you need to "tune" the socket before it is used to
162 connect (for exmaple, to bind it on a given IP address). This
163 parameter overrides the prepare callback passed to
164 "AnyEvent::Socket::tcp_connect" and behaves exactly the same way
165 (e.g. it has to provide a timeout). See the description for the
166 $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
167 details.
168
169 tcp_connect => $callback->($host, $service, $connect_cb,
170 $prepare_cb)
171 In even rarer cases you want total control over how
172 AnyEvent::HTTP establishes connections. Normally it uses
173 AnyEvent::Socket::tcp_connect to do this, but you can provide
174 your own "tcp_connect" function - obviously, it has to follow
175 the same calling conventions, except that it may always return a
176 connection guard object.
177
178 There are probably lots of weird uses for this function,
179 starting from tracing the hosts "http_request" actually tries to
180 connect, to (inexact but fast) host => IP address caching or
181 even socks protocol support.
141 182
142 on_header => $callback->($headers) 183 on_header => $callback->($headers)
143 When specified, this callback will be called with the header 184 When specified, this callback will be called with the header
144 hash as soon as headers have been successfully received from the 185 hash as soon as headers have been successfully received from the
145 remote server (not on locally-generated errors). 186 remote server (not on locally-generated errors).
… …
232 print "$body\n"; 273 print "$body\n";
233 }; 274 };
234 275
235 undef $request; 276 undef $request;
236 277
278 DNS CACHING
279 AnyEvent::HTTP uses the AnyEvent::Socket::tcp_connect function for the
280 actual connection, which in turn uses AnyEvent::DNS to resolve
281 hostnames. The latter is a simple stub resolver and does no caching on
282 its own. If you want DNS caching, you currently have to provide your own
283 default resolver (by storing a suitable resolver object in
284 $AnyEvent::DNS::RESOLVER).
285
237 GLOBAL FUNCTIONS AND VARIABLES 286 GLOBAL FUNCTIONS AND VARIABLES
238 AnyEvent::HTTP::set_proxy "proxy-url" 287 AnyEvent::HTTP::set_proxy "proxy-url"
239 Sets the default proxy server to use. The proxy-url must begin with 288 Sets the default proxy server to use. The proxy-url must begin with
240 a string of the form "http://host:port" (optionally "https:..."). 289 a string of the form "http://host:port" (optionally "https:..."),
290 croaks otherwise.
291
292 To clear an already-set proxy, use "undef".
293
294 $date = AnyEvent::HTTP::format_date $timestamp
295 Takes a POSIX timestamp (seconds since the epoch) and formats it as
296 a HTTP Date (RFC 2616).
297
298 $timestamp = AnyEvent::HTTP::parse_date $date
299 Takes a HTTP Date (RFC 2616) and returns the corresponding POSIX
300 timestamp, or "undef" if the date cannot be parsed.
241 301
242 $AnyEvent::HTTP::MAX_RECURSE 302 $AnyEvent::HTTP::MAX_RECURSE
243 The default value for the "recurse" request parameter (default: 10). 303 The default value for the "recurse" request parameter (default: 10).
244 304
245 $AnyEvent::HTTP::USERAGENT 305 $AnyEvent::HTTP::USERAGENT
246 The default value for the "User-Agent" header (the default is 306 The default value for the "User-Agent" header (the default is
247 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION; 307 "Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
248 +http://software.schmorp.de/pkg/AnyEvent)"). 308 +http://software.schmorp.de/pkg/AnyEvent)").
249 309
250 $AnyEvent::HTTP::MAX_PER_HOST 310 $AnyEvent::HTTP::MAX_PER_HOST
251 The maximum number of concurrent conenctions to the same host 311 The maximum number of concurrent connections to the same host
252 (identified by the hostname). If the limit is exceeded, then the 312 (identified by the hostname). If the limit is exceeded, then the
253 additional requests are queued until previous connections are 313 additional requests are queued until previous connections are
254 closed. 314 closed.
255 315
256 The default value for this is 4, and it is highly advisable to not 316 The default value for this is 4, and it is highly advisable to not
… …
260 The number of active connections. This is not the number of 320 The number of active connections. This is not the number of
261 currently running requests, but the number of currently open and 321 currently running requests, but the number of currently open and
262 non-idle TCP connections. This number of can be useful for 322 non-idle TCP connections. This number of can be useful for
263 load-leveling. 323 load-leveling.
264 324
325 SOCKS PROXIES
326 Socks proxies are not directly supported by AnyEvent::HTTP. You can
327 compile your perl to support socks, or use an external program such as
328 socksify (dante) or tsocks to make your program use a socks proxy
329 transparently.
330
331 Alternatively, for AnyEvent::HTTP only, you can use your own
332 "tcp_connect" function that does the proxy handshake - here is an
333 example that works with socks4a proxies:
334
335 use Errno;
336 use AnyEvent::Util;
337 use AnyEvent::Socket;
338 use AnyEvent::Handle;
339
340 # host, port and username of/for your socks4a proxy
341 my $socks_host = "10.0.0.23";
342 my $socks_port = 9050;
343 my $socks_user = "";
344
345 sub socks4a_connect {
346 my ($host, $port, $connect_cb, $prepare_cb) = @_;
347
348 my $hdl = new AnyEvent::Handle
349 connect => [$socks_host, $socks_port],
350 on_prepare => sub { $prepare_cb->($_[0]{fh}) },
351 on_error => sub { $connect_cb->() },
352 ;
353
354 $hdl->push_write (pack "CCnNZ*Z*", 4, 1, $port, 1, $socks_user, $host);
355
356 $hdl->push_read (chunk => 8, sub {
357 my ($hdl, $chunk) = @_;
358 my ($status, $port, $ipn) = unpack "xCna4", $chunk;
359
360 if ($status == 0x5a) {
361 $connect_cb->($hdl->{fh}, (format_address $ipn) . ":$port");
362 } else {
363 $! = Errno::ENXIO; $connect_cb->();
364 }
365 });
366
367 $hdl
368 }
369
370 Use "socks4a_connect" instead of "tcp_connect" when doing
371 "http_request"s, possibly after switching off other proxy types:
372
373 AnyEvent::HTTP::set_proxy undef; # usually you do not want other proxies
374
375 http_get 'http://www.google.com', tcp_connect => \&socks4a_connect, sub {
376 my ($data, $headers) = @_;
377 ...
378 };
379
265SEE ALSO 380SEE ALSO
266 AnyEvent. 381 AnyEvent.
267 382
268AUTHOR 383AUTHOR
269 Marc Lehmann <schmorp@schmorp.de> 384 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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