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

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.13 by root, Wed Jun 16 19:17:30 2010 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" (uppercase to avoid clashing 59 response headers, the "pseudo-headers" (uppercase to avoid clashing
60 with possible response headers) "HTTPVersion", "Status" and "Reason" 60 with possible response headers) "HTTPVersion", "Status" and "Reason"
61 contain the three parts of the HTTP Status-Line of the same name. 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".
62 65
63 The pseudo-header "URL" contains the actual URL (which can differ 66 The pseudo-header "URL" contains the actual URL (which can differ
64 from the requested URL when following redirects - for example, you 67 from the requested URL when following redirects - for example, you
65 might get an error that your URL scheme is not supported even though 68 might get an error that your URL scheme is not supported even though
66 your URL is a valid http URL because it redirected to an ftp URL, in 69 your URL is a valid http URL because it redirected to an ftp URL, in
… …
160 parameter overrides the prepare callback passed to 163 parameter overrides the prepare callback passed to
161 "AnyEvent::Socket::tcp_connect" and behaves exactly the same way 164 "AnyEvent::Socket::tcp_connect" and behaves exactly the same way
162 (e.g. it has to provide a timeout). See the description for the 165 (e.g. it has to provide a timeout). See the description for the
163 $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for 166 $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
164 details. 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.
165 182
166 on_header => $callback->($headers) 183 on_header => $callback->($headers)
167 When specified, this callback will be called with the header 184 When specified, this callback will be called with the header
168 hash as soon as headers have been successfully received from the 185 hash as soon as headers have been successfully received from the
169 remote server (not on locally-generated errors). 186 remote server (not on locally-generated errors).
… …
272 a string of the form "http://host:port" (optionally "https:..."), 289 a string of the form "http://host:port" (optionally "https:..."),
273 croaks otherwise. 290 croaks otherwise.
274 291
275 To clear an already-set proxy, use "undef". 292 To clear an already-set proxy, use "undef".
276 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.
301
277 $AnyEvent::HTTP::MAX_RECURSE 302 $AnyEvent::HTTP::MAX_RECURSE
278 The default value for the "recurse" request parameter (default: 10). 303 The default value for the "recurse" request parameter (default: 10).
279 304
280 $AnyEvent::HTTP::USERAGENT 305 $AnyEvent::HTTP::USERAGENT
281 The default value for the "User-Agent" header (the default is 306 The default value for the "User-Agent" header (the default is
… …
295 The number of active connections. This is not the number of 320 The number of active connections. This is not the number of
296 currently running requests, but the number of currently open and 321 currently running requests, but the number of currently open and
297 non-idle TCP connections. This number of can be useful for 322 non-idle TCP connections. This number of can be useful for
298 load-leveling. 323 load-leveling.
299 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
300SEE ALSO 380SEE ALSO
301 AnyEvent. 381 AnyEvent.
302 382
303AUTHOR 383AUTHOR
304 Marc Lehmann <schmorp@schmorp.de> 384 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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