--- AnyEvent-HTTP/README	2011/01/04 08:29:28	1.15
+++ AnyEvent-HTTP/README	2011/01/12 03:30:05	1.17
@@ -14,7 +14,7 @@
 
     This module implements a simple, stateless and non-blocking HTTP client.
     It supports GET, POST and other request methods, cookies and more, all
-    on a very low level. It can follow redirects supports proxies and
+    on a very low level. It can follow redirects, supports proxies, and
     automatically limits the number of connections to the values specified
     in the RFC.
 
@@ -453,7 +453,107 @@
         non-idle TCP connections. This number can be useful for
         load-leveling.
 
-  SOCKS PROXIES
+  SHOWCASE
+    This section contaisn some more elaborate "real-world" examples or code
+    snippets.
+
+  HTTP/1.1 FILE DOWNLOAD
+    Downloading files with HTTP cna be quite tricky, especially when
+    something goes wrong and you want tor esume.
+
+    Here is a function that initiates and resumes a download. It uses the
+    last modified time to check for file content changes, and works with
+    many HTTP/1.0 servers as well, and usually falls back to a complete
+    re-download on older servers.
+
+    It calls the completion callback with either "undef", which means a
+    nonretryable error occured, 0 when the download was partial and should
+    be retried, and 1 if it was successful.
+
+       use AnyEvent::HTTP;
+
+       sub download($$$) {
+          my ($url, $file, $cb) = @_;
+
+          open my $fh, "+<", $file
+             or die "$file: $!";
+
+          my %hdr;
+          my $ofs = 0;
+
+          warn stat $fh;
+          warn -s _;
+          if (stat $fh and -s _) {
+             $ofs = -s _;
+             warn "-s is ", $ofs;#d#
+             $hdr{"if-unmodified-since"} = AnyEvent::HTTP::format_date +(stat _)[9];
+             $hdr{"range"} = "bytes=$ofs-";
+          }
+
+          http_get $url,
+             headers   => \%hdr,
+             on_header => sub {
+                my ($hdr) = @_;
+
+                if ($hdr->{Status} == 200 && $ofs) {
+                   # resume failed
+                   truncate $fh, $ofs = 0;
+                }
+
+                sysseek $fh, $ofs, 0;
+
+                1
+             },
+             on_body   => sub {
+                my ($data, $hdr) = @_;
+
+                if ($hdr->{Status} =~ /^2/) {
+                   length $data == syswrite $fh, $data
+                      or return; # abort on write errors
+                }
+
+                1
+             },
+             sub {
+                my (undef, $hdr) = @_;
+
+                my $status = $hdr->{Status};
+
+                if (my $time = AnyEvent::HTTP::parse_date $hdr->{"last-modified"}) {
+                   utime $fh, $time, $time;
+                }
+
+                if ($status == 200 || $status == 206 || $status == 416) {
+                   # download ok || resume ok || file already fully downloaded
+                   $cb->(1, $hdr);
+
+                } elsif ($status == 412) {
+                   # file has changed while resuming, delete and retry
+                   unlink $file;
+                   $cb->(0, $hdr);
+
+                } elsif ($status == 500 or $status == 503 or $status =~ /^59/) {
+                   # retry later
+                   $cb->(0, $hdr);
+
+                } else {
+                   $cb->(undef, $hdr);
+                }
+             }
+          ;
+       }
+
+       download "http://server/somelargefile", "/tmp/somelargefile", sub {
+          if ($_[0]) {
+             print "OK!\n";
+          } elsif (defined $_[0]) {
+             print "please retry later\n";
+          } else {
+             print "ERROR\n";
+          }
+       };
+
+   SOCKS PROXIES
     Socks proxies are not directly supported by AnyEvent::HTTP. You can
     compile your perl to support socks, or use an external program such as
     socksify (dante) or tsocks to make your program use a socks proxy