GT::WWW::http - HTTP interface for GT::WWW
use GT::WWW;
my $www = GT::WWW->new();
$www->protocol('http');
# any valid GT::WWW methods here
# ...
my $header = $www->header;
$header->header("Some-Http-Header" => $value);
$header->delete_header("Some-Other-Http-Header");
my $response = $www->get() or die "Could not connect to server: " . $www->error;
my $status = $response->status;
my $response_code = int $status; # For example, 200, 404, 500, etc.
my $response_str = "$status"; # For example, 'OK', 'Not Found', 'Internal Server Error', etc.
if ($status) {
# This will be true if the status code is a successful one - in other
# words, true for 2xx responses, false for others
print "Response successful. Content:\n$response\n";
}
else {
die "Request was not successful ($response_code $response_str)\n";
}
GT::WWW::http handles HTTP connections for GT::WWW. It uses some overloading to assist in the ease of use without sacrificing functionality.
This document does not cover the basics of a GT::WWW object; those are covered by the GT::WWW manpage.
This method returns the GT::WWW::http::Header object that will be (or has been) sent to the HTTP server. See the GT::WWW::http::Header manpage for information on using and manipulating a header object.
Note that you can add headers without first getting a header object by simply specifying the headers as arguments to header(). Normally, you would call:
$www->header->header('X-Foo' => 'bar');
This shortcut allows for:
$www->header('X-Foo' => 'bar');
Check the GT::WWW::http::Header manpage for valid arguments to the header() method.
This method can be used before initiating a request on the object to force HTTP/1.0 communication with the HTTP server. By default HTTP/1.1 connections are used. Note that HTTP/1.1 is strongly recommended as this module supports keep-alive connections only when using HTTP/1.1. To force HTTP/1.0 communication, pass a true value to this method, or a false value to use the default HTTP/1.1 connections. Returns true if HTTP/1.0 connections will be used.
This works as described in GT::WWW. Specifically, in addition to the loose query string restrictions, this allows relative URL Location: redirects (HTTP/1.1 specifically states that Location: redirects MUST be absolute).
This method is used before a request to indicate that automatic, seemless redirection should not take place. By default, when a server responds with an acceptable, properly-formed 3xx response allowing a redirection, this module will automatically perform the redirection, unless this option has been enabled. To enable, call this method with a true value, or to disable, a false value. Returns true if automatic redirection is enabled.
Note that redirections will only be performed on GET requests.
If redirections are enabled (i.e. the no_redirect option has not been turned
on), you can call the redirects() method to get a list of response objects
created while performing redirections. Typically this will be just one, but
more are possible.
Returns the response object for the last request. When automatic redirection is enabled, this will be the response object for the final request. The response object can be used is multiple ways, which are described below, in the RETURN VALUES section, and in the GT::WWW::http::Response manpage.
This works as described in cancel in the GT::WWW manpage, with one exception: if cancelling a request immediately before a redirect takes place, only the current request is cancelled - the redirect still occurs. Note that cancelling is likely to be a resource hit in such a case because the connection cannot be reused and a new one must be established - typically, to the same server.
The return values of the get(), head(),
and post() methods are simply the response object for the
request, which can also be obtained by calling the response()
method after completing the request.
The full documentation for the response object is covered in
the GT::WWW::http::Response manpage, however the below description is provided for a
brief overview. The following examples assume that ``$response'' is an object
that has been obtained by calling get(), head(), post(), or response().
The status of the request is available via the ->status method of the response object. It is made up of three pieces of data - status code, status string, and success.
To get the status code (e.g. 500, 200, etc.), simply use the status as a number:
my $status = int($response->status);
To get the status string (e.g. ``500 Internal Server Error'', ``200 OK''), use the status as a string:
my $status = "" . $response->status;
And finally, to get the success of the request, simply use status in boolean context:
if ($response->status) {
Success for HTTP is defined by any 200-level response status code. A request that returns ``200 OK'' will be pass the above if statement, while a request that returned ``500 Internal Server Error'' will fail.
The content of the last request is available by simply using the response object as a string:
my $content = "$response";
You should take note, however, that if you are using the
chunk() method no content will be available in this way.
Also note that the response object is an object, not a string, so anything beyond basic string comparison/concatenation should not occur on the response object itself. See CAVEATS in the GT::WWW::http::Response manpage for more details.
The header() method of the response object returns a GT::WWW::http::Header
object which gives you easy access to the headers returned by the server with
the request.
As a special shortcut, calling header() with arguments will call the
header() method of the header object with the
arguments provided. This allows you to optionally change this:
my $location = $response->header->header('Location');
into the shorter and clearer:
my $location = $response->header('Location');
Calling header() without arguments returns the header object for the response.
the GT::WWW manpage the GT::WWW::http::Response manpage the GT::WWW::http::Header manpage RFC 2616: http://www.ietf.org/rfc/rfc2616.txt
Jason Rhinelander
Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: http.pm,v 1.31 2005/04/08 19:20:00 jagerman Exp $