GHTTP(3) User Contributed Perl Documentation GHTTP(3)NAMEHTTP::GHTTP - Perl interface to the gnome ghttp library
SYNOPSIS
use HTTP::GHTTP;
my $r = HTTP::GHTTP->new();
$r->set_uri("http://axkit.org/");
$r->process_request;
print $r->get_body;
DESCRIPTION
This is a fairly low level interface to the Gnome project's libghttp,
which allows you to process HTTP requests to HTTP servers. There also
exists a slightly higher level interface - a simple get() function
which takes a URI as a parameter. This is not exported by default, you
have to ask for it explicitly.
API
HTTP::GHTTP->new([$uri, [%headers]])
Constructor function - creates a new GHTTP object. If supplied a URI it
will automatically call set_uri for you. If you also supply a list of
key/value pairs it will set those as headers:
my $r = HTTP::GHTTP->new(
"http://axkit.com/",
Connection => "close");
$r->set_uri($uri)
This sets the URI for the request
$r->set_header($header, $value)
This sets an outgoing HTTP request header
$r->set_type($type)
This sets the request type. The request types themselves are constants
that are not exported by default. To export them, specify the :methods
option in the import list:
use HTTP::GHTTP qw/:methods/;
my $r = HTTP::GHTTP->new();
$r->set_uri('http://axkit.com/');
$r->set_type(METHOD_HEAD);
...
The available methods are:
METHOD_GET
METHOD_POST
METHOD_OPTIONS
METHOD_HEAD
METHOD_PUT
METHOD_DELETE
METHOD_TRACE
METHOD_CONNECT
METHOD_PROPFIND
METHOD_PROPPATCH
METHOD_MKCOL
METHOD_COPY
METHOD_MOVE
METHOD_LOCK
METHOD_UNLOCK
Some of these are for DAV.
$r->set_body($body)
This sets the body of a request, useful in POST and some of the DAV
request types.
$r->process_request()
This sends the actual request to the server
$r->get_status()
This returns 2 values, a status code (numeric) and a status reason
phrase. A simple example of the return values would be (200, "OK").
$r->get_header($header)
This gets the value of an incoming HTTP response header
$r->get_headers()
Returns a list of all the response header names in the order they came
back. This method is only available in libghttp 1.08 and later - perl
Makefile.PL should have reported whether it found it or not.
my @headers = $r->get_headers;
print join("\n",
map { "$_: " . $r->get_header($_) } @headers), "\n\n";
$r->get_body()
This gets the body of the response
$r->get_error()
If the response failed for some reason, this returns a textual error
$r->set_authinfo($user, $password)
This sets an outgoing username and password for simple HTTP authentica-
tion
$r->set_proxy($proxy)
This sets your proxy server, use the form "http://proxy:port"
$r->set_proxy_authinfo($user, $password)
If you have set a proxy and your proxy requires a username and password
you can set it with this.
$r->prepare()
This is a low level interface useful only when doing async downloads.
See "ASYNC OPERATION".
$r->process()
This is a low level interface useful only when doing async downloads.
See "ASYNC OPERATION".
process returns undef for error, 1 for "in progress", and zero for
"complete".
$r->get_socket()
Returns an IO::Handle object that is the currently in progress socket.
Useful only when doing async downloads. There appears to be some cor-
ruption when using the socket to retrieve file contents on more recent
libghttp's.
$r->current_status()
This is only useful in async mode. It returns 3 values: The current
processing stage (0 = none, 1 = request, 2 = response headers, 3 =
response), the number of bytes read, and the number of bytes total.
$r->set_async()
This turns async mode on. There is no corresponding unset function.
$r->set_chunksize($bytes)
Sets the download (and upload) chunk size in bytes for use in async
mode. This may be a useful value to set for slow modems, or perhaps for
a download progress bar, or just to allow periodic writes.
get($uri, [%headers])
This does everything automatically for you, retrieving the body at the
remote URI. Optionally pass in headers.
ASYNC OPERATION
Its possible to use an asynchronous mode of operation with ghttp.
Here's a brief example of how:
my $r = HTTP::GHTTP->new("http://axkit.org/");
$r->set_async;
$r->set_chunksize(1);
$r->prepare;
my $status;
while ($status = $r->process) {
# do something
# you can do $r->get_body in here if you want to
# but it always returns the entire body.
}
die "An error occured" unless defined $status;
print $r->get_body;
Doing timeouts is an exercise for the reader (hint: lookup select() in
perlfunc).
Note also that $sock above is an IO::Handle, not an IO::Socket,
although you can probably get away with re-blessing it. Also note that
by calling $r->get_socket() you load IO::Handle, which probably brings
a lot of code with it, thereby obliterating a lot of the use for
libghttp. So use at your own risk :-)
AUTHOR
Matt Sergeant, matt@sergeant.org
LICENSE
This is free software, you may use it and distribute it under the same
terms as Perl itself. Please be aware though that libghttp is licensed
under the terms of the LGPL, a copy of which can be found in the
libghttp distribution.
BUGS
Probably many - this is my first adventure into XS.
libghttp doesn't support SSL. When libghttp does support SSL, so will
HTTP::GHTTP. The author of libghttp, Chris Blizzard <blizzard@red-
hat.com> is looking for patches to support SSL, so get coding!
BENCHMARKS
Benchmarking this sort of thing is often difficult, and I don't want to
offend anyone. But as well as being lightweight (HTTP::GHTTP is about 4
times less code than either LWP::UserAgent, or HTTP::Lite), it is also
in my tests significantly faster. Here are my benchmark results
requesting http://localhost/ (the Apache "Successful Install" page):
Benchmark: timing 1000 iterations of ghttp, lite, lwp...
ghttp: 8 wallclock secs ( 0.96 usr + 1.16 sys = 2.12 CPU)
lite: 21 wallclock secs ( 3.00 usr + 3.44 sys = 6.44 CPU)
lwp: 18 wallclock secs ( 9.76 usr + 1.59 sys = 11.35 CPU)
perl v5.8.8 2002-03-25 GHTTP(3)
