[ViewVC] Diff of: cvs/AnyEvent-HTTP/README

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.4 by root, Thu Jul 24 06:01:10 2008 UTC vs.
Revision 1.24 by root, Wed Nov 14 22:22:24 2012 UTC

…		…
12	This module is an AnyEvent user, you need to make sure that you use and	12	This module is an AnyEvent user, you need to make sure that you use and
13	run a supported event loop.	13	run a supported event loop.
14		14
15	This module implements a simple, stateless and non-blocking HTTP client.	15	This module implements a simple, stateless and non-blocking HTTP client.
16	It supports GET, POST and other request methods, cookies and more, all	16	It supports GET, POST and other request methods, cookies and more, all
17	on a very low level. It can follow redirects supports proxies and	17	on a very low level. It can follow redirects, supports proxies, and
18	automatically limits the number of connections to the values specified	18	automatically limits the number of connections to the values specified
19	in the RFC.	19	in the RFC.
20		20
21	It should generally be a "good client" that is enough for most HTTP	21	It should generally be a "good client" that is enough for most HTTP
22	tasks. Simple tasks should be simple, but complex tasks should still be	22	tasks. Simple tasks should be simple, but complex tasks should still be
…		…
28	limited support.	28	limited support.
29		29
30	METHODS	30	METHODS
31	http_get $url, key => value..., $cb->($data, $headers)	31	http_get $url, key => value..., $cb->($data, $headers)
32	Executes an HTTP-GET request. See the http_request function for	32	Executes an HTTP-GET request. See the http_request function for
33	details on additional parameters.	33	details on additional parameters and the return value.
34		34
35	http_head $url, key => value..., $cb->($data, $headers)	35	http_head $url, key => value..., $cb->($data, $headers)
36	Executes an HTTP-HEAD request. See the http_request function for	36	Executes an HTTP-HEAD request. See the http_request function for
37	details on additional parameters.	37	details on additional parameters and the return value.
38		38
39	http_post $url, $body, key => value..., $cb->($data, $headers)	39	http_post $url, $body, key => value..., $cb->($data, $headers)
40	Executes an HTTP-POST request with a request body of $body. See the	40	Executes an HTTP-POST request with a request body of $body. See the
41	http_request function for details on additional parameters.	41	http_request function for details on additional parameters and the
		42	return value.
42		43
43	http_request $method => $url, key => value..., $cb->($data, $headers)	44	http_request $method => $url, key => value..., $cb->($data, $headers)
44	Executes a HTTP request of type $method (e.g. "GET", "POST"). The	45	Executes a HTTP request of type $method (e.g. "GET", "POST"). The
45	URL must be an absolute http or https URL.	46	URL must be an absolute http or https URL.
46		47
		48	When called in void context, nothing is returned. In other contexts,
		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
		51	gets destroyed before the callback is called, the request will be
		52	cancelled.
		53
