494 lines
14 KiB
HTML
494 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::WWW::http - HTTP interface for GT::WWW</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#methods">METHODS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#header">header</a></li>
|
|
<li><a href="#http_10">http_10</a></li>
|
|
<li><a href="#strict">strict</a></li>
|
|
<li><a href="#no_redirect">no_redirect</a></li>
|
|
<li><a href="#redirects">redirects</a></li>
|
|
<li><a href="#response">response</a></li>
|
|
<li><a href="#cancel">cancel</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#status">Status</a></li>
|
|
<li><a href="#content">Content</a></li>
|
|
<li><a href="#headers">Headers</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#maintainer">MAINTAINER</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::WWW::http - HTTP interface for GT::WWW</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
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");</pre>
|
|
<pre>
|
|
my $response = $www->get() or die "Could not connect to server: " . $www->error;</pre>
|
|
<pre>
|
|
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.</pre>
|
|
<pre>
|
|
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";
|
|
}</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::WWW::http handles HTTP connections for GT::WWW. It uses some overloading
|
|
to assist in the ease of use without sacrificing functionality.</p>
|
|
<p>This document does not cover the basics of a GT::WWW object; those are covered
|
|
by <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html">the GT::WWW manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods">METHODS</a></h1>
|
|
<p>
|
|
</p>
|
|
<h2><a name="header">header</a></h2>
|
|
<p>This method returns the GT::WWW::http::Header object that will be (or has been)
|
|
sent to the HTTP server. See <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html">the GT::WWW::http::Header manpage</a> for information on using
|
|
and manipulating a header object.</p>
|
|
<p>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:</p>
|
|
<pre>
|
|
$www->header->header('X-Foo' => 'bar');</pre>
|
|
<p>This shortcut allows for:</p>
|
|
<pre>
|
|
$www->header('X-Foo' => 'bar');</pre>
|
|
<p>Check <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html">the GT::WWW::http::Header manpage</a> for valid arguments to the <code>header()</code> method.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="http_10">http_10</a></h2>
|
|
<p>This method can be used <em>before</em> 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.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="strict">strict</a></h2>
|
|
<p>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).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="no_redirect">no_redirect</a></h2>
|
|
<p>This method is used before a request to indicate that automatic, seemless
|
|
redirection should <strong>not</strong> 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.</p>
|
|
<p>Note that redirections will only be performed on GET requests.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="redirects">redirects</a></h2>
|
|
<p>If redirections are enabled (i.e. the no_redirect option has not been turned
|
|
on), you can call the <code>redirects()</code> method to get a list of response objects
|
|
created while performing redirections. Typically this will be just one, but
|
|
more are possible.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="response">response</a></h2>
|
|
<p>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
|
|
<a href="#return_values">RETURN VALUES</a> section, and in <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Response.html">the GT::WWW::http::Response manpage</a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="cancel">cancel</a></h2>
|
|
<p>This works as described in <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#cancel">cancel in the GT::WWW manpage</a>, 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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>The return values of the <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#get"><code>get()</code></a>, <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#head"><code>head()</code></a>,
|
|
and <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#post"><code>post()</code></a> methods are simply the response object for the
|
|
request, which can also be obtained by calling the <a href="#response"><code>response()</code></a>
|
|
method after completing the request.</p>
|
|
<p>The full documentation for the response object is covered in
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Response.html">the GT::WWW::http::Response manpage</a>, however the below description is provided for a
|
|
brief overview. The following examples assume that ``<code>$response</code>'' is an object
|
|
that has been obtained by calling get(), head(), post(), or response().</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="status">Status</a></h2>
|
|
<p>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.</p>
|
|
<p>To get the status code (e.g. 500, 200, etc.), simply use the status as a number:</p>
|
|
<pre>
|
|
my $status = int($response->status);</pre>
|
|
<p>To get the status string (e.g. ``500 Internal Server Error'', ``200 OK''), use the
|
|
status as a string:</p>
|
|
<pre>
|
|
my $status = "" . $response->status;</pre>
|
|
<p>And finally, to get the success of the request, simply use status in boolean
|
|
context:</p>
|
|
<pre>
|
|
if ($response->status) {</pre>
|
|
<p>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.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="content">Content</a></h2>
|
|
<p>The content of the last request is available by simply using the response
|
|
object as a string:</p>
|
|
<pre>
|
|
my $content = "$response";</pre>
|
|
<p>You should take note, however, that if you are using the
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#chunk"><code>chunk()</code></a> method no content will be available in this way.</p>
|
|
<p>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 <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Response.html#caveats">CAVEATS in the GT::WWW::http::Response manpage</a> for more details.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="headers">Headers</a></h2>
|
|
<p>The <code>header()</code> 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.</p>
|
|
<p>As a special shortcut, calling <code>header()</code> with arguments will call the
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html#header">header()</a> method of the header object with the
|
|
arguments provided. This allows you to optionally change this:</p>
|
|
<pre>
|
|
my $location = $response->header->header('Location');</pre>
|
|
<p>into the shorter and clearer:</p>
|
|
<pre>
|
|
my $location = $response->header('Location');</pre>
|
|
<p>Calling <code>header()</code> without arguments returns the header object for the response.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html">the GT::WWW manpage</a>
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Response.html">the GT::WWW::http::Response manpage</a>
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html">the GT::WWW::http::Header manpage</a>
|
|
RFC 2616: <a href="http://www.ietf.org/rfc/rfc2616.txt">http://www.ietf.org/rfc/rfc2616.txt</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="maintainer">MAINTAINER</a></h1>
|
|
<p>Jason Rhinelander</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>Revision: $Id: http.pm,v 1.31 2005/04/08 19:20:00 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|