724 lines
25 KiB
HTML
724 lines
25 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 - Multi-protocol retrieving and posting, related in functionality to
|
|
LWP.</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="#description">DESCRIPTION</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#methods">METHODS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#new">new</a></li>
|
|
<li><a href="#head">head</a></li>
|
|
<li><a href="#get">get</a></li>
|
|
<li><a href="#post">post</a></li>
|
|
<li><a href="#url">url</a></li>
|
|
<li><a href="#parse_url">parse_url</a></li>
|
|
<li><a href="#protocol">protocol</a></li>
|
|
<li><a href="#protocol_supported">protocol_supported</a></li>
|
|
<li><a href="#valid_host">valid_host</a></li>
|
|
<li><a href="#host">host</a></li>
|
|
<li><a href="#port">port</a></li>
|
|
<li><a href="#reset_port">reset_port</a></li>
|
|
<li><a href="#username">username</a></li>
|
|
<li><a href="#reset_username">reset_username</a></li>
|
|
<li><a href="#password">password</a></li>
|
|
<li><a href="#reset_password">reset_password</a></li>
|
|
<li><a href="#connection_timeout">connection_timeout</a></li>
|
|
<li><a href="#path">path</a></li>
|
|
<li><a href="#parameters">parameters</a></li>
|
|
<li><a href="#reset_parameters">reset_parameters</a></li>
|
|
<li><a href="#query_string">query_string</a></li>
|
|
<li><a href="#strict">strict</a></li>
|
|
<li><a href="#post_data">post_data</a></li>
|
|
<li><a href="#agent">agent</a></li>
|
|
<li><a href="#default_agent">default_agent</a></li>
|
|
<li><a href="#chunk">chunk</a></li>
|
|
<li><a href="#chunk_size">chunk_size</a></li>
|
|
<li><a href="#cancel">cancel</a></li>
|
|
<li><a href="#cancelled">cancelled</a></li>
|
|
<li><a href="#debug_level">debug_level</a></li>
|
|
<li><a href="#error">error</a></li>
|
|
<li><a href="#fatal_errors">fatal_errors</a></li>
|
|
<li><a href="#file">file</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 - Multi-protocol retrieving and posting, related in functionality to
|
|
LWP.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::WWW is designed to provide a common interface for multiple protocols (as of
|
|
this writing, only HTTP and HTTPS, however others are planned) and handles
|
|
HEAD, GET, and POST requests. For non-HTTP-based protocols, what, exactly, a
|
|
``HEAD'', ``GET'', or ``POST'' request is depends on the module in question. For
|
|
example, with FTP ``GET'' might download a file, while ``POST'' might upload one to
|
|
the server, and ``HEAD'' might return just the size of the file.</p>
|
|
<p>The modules under GT::WWW <strong>should not</strong> be used directly; this module should be
|
|
used instead. The documentation here describes the options common to all
|
|
protocols - however you should check the POD of the protocol subclasses
|
|
(GT::WWW::http, GT::WWW::https, etc.) to see any extra options or methods that
|
|
those modules provide.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<p>Quick way:</p>
|
|
<pre>
|
|
use GT::WWW;
|
|
my $www = GT::WWW->get("<a href="http://server.com/page"">http://server.com/page"</a>;);
|
|
... = GT::WWW->post("<a href="http://server.com/page"">http://server.com/page"</a>;);
|
|
... = GT::WWW->head("<a href="http://server.com/page"">http://server.com/page"</a>;);
|
|
... = GT::WWW->...("<a href="http://user:pass@server.com/page"">http://user:pass@server.com/page"</a>;);
|
|
... = GT::WWW->...("https://server.com/page");</pre>
|
|
<pre>
|
|
# This query string will be parsed and passed as POST input:
|
|
... = GT::WWW->post("<a href="http://server.com/page?foo=bar;bar=foo"">http://server.com/page?foo=bar;bar=foo"</a>;);</pre>
|
|
<p>Longer, but more capable way:</p>
|
|
<pre>
|
|
use GT::WWW;
|
|
my $request = GT::WWW->new();</pre>
|
|
<pre>
|
|
$request->protocol("http");
|
|
$request->host("server.com");
|
|
$request->port(8080);
|
|
$request->path("/path/foo.cgi");
|
|
$request->username("user");
|
|
$request->password("pass");
|
|
$request->parameters(foo => "bar", bar => "foo");</pre>
|
|
<p>equivelant to the above, using ->url():</p>
|
|
<pre>
|
|
$request->url("<a href="http://user:pass@server.com:8080/path/foo.cgi?foo=bar;bar=foo"">http://user:pass@server.com:8080/path/foo.cgi?foo=bar;bar=foo"</a>;);</pre>
|
|
<p>Now call $request->get(), $request->post(), or $request->head().</p>
|
|
<p>Very quick way to print a page:</p>
|
|
<pre>
|
|
perl -MGT::WWW=get -e 'print get("<a href="http://server.com/page?foo=bar&bar=foo"">http://server.com/page?foo=bar&bar=foo"</a>;)'</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods">METHODS</a></h1>
|
|
<p>Note that all methods that set values (such as host(), port(), etc.) also
|
|
return the value when called without any argument.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="new">new</a></h2>
|
|
<p>Call <code>new()</code> to get a new GT::WWW object. You can call it without arguments to
|
|
get a generic GT::WWW object, or use arguments as described below.</p>
|
|
<dl>
|
|
<dt><strong><a name="item_url">URL</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
You can call new with a single scalar argument - a URL to be parsed. The URL is
|
|
of the same format as taken by the <code>url()</code> method.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_hash">HASH</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
You can alternatively call <code>new()</code> with a hash (or hash reference) of options.
|
|
Each of the methods described below can be passed in to new in the form of
|
|
<code>key => value</code> pairs - the methods will be called with the values
|
|
specified automatically.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="head">head</a></h2>
|
|
<p>
|
|
</p>
|
|
<h2><a name="get">get</a></h2>
|
|
<p>
|
|
</p>
|
|
<h2><a name="post">post</a></h2>
|
|
<p>These are the methods used to tell the module to actually connect to the server
|
|
and download the requested page.</p>
|
|
<p>When used as GT::WWW class methods or function calls (but <strong>NOT</strong> as methods on
|
|
GT::WWW objects or sub-objects), they take a single URL as an argument. This
|
|
call creates an internal GT::WWW object, turns on
|
|
<a href="#fatal_errors"><code>fatal_errors(1)</code></a>, passes the URL to <a href="#url"><code>url()</code></a>, then
|
|
calls the appropriate <code>get()</code>, <code>head()</code>, or <code>post()</code> method of the resulting
|
|
protocol-specific object.</p>
|
|
<p>Note, however, that once you have specified a protocol (either via
|
|
<a href="#protocol"><code>protocol()</code></a>, or as part of a url passed to <a href="#url"><code>url()</code></a>)
|
|
your object ceases to be a GT::WWW object and becomes a protocol-specific
|
|
GT::WWW subclass. All subclasses provide their own versions of these methods.</p>
|
|
<p>The subclassed methods are not described here because they may not be supported
|
|
for all protocols, and their return <code>value(s)</code> may differ from one protocol to
|
|
the next. For more details, see the modules listed in the
|
|
<a href="#see_also">SEE ALSO</a> section.</p>
|
|
<p>Generally, <code>get()</code> and <code>post()</code> return an overloaded object that can be used as a
|
|
string to get the content (i.e. for printing), but see the notes in the CAVEATS
|
|
section of <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Response.html">the GT::WWW::http::Response manpage</a> for anything more complicated than
|
|
concatenation or printing.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="url">url</a></h2>
|
|
<p>Takes a URL as argument. The URL is parsed into several fields: <code>protocol</code>,
|
|
<code>username</code>, <code>password</code>, <code>host</code>, <code>port</code>, <code>path</code>, and <code>query_string</code>, then
|
|
each of those properties are set for the current object. Also note that
|
|
calling <code>url()</code> on an existing object resets the host, port, username, password,
|
|
and all parameters.</p>
|
|
<p>Interally, this method calls <a href="#parse_url"><code>parse_url()</code></a>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parse_url">parse_url</a></h2>
|
|
<p>Takes a URI, and returns the following 7 element list:</p>
|
|
<pre>
|
|
# 0 1 2 3 4 5 6
|
|
($protocol, $username, $password, $host, $port, $path, $query_string) =
|
|
GT::WWW->parse_url($url);</pre>
|
|
<p>URL's require, at a minimum, protocol and host, in URI form:</p>
|
|
<pre>
|
|
PROTOCOL://HOST</pre>
|
|
<p>The URL can extend up to:</p>
|
|
<pre>
|
|
PROTOCOL://USERNAME:PASSWORD@HOST:PORT/PATH?QUERY_STRING</pre>
|
|
<p>Only protocols known to GT::WWW are acceptable. To check if a URL is valid,
|
|
check <code>$protocol</code>.</p>
|
|
<p>This method can be called as a class or object method, but not as a function.
|
|
If called as an object method, the strict option as currently set for the
|
|
object will be used; as a class method or function, an optional second
|
|
parameter can be passed in - if true, strict query string parsing mode will be
|
|
enabled.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="protocol">protocol</a></h2>
|
|
<p>Takes a protocol, such as 'http', 'https', 'ftp', etc. Note that when you call
|
|
protocol, you object ceases being a GT::WWW object, by becoming a GT::WWW subclass
|
|
(such as GT::WWW::http, GT::WWW::https, etc.). Before trying an unknown protocol,
|
|
you should generally call the <a href="#protocol_supported">protocol_supported</a> method - calling
|
|
<code>protocol(...)</code> with an unsupported protocol will result in a fatal error.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="protocol_supported">protocol_supported</a></h2>
|
|
<p>This method takes a protocol, such as 'http', 'https', 'ftp', etc. In order to
|
|
make sure the protocol is supported, this checks to see that it is an
|
|
internally supported protocol, and also tries to load the module to make sure
|
|
that the module can be loaded.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="valid_host">valid_host</a></h2>
|
|
<p>Returns true in scalar context if the host appears valid, or the host and port
|
|
in list context if the host is valid. Note that no check is performed to see
|
|
whether or not the host resolves or is reachable - this simply verifies that
|
|
the host is at least valid enough to warrant a lookup.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="host">host</a></h2>
|
|
<p>Sets the host, and optionally the port (assuming the argument is of the form:
|
|
'hostname:port'). Returns a fatal error if the host is not valid. Note that
|
|
setting the host will <strong>reset</strong> the port to the protocol's default value, so
|
|
this method <strong>must</strong> be called before port().</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="port">port</a></h2>
|
|
<p>Sets the port for the connection. This can be a name, such as ``smtp'', or a
|
|
numeric value. Note that the port value <strong>will be reset</strong> when the <code>host()</code>
|
|
method is called, so setting a port <strong>must</strong> happen after setting the host.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="reset_port">reset_port</a></h2>
|
|
<p>Resets the port so that the next request will use the default port.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="username">username</a></h2>
|
|
<p>Sets or retrieves the login username.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="reset_username">reset_username</a></h2>
|
|
<p>Removes the login username.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="password">password</a></h2>
|
|
<p>Sets the login password.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="reset_password">reset_password</a></h2>
|
|
<p>Removes the login password.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="connection_timeout">connection_timeout</a></h2>
|
|
<p>Specifies a timeout for connections, in seconds. By default, a value of 10 is
|
|
used. If you specify a false value here, the connection time out will be
|
|
system dependent; typically this is from one to several minutes. Note,
|
|
however, that the timeout is not supported on Windows systems and so should not
|
|
be depended on in code that runs on Windows systems.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="path">path</a></h2>
|
|
<p>Sets the path for the request. Any HTTP escapes (e.g. %20) are automatically
|
|
converted to the actual value (e.g. `` ''). If required, the path will be
|
|
automatically re-escaped before being sent to the server.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="parameters">parameters</a></h2>
|
|
<p>Takes a list (not a hash, since duplicate keys are permitted) of key => value
|
|
pairs. Optionally takes an extra argument - if true, the parameters are added,
|
|
not replaced - if omitted (or false), any existing parameters are deleted.</p>
|
|
<p>To specify a valueless parameter without a value, such as b in this example
|
|
query string:</p>
|
|
<pre>
|
|
a=1&b&c=3</pre>
|
|
<p>Pass undef as b's value. Passing ``'' as the value will result in:</p>
|
|
<pre>
|
|
a=1&b=&c=3</pre>
|
|
<p>For example, to set to two query strings above would require the following two
|
|
sets of arguments, respectively:</p>
|
|
<pre>
|
|
$www->parameters(a => 1, b => undef, c => 3);</pre>
|
|
<pre>
|
|
$www->parameters(a => 1, b => "", c => 3);</pre>
|
|
<p>To then add a ``d=4'' parameter to either one, you would call:</p>
|
|
<pre>
|
|
$www->parameters(d => 4, 1);</pre>
|
|
<p>Omitting the extra ``1'' would cause you to erase the previously set parameters.</p>
|
|
<p>Values specified should <strong>not</strong> be URL encoded.</p>
|
|
<p>If called without arguments, the list of key/value pairs is returned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="reset_parameters">reset_parameters</a></h2>
|
|
<p>Resets the parameters. You want to make sure you do this between each request
|
|
on the same object, unless using <a href="#url"><code>url()</code></a>, which calls this for you.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="query_string">query_string</a></h2>
|
|
<p>This function serves the same purpose as <a href="#parameters"><code>parameters()</code></a>, except
|
|
that it takes a query string as input instead of a list. Like <code>parameters()</code>,
|
|
the default behaviour is to replace any existing parameters unless a second,
|
|
true argument is provided.</p>
|
|
<p>Note that if you already have your parameters in some sort of list, it is
|
|
preferable to pass them to <code>parameters()</code> than to join them into a query
|
|
string and pass them into this function, because this function just splits them
|
|
back up into a list again.</p>
|
|
<p>You can also provide a query string (along with a host, path, and possibly
|
|
other data) using the <a href="#url"><code>url()</code></a> method.</p>
|
|
<p>If called without arguments, the current parameters will be joined into a valid
|
|
query string and returned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="strict">strict</a></h2>
|
|
<p>This function is used to tell the GT::WWW object to allow/disallow
|
|
standard-violating responses. This has a global effect of allowing query
|
|
strings to contain _any_ characters except for ``\r'', ``\n'', and ``#'' - normally,
|
|
characters such as /, ?, and various extended characters much be escaped into
|
|
%XX format. The <code>strict</code> option may have other protocol-specific effects,
|
|
which will be indicated in each protocol's documentation.</p>
|
|
<p>The option defaults to non-strict.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="post_data">post_data</a></h2>
|
|
<p>This function allows you to pass in raw data to be posted. The data will not be
|
|
encoded. If you pass in a code reference, the data will be posted in chunks.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="agent">agent</a></h2>
|
|
<p>Used to set or retrieve the User-Agent string that will be sent to the server.
|
|
If the agent string you pass starts or ends with whitespace or a comma, the
|
|
default agent will be added at the beginning of end of the User-Agent string,
|
|
respectively. This value is only meaningful to protocols supporting something
|
|
similar to the HTTP User-Agent.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="default_agent">default_agent</a></h2>
|
|
<p>Returns the default user agent string. This will be automatically used if no
|
|
agent has been set, or if an agent ending with whitespace is specified. This
|
|
value is dependent on the protocol being used, but is typically something like
|
|
``GT::WWW::http/1.23''. This method is read-only.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="chunk">chunk</a></h2>
|
|
<p>
|
|
</p>
|
|
<h2><a name="chunk_size">chunk_size</a></h2>
|
|
<p><code>chunk</code> and <code>chunk_size</code> are used to perform a large download in chunks. The
|
|
<code>chunk()</code> method takes a code reference that will be called when a chunk of
|
|
data has been retrieved from the server, or a value of <code>undef</code> to clear any
|
|
currently set chunk code. <code>chunk_size()</code> takes a integer containing the
|
|
number bytes that you wish to retrieve at a time from the server; the <code>chunk</code>
|
|
code reference will be called with a scalar reference containing up to
|
|
<code>chunk_size</code> bytes.</p>
|
|
<p>Note that when using chunked downloading, the data will not be available using
|
|
the normal content retrieval interface.</p>
|
|
<p>Also note that, as of 1.024, the chunk code reference only applies to the next
|
|
<code>get()</code> or <code>post()</code> request - after each <code>get()</code> or <code>post()</code> request, the chunk_code is
|
|
cleared (in order to avoid self-references and possible memory leaks).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="cancel">cancel</a></h2>
|
|
<p>
|
|
</p>
|
|
<h2><a name="cancelled">cancelled</a></h2>
|
|
<p>The <code>cancel</code> method can be used in conjunction with the <a href="#chunk"><code>chunk</code></a>
|
|
option to abort a download in progress. The chunk code will not be called
|
|
again, and the server connection will be closed. This should be used sparingly
|
|
and with care. <code>cancelled</code> simply return a true/false value indicating
|
|
whether the operation has been cancelled. This value is reset at the beginning
|
|
of each operation.</p>
|
|
<p>Note that cancelling an operation is never performed automatically, and only
|
|
happens - if ever - in the <code>chunk</code> code reference, so checking the
|
|
cancellation status is rarely needed.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="debug_level">debug_level</a></h2>
|
|
<p>This is used to set or retrieve the debug level.
|
|
0 = no debugging
|
|
1 = debugging related to current operation
|
|
2 = adds operation details to debugging level 1
|
|
3 = adds data debugging (very large!) to debugging level 2</p>
|
|
<p>When passed as part of a hash to new(), the key for this option can be specified
|
|
as <code>debug</code> instead of <code>debug_level</code>.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="error">error</a></h2>
|
|
<p>This method will return a string containing an error that has occured. Note
|
|
that an error may be generated even for methods that _seem_ to be correct - for
|
|
example, if a server unexpectedly closes the connection before properly
|
|
finishing the transfer, a successful return will result since the transfer was
|
|
partially successful, but an error message will still be set.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="fatal_errors">fatal_errors</a></h2>
|
|
<p>This method will alter the current object's error handling behaviour such that
|
|
any errors that occur will be propogated to fatal errors. It is enabled
|
|
automatically when using the quick (i.e. objectless) forms of <code>get()</code>,
|
|
<code>head()</code>, and <code>post()</code> methods which have no associated object on which
|
|
->error can be called.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="file">file</a></h2>
|
|
<p>This method is used to create a parameter for uploading a file. It takes
|
|
either one or two arguments:</p>
|
|
<p>2 argument form:
|
|
First argument is a <strong>remote</strong> filename, second argument is either a <strong>local</strong>
|
|
filename, or a GLOB reference to an open filehandle.</p>
|
|
<p>1 argument form:
|
|
Argument is a filename to read.</p>
|
|
<p>Example usage:</p>
|
|
<pre>
|
|
my $file = $www->file("foo.txt");
|
|
$www->parameters(foobar => $file, 1);
|
|
my $response = $www->post();</pre>
|
|
<p>This will upload the file from disk named ``foo.txt'', using a form parameter
|
|
named ``foobar''. This is similar to uploading a file named ``foo.txt'' via the
|
|
following HTML element:</p>
|
|
<pre>
|
|
<input type="file" name="foobar"></pre>
|
|
<p>The two argument form with two filenames is used to lie to the server about the
|
|
actual name of the file. Using a filehandle as the second argument is for use
|
|
when a filename is not available - such as an opened socket, or a file that has
|
|
been opened elsewhere in the code.</p>
|
|
<p>Examples:</p>
|
|
<pre>
|
|
my $file = $www->file("foo.txt", "bar.txt");
|
|
my $file2 = $www->file("foo2.txt", \*FH);
|
|
$www->parameters(foobar => $file, foobar2 => $file2, 1);
|
|
my $response = $www->post();</pre>
|
|
<p>This will upload two files - a file named <em>foo.txt</em> (which is actually read
|
|
from the <code>bar.txt</code> file) specified as form parameter <code>foobar</code>, and a second
|
|
file, specified as parameter <code>foobar2</code>, whose content is read from the
|
|
filehandle <code>FH</code>.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http.html">the GT::WWW::http manpage</a>
|
|
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/https.html">the GT::WWW::https manpage</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: WWW.pm,v 1.25 2005/04/08 19:25:31 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|