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

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

Diff Legend

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

Comparing AnyEvent-HTTP/README (file contents): Revision 1.11 by root, Fri Aug 14 15:21:33 2009 UTC vs. Revision 1.25 by root, Sun Jun 8 23:33:28 2014 UTC

Diff Legend

Comparing AnyEvent-HTTP/README (file contents):
Revision 1.11 by root, Fri Aug 14 15:21:33 2009 UTC vs.
Revision 1.25 by root, Sun Jun 8 23:33:28 2014 UTC