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

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

Diff Legend

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

Comparing AnyEvent-HTTP/README (file contents): Revision 1.13 by root, Wed Jun 16 19:17:30 2010 UTC vs. Revision 1.19 by root, Sat Feb 19 06:46:14 2011 UTC

Diff Legend

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.13 by root, Wed Jun 16 19:17:30 2010 UTC vs.
Revision 1.19 by root, Sat Feb 19 06:46:14 2011 UTC