NAME

HTTP::RangeSaver - handle partial content HTTP responses

SYNOPSIS

 use LWP;
 use HTTP::RangeSaver;

 open(my $fh,'+<','example.mpeg') || die $!;
 my $req=new HTTP::Request
    (GET => 'http://www.example.com/example.mpeg');
 $req->header(Range => 'bytes='.(-s $fh).'-');
 my $saver=new HTTP::RangeSaver($fh);
 my $ua=new LWP::UserAgent;
 my $resp=$ua->request($req,$saver->get_callback());

DESCRIPTION

HTTP::RangeSaver is a helper class for updating an existing file with data from a partial content HTTP response. It understands both of the partial content formats defined in RFC 2616 (a single Content-Range header or a multipart/byteranges Content-Type). For convenience, it also handles complete content HTTP responses (status 200 or 203 rather than 206).

CONSTRUCTOR

my $saver=HTTP::RangeSaver->new($fh,%options);

$fh is an open filehandle. It must allow seeking and writing.

%options is a list of key/value pairs for modifying the saver's behaviour.

truncate

Pass a true value to make the saver truncate the file to match the full length of the returned entity. Ignored if the server doesn't report a definite length.

require_length

Pass a true value to make the saver die if the server doesn't report a definite full length for the returned entity.

require_partial

Pass a true value to make the saver die if the server returns a complete entity rather than a partial one.

require_resource

Pass a true value to make the saver die if the server returns an entity that doesn't represent the requested resource (i.e. a 2xx status code other than 200, 203, or 206). This should never happen for a GET request.

delta

A adjustment to be applied to all file offsets in the destination file.

METHODS

my $callback=$saver->get_callback();

Returns a closure suitable for passing as the callback function argument to LWP::UserAgent's request methods.

$saver->process($data,$response,$protocol);

$saver->process(@_); # if called directly from the callback function

Call this method from your callback function if you want to do more than just save the incoming data (e.g. display a progress indicator).

$saver->get_length();

Returns the total length of the returned entity, or an undefined value if the length is indefinite (or hasn't arrived yet).

$saver->get_type();

Returns the MIME type of the returned entity, from either the Content-Type header of the response or the first part header of a multipart response. Returns undef if this information hasn't arrived yet.

$saver->get_written();

Returns the total number of bytes written by the saver (so far). Useful for displaying a simple progress indicator.

$saver->get_ranges();

Returns a reference to an array of ranges written by the saver (so far). Each range is represented by a reference to a two-element array containing the first and last byte numbers (ignoring the delta parameter) with the same semantics as in the HTTP protocol. Useful for displaying a complex progress indicator.

$saver->get_partheaders();

Returns a reference to an array of HTTP::Headers objects, one for each part (seen so far) of a multipart response.

$saver->is_incomplete();

Returns true if the saver hasn't seen a complete response yet.

AUTHOR

Bo Lindbergh <blgl@stacken.kth.se>

COPYRIGHT AND LICENSE

Copyright 2006 by Bo Lindbergh

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.