47	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
48	(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
49	with response headers as second argument.	56	response headers (and trailers) as second argument.
50		57
51	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
52	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"
53	"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
54	name. The pseudo-header "URL" contains the original URL (which can	66	The pseudo-header "URL" contains the actual URL (which can differ
55	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).
56		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.
		78
57	If the server sends a header multiple lines, then their contents	79	If the server sends a header multiple times, then their contents
58	will be joined together with "\x00".	80	will be joined together with a comma (","), as per the HTTP spec.
59		81
60	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
61	hostname, then $data will be "undef", "$headers->{Status}" will be	83	hostname, then $data will be "undef", "$headers->{Status}" will be
62	599 and the "Reason" pseudo-header will contain an error message.	84	590-599 and the "Reason" pseudo-header will contain an error
		85	message. Currently the following status codes are used:
		86
		87	595 - errors during connection etsbalishment, proxy handshake.
		88	596 - errors during TLS negotiation, request sending and header
		89	processing.
		90	597 - errors during body receiving or processing.
		91	598 - user aborted request via "on_header" or "on_body".
		92	599 - other, usually nonretryable, errors (garbled URL etc.).
63		93
64	A typical callback might look like this:	94	A typical callback might look like this:
65		95
66	sub {	96	sub {
67	my ($body, $hdr) = @_;	97	my ($body, $hdr) = @_;
…		…
76	Additional parameters are key-value pairs, and are fully optional.	106	Additional parameters are key-value pairs, and are fully optional.
77	They include:	107	They include:
78		108
79	recurse => $count (default: $MAX_RECURSE)	109	recurse => $count (default: $MAX_RECURSE)
80	Whether to recurse requests or not, e.g. on redirects,	110	Whether to recurse requests or not, e.g. on redirects,
81	authentication retries and so on, and how often to do so.	111	authentication and other retries and so on, and how often to do
		112	so.
82		113
83	headers => hashref	114	headers => hashref
84	The request headers to use. Currently, "http_request" may	115	The request headers to use. Currently, "http_request" may
85	provide its own "Host:", "Content-Length:", "Connection:" and	116	provide its own "Host:", "Content-Length:", "Connection:" and
86	"Cookie:" headers and will provide defaults for "User-Agent:"	117	"Cookie:" headers and will provide defaults at least for "TE:",
87	and "Referer:".	118	"Referer:" and "User-Agent:" (this can be suppressed by using
		119	"undef" for these headers in which case they won't be sent at
		120	all).
		121
		122	You really should provide your own "User-Agent:" header value
		123	that is appropriate for your program - I wouldn't be surprised
		124	if the default AnyEvent string gets blocked by webservers sooner
		125	or later.
		126
		127	Also, make sure that your headers names and values do not
		128	contain any embedded newlines.
88		129
89	timeout => $seconds	130	timeout => $seconds
90	The time-out to use for various stages - each connect attempt	131	The time-out to use for various stages - each connect attempt
91	will reset the timeout, as will read or write activity. Default	132	will reset the timeout, as will read or write activity, i.e.
		133	this is not an overall timeout.
		134
92	timeout is 5 minutes.	135	Default timeout is 5 minutes.
93		136
94	proxy => [$host, $port[, $scheme]] or undef	137	proxy => [$host, $port[, $scheme]] or undef
95	Use the given http proxy for all requests. If not specified,	138	Use the given http proxy for all requests, or no proxy if
96	then the default proxy (as specified by $ENV{http_proxy}) is
97	used.	139	"undef" is used.
98		140
99	$scheme must be either missing or "http" for HTTP, or "https"	141	$scheme must be either missing or must be "http" for HTTP.
100	for HTTPS.	142
		143	If not specified, then the default proxy is used (see
		144	"AnyEvent::HTTP::set_proxy").
101		145
102	body => $string	146	body => $string
103	The request body, usually empty. Will be-sent as-is (future	147	The request body, usually empty. Will be sent as-is (future
104	versions of this module might offer more options).	148	versions of this module might offer more options).
105		149
106	cookie_jar => $hash_ref	150	cookie_jar => $hash_ref
107	Passing this parameter enables (simplified) cookie-processing,	151	Passing this parameter enables (simplified) cookie-processing,
108	loosely based on the original netscape specification.	152	loosely based on the original netscape specification.
109		153
110	The $hash_ref must be an (initially empty) hash reference which	154	The $hash_ref must be an (initially empty) hash reference which
111	will get updated automatically. It is possible to save the	155	will get updated automatically. It is possible to save the
112	cookie_jar to persistent storage with something like JSON or	156	cookie jar to persistent storage with something like JSON or
113	Storable, but this is not recommended, as expire times are	157	Storable - see the "AnyEvent::HTTP::cookie_jar_expire" function
114	currently being ignored.	158	if you wish to remove expired or session-only cookies, and also
		159	for documentation on the format of the cookie jar.
115		160
116	Note that this cookie implementation is not of very high	161	Note that this cookie implementation is not meant to be
117	quality, nor meant to be complete. If you want complete cookie	162	complete. If you want complete cookie management you have to do
118	management you have to do that on your own. "cookie_jar" is	163	that on your own. "cookie_jar" is meant as a quick fix to get
119	meant as a quick fix to get some cookie-using sites working.	164	most cookie-using sites working. Cookies are a privacy disaster,
120	Cookies are a privacy disaster, do not use them unless required	165	do not use them unless required to.
		166
		167	When cookie processing is enabled, the "Cookie:" and
		168	"Set-Cookie:" headers will be set and handled by this module,
		169	otherwise they will be left untouched.
		170
		171	tls_ctx => $scheme \| $tls_ctx
		172	Specifies the AnyEvent::TLS context to be used for https
		173	connections. This parameter follows the same rules as the
		174	"tls_ctx" parameter to AnyEvent::Handle, but additionally, the
		175	two strings "low" or "high" can be specified, which give you a
		176	predefined low-security (no verification, highest compatibility)
		177	and high-security (CA and common-name verification) TLS context.
		178
		179	The default for this option is "low", which could be interpreted
		180	as "give me the page, no matter what".
		181
		182	See also the "sessionid" parameter.
		183
		184	session => $string
		185	The module might reuse connections to the same host internally.
		186	Sometimes (e.g. when using TLS), you do not want to reuse
		187	connections from other sessions. This can be achieved by setting
		188	this parameter to some unique ID (such as the address of an
		189	object storing your state data, or the TLS context) - only
		190	connections using the same unique ID will be reused.
		191
		192	on_prepare => $callback->($fh)
		193	In rare cases you need to "tune" the socket before it is used to
		194	connect (for exmaple, to bind it on a given IP address). This
		195	parameter overrides the prepare callback passed to
		196	"AnyEvent::Socket::tcp_connect" and behaves exactly the same way
		197	(e.g. it has to provide a timeout). See the description for the
		198	$prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
		199	details.
		200
		201	tcp_connect => $callback->($host, $service, $connect_cb,
		202	$prepare_cb)
		203	In even rarer cases you want total control over how
		204	AnyEvent::HTTP establishes connections. Normally it uses
		205	AnyEvent::Socket::tcp_connect to do this, but you can provide
		206	your own "tcp_connect" function - obviously, it has to follow
		207	the same calling conventions, except that it may always return a
		208	connection guard object.
		209
		210	There are probably lots of weird uses for this function,
		211	starting from tracing the hosts "http_request" actually tries to
		212	connect, to (inexact but fast) host => IP address caching or
		213	even socks protocol support.
		214
		215	on_header => $callback->($headers)
		216	When specified, this callback will be called with the header
		217	hash as soon as headers have been successfully received from the
		218	remote server (not on locally-generated errors).
		219
		220	It has to return either true (in which case AnyEvent::HTTP will
		221	continue), or false, in which case AnyEvent::HTTP will cancel
		222	the download (and call the finish callback with an error code of
121	to.	223	598).
122		224
		225	This callback is useful, among other things, to quickly reject
		226	unwanted content, which, if it is supposed to be rare, can be
		227	faster than first doing a "HEAD" request.
		228
		229	The downside is that cancelling the request makes it impossible
		230	to re-use the connection. Also, the "on_header" callback will
		231	not receive any trailer (headers sent after the response body).
		232
		233	Example: cancel the request unless the content-type is
		234	"text/html".
		235
		236	on_header => sub {
		237	$_[0]{"content-type"} =~ /^text\/html\s*(?:;\|$)/
		238	},
		239
		240	on_body => $callback->($partial_body, $headers)
		241	When specified, all body data will be passed to this callback
		242	instead of to the completion callback. The completion callback
		243	will get the empty string instead of the body data.
		244
		245	It has to return either true (in which case AnyEvent::HTTP will
		246	continue), or false, in which case AnyEvent::HTTP will cancel
		247	the download (and call the completion callback with an error
		248	code of 598).
		249
		250	The downside to cancelling the request is that it makes it
		251	impossible to re-use the connection.
		252
		253	This callback is useful when the data is too large to be held in
		254	memory (so the callback writes it to a file) or when only some
		255	information should be extracted, or when the body should be
		256	processed incrementally.
		257
		258	It is usually preferred over doing your own body handling via
		259	"want_body_handle", but in case of streaming APIs, where HTTP is
		260	only used to create a connection, "want_body_handle" is the
		261	better alternative, as it allows you to install your own event
		262	handler, reducing resource usage.
		263
		264	want_body_handle => $enable
		265	When enabled (default is disabled), the behaviour of
		266	AnyEvent::HTTP changes considerably: after parsing the headers,
		267	and instead of downloading the body (if any), the completion
		268	callback will be called. Instead of the $body argument
		269	containing the body data, the callback will receive the
		270	AnyEvent::Handle object associated with the connection. In error
		271	cases, "undef" will be passed. When there is no body (e.g.
		272	status 304), the empty string will be passed.
		273
		274	The handle object might or might not be in TLS mode, might be
		275	connected to a proxy, be a persistent connection, use chunked
		276	transfer encoding etc., and configured in unspecified ways. The
		277	user is responsible for this handle (it will not be used by this
		278	module anymore).
		279
		280	This is useful with some push-type services, where, after the
		281	initial headers, an interactive protocol is used (typical
		282	example would be the push-style twitter API which starts a
		283	JSON/XML stream).
		284
		285	If you think you need this, first have a look at "on_body", to
		286	see if that doesn't solve your problem in a better way.
		287
		288	persistent => $boolean
		289	Try to create/reuse a persistent connection. When this flag is
		290	set (default: true for idempotent requests, false for all
		291	others), then "http_request" tries to re-use an existing
		292	(previously-created) persistent connection to the host and,
		293	failing that, tries to create a new one.
		294
		295	Requests failing in certain ways will be automatically retried
		296	once, which is dangerous for non-idempotent requests, which is
		297	why it defaults to off for them. The reason for this is because
		298	the bozos who designed HTTP/1.1 made it impossible to
		299	distinguish between a fatal error and a normal connection
		300	timeout, so you never know whether there was a problem with your
		301	request or not.
		302
		303	When reusing an existent connection, many parameters (such as
		304	TLS context) will be ignored. See the "session" parameter for a
		305	workaround.
		306
		307	keepalive => $boolean
		308	Only used when "persistent" is also true. This parameter decides
		309	whether "http_request" tries to handshake a HTTP/1.0-style
		310	keep-alive connection (as opposed to only a HTTP/1.1 persistent
		311	connection).
		312
		313	The default is true, except when using a proxy, in which case it
		314	defaults to false, as HTTP/1.0 proxies cannot support this in a
		315	meaningful way.
		316
		317	handle_params => { key => value ... }
		318	The key-value pairs in this hash will be passed to any
		319	AnyEvent::Handle constructor that is called - not all requests
		320	will create a handle, and sometimes more than one is created, so
		321	this parameter is only good for setting hints.
		322
		323	Example: set the maximum read size to 4096, to potentially
		324	conserve memory at the cost of speed.
		325
		326	handle_params => {
		327	max_read_size => 4096,
		328	},
		329
123	Example: make a simple HTTP GET request for http://www.nethype.de/	330	Example: do a simple HTTP GET request for http://www.nethype.de/ and
		331	print the response body.
124		332
125	http_request GET => "http://www.nethype.de/", sub {	333	http_request GET => "http://www.nethype.de/", sub {
126	my ($body, $hdr) = @_;	334	my ($body, $hdr) = @_;
127	print "$body\n";	335	print "$body\n";
128	};	336	};
129		337
130	Example: make a HTTP HEAD request on https://www.google.com/, use a	338	Example: do a HTTP HEAD request on https://www.google.com/, use a
131	timeout of 30 seconds.	339	timeout of 30 seconds.
132		340
133	http_request	341	http_request
134	GET => "https://www.google.com",	342	HEAD => "https://www.google.com",
		343	headers => { "user-agent" => "MySearchClient 1.0" },
135	timeout => 30,	344	timeout => 30,
136	sub {	345	sub {
137	my ($body, $hdr) = @_;	346	my ($body, $hdr) = @_;
138	use Data::Dumper;	347	use Data::Dumper;
139	print Dumper $hdr;	348	print Dumper $hdr;
140	}	349	}
141	;	350	;
142		351
		352	Example: do another simple HTTP GET request, but immediately try to
		353	cancel it.
		354
		355	my $request = http_request GET => "http://www.nethype.de/", sub {
		356	my ($body, $hdr) = @_;
		357	print "$body\n";
		358	};
		359
		360	undef $request;
		361
		362	DNS CACHING
		363	AnyEvent::HTTP uses the AnyEvent::Socket::tcp_connect function for the
		364	actual connection, which in turn uses AnyEvent::DNS to resolve
		365	hostnames. The latter is a simple stub resolver and does no caching on
		366	its own. If you want DNS caching, you currently have to provide your own
		367	default resolver (by storing a suitable resolver object in
		368	$AnyEvent::DNS::RESOLVER) or your own "tcp_connect" callback.
		369
143	GLOBAL FUNCTIONS AND VARIABLES	370	GLOBAL FUNCTIONS AND VARIABLES
144	AnyEvent::HTTP::set_proxy "proxy-url"	371	AnyEvent::HTTP::set_proxy "proxy-url"
145	Sets the default proxy server to use. The proxy-url must begin with	372	Sets the default proxy server to use. The proxy-url must begin with
146	a string of the form "http://host:port" (optionally "https:...").	373	a string of the form "http://host:port", croaks otherwise.
		374
		375	To clear an already-set proxy, use "undef".
		376
		377	When AnyEvent::HTTP is laoded for the first time it will query the
		378	default proxy from the operating system, currently by looking at
		379	"$ENV{http_proxy"}.
		380
		381	AnyEvent::HTTP::cookie_jar_expire $jar[, $session_end]
		382	Remove all cookies from the cookie jar that have been expired. If
		383	$session_end is given and true, then additionally remove all session
		384	cookies.
		385
		386	You should call this function (with a true $session_end) before you
		387	save cookies to disk, and you should call this function after
		388	loading them again. If you have a long-running program you can
		389	additonally call this function from time to time.
		390
		391	A cookie jar is initially an empty hash-reference that is managed by
		392	this module. It's format is subject to change, but currently it is
		393	like this:
		394
		395	The key "version" has to contain 1, otherwise the hash gets emptied.
		396	All other keys are hostnames or IP addresses pointing to
		397	hash-references. The key for these inner hash references is the
		398	server path for which this cookie is meant, and the values are again
		399	hash-references. The keys of those hash-references is the cookie
		400	name, and the value, you guessed it, is another hash-reference, this
		401	time with the key-value pairs from the cookie, except for "expires"
		402	and "max-age", which have been replaced by a "_expires" key that
		403	contains the cookie expiry timestamp.
		404
		405	Here is an example of a cookie jar with a single cookie, so you have
		406	a chance of understanding the above paragraph:
		407
		408	{
		409	version => 1,
		410	"10.0.0.1" => {
		411	"/" => {
		412	"mythweb_id" => {
		413	_expires => 1293917923,
		414	value => "ooRung9dThee3ooyXooM1Ohm",
		415	},
		416	},
		417	},
		418	}
		419
		420	$date = AnyEvent::HTTP::format_date $timestamp
		421	Takes a POSIX timestamp (seconds since the epoch) and formats it as
		422	a HTTP Date (RFC 2616).
		423
		424	$timestamp = AnyEvent::HTTP::parse_date $date
		425	Takes a HTTP Date (RFC 2616) or a Cookie date (netscape cookie spec)
		426	or a bunch of minor variations of those, and returns the
		427	corresponding POSIX timestamp, or "undef" if the date cannot be
		428	parsed.
147		429
148	$AnyEvent::HTTP::MAX_RECURSE	430	$AnyEvent::HTTP::MAX_RECURSE
149	The default value for the "recurse" request parameter (default: 10).	431	The default value for the "recurse" request parameter (default: 10).
150		432
		433	$AnyEvent::HTTP::TIMEOUT
		434	The default timeout for connection operations (default: 300).
		435
151	$AnyEvent::HTTP::USERAGENT	436	$AnyEvent::HTTP::USERAGENT
152	The default value for the "User-Agent" header (the default is	437	The default value for the "User-Agent" header (the default is
153	"Mozilla/5.0 (compatible; AnyEvent::HTTP/$VERSION;	438	"Mozilla/5.0 (compatible; U; AnyEvent-HTTP/$VERSION;
154	+http://software.schmorp.de/pkg/AnyEvent)").	439	+http://software.schmorp.de/pkg/AnyEvent)").
155		440
156	$AnyEvent::HTTP::MAX_PERSISTENT	441	$AnyEvent::HTTP::MAX_PER_HOST
157	The maximum number of persistent connections to keep open (default:	442	The maximum number of concurrent connections to the same host
158	8).	443	(identified by the hostname). If the limit is exceeded, then the
		444	additional requests are queued until previous connections are
		445	closed. Both persistent and non-persistent connections are counted
		446	in this limit.
159		447
160	Not implemented currently.	448	The default value for this is 4, and it is highly advisable to not
		449	increase it much.
		450
		451	For comparison: the RFC's recommend 4 non-persistent or 2 persistent
		452	connections, older browsers used 2, newers (such as firefox 3)
		453	typically use 6, and Opera uses 8 because like, they have the
		454	fastest browser and give a shit for everybody else on the planet.
161		455
162	$AnyEvent::HTTP::PERSISTENT_TIMEOUT	456	$AnyEvent::HTTP::PERSISTENT_TIMEOUT
163	The maximum time to cache a persistent connection, in seconds	457	The time after which idle persistent conenctions get closed by
164	(default: 2).	458	AnyEvent::HTTP (default: 3).
165
166	Not implemented currently.
167		459
168	$AnyEvent::HTTP::ACTIVE	460	$AnyEvent::HTTP::ACTIVE
169	The number of active connections. This is not the number of	461	The number of active connections. This is not the number of
170	currently running requests, but the number of currently open and	462	currently running requests, but the number of currently open and
171	non-idle TCP connections. This number of can be useful for	463	non-idle TCP connections. This number can be useful for
172	load-leveling.	464	load-leveling.
		465
		466	SHOWCASE
		467	This section contaisn some more elaborate "real-world" examples or code
		468	snippets.
		469
		470	HTTP/1.1 FILE DOWNLOAD
		471	Downloading files with HTTP can be quite tricky, especially when
		472	something goes wrong and you want to resume.
		473
		474	Here is a function that initiates and resumes a download. It uses the
		475	last modified time to check for file content changes, and works with
		476	many HTTP/1.0 servers as well, and usually falls back to a complete
		477	re-download on older servers.
		478
		479	It calls the completion callback with either "undef", which means a
		480	nonretryable error occured, 0 when the download was partial and should
		481	be retried, and 1 if it was successful.
		482
		483	use AnyEvent::HTTP;
		484
		485	sub download($$$) {
		486	my ($url, $file, $cb) = @_;
		487
		488	open my $fh, "+<", $file
		489	or die "$file: $!";
		490
		491	my %hdr;
		492	my $ofs = 0;
		493
		494	warn stat $fh;
		495	warn -s _;
		496	if (stat $fh and -s _) {
		497	$ofs = -s _;
		498	warn "-s is ", $ofs;
		499	$hdr{"if-unmodified-since"} = AnyEvent::HTTP::format_date +(stat _)[9];
		500	$hdr{"range"} = "bytes=$ofs-";
		501	}
		502
		503	http_get $url,
		504	headers => \%hdr,
		505	on_header => sub {
		506	my ($hdr) = @_;
		507
		508	if ($hdr->{Status} == 200 && $ofs) {
		509	# resume failed
		510	truncate $fh, $ofs = 0;
		511	}
		512
		513	sysseek $fh, $ofs, 0;
		514
		515	1
		516	},
		517	on_body => sub {
		518	my ($data, $hdr) = @_;
		519
		520	if ($hdr->{Status} =~ /^2/) {
		521	length $data == syswrite $fh, $data
		522	or return; # abort on write errors
		523	}
		524
		525	1
		526	},
		527	sub {
		528	my (undef, $hdr) = @_;
		529
		530	my $status = $hdr->{Status};
		531
		532	if (my $time = AnyEvent::HTTP::parse_date $hdr->{"last-modified"}) {
		533	utime $fh, $time, $time;
		534	}
		535
		536	if ($status == 200 \|\| $status == 206 \|\| $status == 416) {
		537	# download ok \|\| resume ok \|\| file already fully downloaded
		538	$cb->(1, $hdr);
		539
		540	} elsif ($status == 412) {
		541	# file has changed while resuming, delete and retry
		542	unlink $file;
		543	$cb->(0, $hdr);
		544
		545	} elsif ($status == 500 or $status == 503 or $status =~ /^59/) {
		546	# retry later
		547	$cb->(0, $hdr);
		548
		549	} else {
		550	$cb->(undef, $hdr);
		551	}
		552	}
		553	;
		554	}
		555
		556	download "http://server/somelargefile", "/tmp/somelargefile", sub {
		557	if ($_[0]) {
		558	print "OK!\n";
		559	} elsif (defined $_[0]) {
		560	print "please retry later\n";
		561	} else {
		562	print "ERROR\n";
		563	}
		564	};
		565
		566	SOCKS PROXIES
		567	Socks proxies are not directly supported by AnyEvent::HTTP. You can
		568	compile your perl to support socks, or use an external program such as
		569	socksify (dante) or tsocks to make your program use a socks proxy
		570	transparently.
		571
		572	Alternatively, for AnyEvent::HTTP only, you can use your own
		573	"tcp_connect" function that does the proxy handshake - here is an
		574	example that works with socks4a proxies:
		575
		576	use Errno;
		577	use AnyEvent::Util;
		578	use AnyEvent::Socket;
		579	use AnyEvent::Handle;
		580
		581	# host, port and username of/for your socks4a proxy
		582	my $socks_host = "10.0.0.23";
		583	my $socks_port = 9050;
		584	my $socks_user = "";
		585
		586	sub socks4a_connect {
		587	my ($host, $port, $connect_cb, $prepare_cb) = @_;
		588
		589	my $hdl = new AnyEvent::Handle
		590	connect => [$socks_host, $socks_port],
		591	on_prepare => sub { $prepare_cb->($_[0]{fh}) },
		592	on_error => sub { $connect_cb->() },
		593	;
		594
		595	$hdl->push_write (pack "CCnNZZ", 4, 1, $port, 1, $socks_user, $host);
		596
		597	$hdl->push_read (chunk => 8, sub {
		598	my ($hdl, $chunk) = @_;
		599	my ($status, $port, $ipn) = unpack "xCna4", $chunk;
		600
		601	if ($status == 0x5a) {
		602	$connect_cb->($hdl->{fh}, (format_address $ipn) . ":$port");
		603	} else {
		604	$! = Errno::ENXIO; $connect_cb->();
		605	}
		606	});
		607
		608	$hdl
		609	}
		610
		611	Use "socks4a_connect" instead of "tcp_connect" when doing
		612	"http_request"s, possibly after switching off other proxy types:
		613
		614	AnyEvent::HTTP::set_proxy undef; # usually you do not want other proxies
		615
		616	http_get 'http://www.google.com', tcp_connect => \&socks4a_connect, sub {
		617	my ($data, $headers) = @_;
		618	...
		619	};
173		620
174	SEE ALSO	621	SEE ALSO
175	AnyEvent.	622	AnyEvent.
176		623
177	AUTHOR	624	AUTHOR
178	Marc Lehmann <schmorp@schmorp.de>	625	Marc Lehmann <schmorp@schmorp.de>
179	http://home.schmorp.de/	626	http://home.schmorp.de/
180		627
		628	With many thanks to Дмитрий Шалашов, who provided
		629	countless testcases and bugreports.
		630

Diff Legend

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

Comparing AnyEvent-HTTP/README (file contents): Revision 1.4 by root, Thu Jul 24 06:01:10 2008 UTC vs. Revision 1.24 by root, Wed Nov 14 22:22:24 2012 UTC

Diff Legend

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.4 by root, Thu Jul 24 06:01:10 2008 UTC vs.
Revision 1.24 by root, Wed Nov 14 22:22:24 2012 UTC