- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- header
- http_10
- strict
- no_redirect
- redirects
- response
- cancel

- RETURN VALUES

- Status
- Content
- Headers

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# NAME

GT::WWW::http - HTTP interface for GT::WWW

# SYNOPSIS

        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";
        }

# DESCRIPTION

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.

# METHODS

## header

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.

## http_10

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.

## strict

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).

## no_redirect

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.

## redirects

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.

## response

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.

## cancel

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.

# RETURN VALUES

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().

## Status

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.

## Content

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.

## Headers

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.

# SEE ALSO

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

# MAINTAINER

Jason Rhinelander

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: http.pm,v 1.31 2005/04/08 19:20:00 jagerman Exp $