This module allows you to read from and write to HTTP resources as if they were normal file handles (in fact, any non-HTTP resources supported by LWP::UserAgent ought to be OK too, including FTP, Gopher, etc).

Why would you do this? Not for efficiency reasons, that's for sure. However, certain APIs expect to be passed filehandles; this module gives you those filehandles.

Files can be opened in either read mode, using:

my $fh = IO::Callback::HTTP->new('<', $request, %options);

or write mode:

my $fh = IO::Callback::HTTP->new('>', $request, %options);

The $fh variable will then act like a normal Perl filehandle, but instead of interacting with a local file on disk, you'll be interacting with an HTTP resource on a remote server.

$request can be a URI (either a string, or a blessed URI object), or it can be an HTTP::Request object. A URI is obviously simpler, but using an HTTP::Request object offers you more flexibility, such as the ability to change the HTTP method (defaults to GET for filehandles opened in read mode, and PUT for filehandles opened in write mode) or include particular HTTP headers (some of which are very useful: Accept, Content-Type, User-Agent, etc).

Note that for a single filehandle, only one HTTP request is actually made. In the case of read mode, this happens on the first read. If no characters are read from the handle, then no request is made. In the case of write mode, the request happens once the file is closed.

In read mode, if true, will make sure the data read from the handle is returned encoded as a UTF-8 byte string. If false, then the data read will be returned as a utf8 character string.

In write mode, if true, will assume that you're writing bytes to the filehandle. If false, will assume that you're writing utf8 character strings to the filehandle, so will deal with encoding them to UTF-8 octets.

Set this to a coderef to trigger when the HTTP request succeeds (i.e. 2XX HTTP response code). It is passed a single parameter, which is the HTTP::Response object.

For filehandles in read mode, this is probably not especially useful, the fact that you can read from the file handle at all indicates that the request was successful. In write mode, it's more interesting as you may be interested in the result of a POST or PUT request.

Most of the test suite is skipped on MSWin32 because Test::HTTP::Server does not currently support that platform. IO::Callback::HTTP is believed to function correctly on Windows, but it's had no meaningful testing.