1759 lines
48 KiB
HTML
1759 lines
48 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LWP::UserAgent</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LWP::UserAgent</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-11-29<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
LWP::UserAgent - Web user agent class
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use strict;
|
|
use warnings;
|
|
|
|
use LWP::UserAgent ();
|
|
|
|
my $ua = LWP::UserAgent->new(timeout => 10);
|
|
$ua->env_proxy;
|
|
|
|
my $response = $ua->get('<A HREF="http://example.com');">http://example.com');</A>
|
|
|
|
if ($response->is_success) {
|
|
print $response->decoded_content;
|
|
}
|
|
else {
|
|
die $response->status_line;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Extra layers of security (note the <TT>"cookie_jar"</TT> and <TT>"protocols_allowed"</TT>):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use strict;
|
|
use warnings;
|
|
|
|
use HTTP::CookieJar::LWP ();
|
|
use LWP::UserAgent ();
|
|
|
|
my $jar = HTTP::CookieJar::LWP->new;
|
|
my $ua = LWP::UserAgent->new(
|
|
cookie_jar => $jar,
|
|
protocols_allowed => ['http', 'https'],
|
|
timeout => 10,
|
|
);
|
|
|
|
$ua->env_proxy;
|
|
|
|
my $response = $ua->get('<A HREF="http://example.com');">http://example.com');</A>
|
|
|
|
if ($response->is_success) {
|
|
print $response->decoded_content;
|
|
}
|
|
else {
|
|
die $response->status_line;
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The LWP::UserAgent is a class implementing a web user agent.
|
|
LWP::UserAgent objects can be used to dispatch web requests.
|
|
<P>
|
|
|
|
In normal use the application creates an LWP::UserAgent object, and
|
|
then configures it with values for timeouts, proxies, name, etc. It
|
|
then creates an instance of HTTP::Request for the request that
|
|
needs to be performed. This request is then passed to one of the
|
|
request method the UserAgent, which dispatches it using the relevant
|
|
protocol, and returns a HTTP::Response object. There are
|
|
convenience methods for sending the most common request types:
|
|
``get'' in LWP::UserAgent, ``head'' in LWP::UserAgent, ``post'' in LWP::UserAgent,
|
|
``put'' in LWP::UserAgent and ``delete'' in LWP::UserAgent. When using these
|
|
methods, the creation of the request object is hidden as shown in the
|
|
synopsis above.
|
|
<P>
|
|
|
|
The basic approach of the library is to use HTTP-style communication
|
|
for all protocol schemes. This means that you will construct
|
|
HTTP::Request objects and receive HTTP::Response objects even
|
|
for non-HTTP resources like <I>gopher</I> and <I>ftp</I>. In order to achieve
|
|
even more similarity to HTTP-style communications, <I>gopher</I> menus and
|
|
file directories are converted to <FONT SIZE="-1">HTML</FONT> documents.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>CONSTRUCTOR METHODS</H2>
|
|
|
|
|
|
|
|
The following constructor methods are available:
|
|
<A NAME="lbAF"> </A>
|
|
<H3>clone</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $ua2 = $ua->clone;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Returns a copy of the LWP::UserAgent object.
|
|
<P>
|
|
|
|
<B></B><FONT SIZE="-1"><B>CAVEAT</B></FONT><B></B>: Please be aware that the clone method does not copy or clone your
|
|
<TT>"cookie_jar"</TT> attribute. Due to the limited restrictions on what can be used
|
|
for your cookie jar, there is no way to clone the attribute. The <TT>"cookie_jar"</TT>
|
|
attribute will be <TT>"undef"</TT> in the new object instance.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>new</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $ua = LWP::UserAgent->new( %options )
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method constructs a new LWP::UserAgent object and returns it.
|
|
Key/value pair arguments may be provided to set up the initial state.
|
|
The following options correspond to attribute methods described below:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
KEY DEFAULT
|
|
----------- --------------------
|
|
agent "libwww-perl/#.###"
|
|
from undef
|
|
conn_cache undef
|
|
cookie_jar undef
|
|
default_headers HTTP::Headers->new
|
|
local_address undef
|
|
ssl_opts { verify_hostname => 1 }
|
|
max_size undef
|
|
max_redirect 7
|
|
parse_head 1
|
|
protocols_allowed undef
|
|
protocols_forbidden undef
|
|
requests_redirectable ['GET', 'HEAD']
|
|
timeout 180
|
|
proxy undef
|
|
no_proxy []
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The following additional options are also accepted: If the <TT>"env_proxy"</TT> option
|
|
is passed in with a true value, then proxy settings are read from environment
|
|
variables (see ``env_proxy'' in LWP::UserAgent). If <TT>"env_proxy"</TT> isn't provided, the
|
|
<TT>"PERL_LWP_ENV_PROXY"</TT> environment variable controls if
|
|
``env_proxy'' in LWP::UserAgent is called during initialization. If the
|
|
<TT>"keep_alive"</TT> option value is defined and non-zero, then an <TT>"LWP::ConnCache"</TT> is set up (see
|
|
``conn_cache'' in LWP::UserAgent). The <TT>"keep_alive"</TT> value is passed on as the
|
|
<TT>"total_capacity"</TT> for the connection cache.
|
|
<P>
|
|
|
|
<TT>"proxy"</TT> must be set as an arrayref of key/value pairs. <TT>"no_proxy"</TT> takes an
|
|
arrayref of domains.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
|
|
|
|
The settings of the configuration attributes modify the behaviour of the
|
|
LWP::UserAgent when it dispatches requests. Most of these can also
|
|
be initialized by options passed to the constructor method.
|
|
<P>
|
|
|
|
The following attribute methods are provided. The attribute value is
|
|
left unchanged if no argument is given. The return value from each
|
|
method is the old attribute value.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>agent</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $agent = $ua->agent;
|
|
$ua->agent('Checkbot/0.4 '); # append the default to the end
|
|
$ua->agent('Mozilla/5.0');
|
|
$ua->agent(""); # don't identify
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the product token that is used to identify the user agent on
|
|
the network. The agent value is sent as the <TT>"User-Agent"</TT> header in
|
|
the requests.
|
|
<P>
|
|
|
|
The default is a string of the form <TT>"libwww-perl/#.###"</TT>, where <TT>"#.###"</TT> is
|
|
substituted with the version number of this library.
|
|
<P>
|
|
|
|
If the provided string ends with space, the default <TT>"libwww-perl/#.###"</TT>
|
|
string is appended to it.
|
|
<P>
|
|
|
|
The user agent string should be one or more simple product identifiers
|
|
with an optional version number separated by the <TT>"/"</TT> character.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>conn_cache</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $cache_obj = $ua->conn_cache;
|
|
$ua->conn_cache( $cache_obj );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the LWP::ConnCache object to use. See LWP::ConnCache
|
|
for details.
|
|
<A NAME="lbAK"> </A>
|
|
<H3>cookie_jar</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $jar = $ua->cookie_jar;
|
|
$ua->cookie_jar( $cookie_jar_obj );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the cookie jar object to use. The only requirement is that
|
|
the cookie jar object must implement the <TT>"extract_cookies($response)"</TT> and
|
|
<TT>"add_cookie_header($request)"</TT> methods. These methods will then be
|
|
invoked by the user agent as requests are sent and responses are
|
|
received. Normally this will be a HTTP::Cookies object or some
|
|
subclass. You are, however, encouraged to use HTTP::CookieJar::LWP
|
|
instead. See ``<FONT SIZE="-1">BEST PRACTICES''</FONT> for more information.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use HTTP::CookieJar::LWP ();
|
|
|
|
my $jar = HTTP::CookieJar::LWP->new;
|
|
my $ua = LWP::UserAgent->new( cookie_jar => $jar );
|
|
|
|
# or after object creation
|
|
$ua->cookie_jar( $cookie_jar );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The default is to have no cookie jar, i.e. never automatically add
|
|
<TT>"Cookie"</TT> headers to the requests.
|
|
<P>
|
|
|
|
Shortcut: If a reference to a plain hash is passed in, it is replaced with an
|
|
instance of HTTP::Cookies that is initialized based on the hash. This form
|
|
also automatically loads the HTTP::Cookies module. It means that:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->cookie_jar({ file => "$ENV{HOME}/.cookies.txt" });
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
is really just a shortcut for:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
require HTTP::Cookies;
|
|
$ua->cookie_jar(HTTP::Cookies->new(file => "$ENV{HOME}/.cookies.txt"));
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>credentials</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $creds = $ua->credentials();
|
|
$ua->credentials( $netloc, $realm );
|
|
$ua->credentials( $netloc, $realm, $uname, $pass );
|
|
$ua->credentials("<A HREF="http://www.example.com">www.example.com</A>:80", "Some Realm", "foo", "secret");
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the user name and password to be used for a realm.
|
|
<P>
|
|
|
|
The <TT>$netloc</TT> is a string of the form <TT>"<host>:<port>"</TT>. The username and
|
|
password will only be passed to this server.
|
|
<A NAME="lbAM"> </A>
|
|
<H3>default_header</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->default_header( $field );
|
|
$ua->default_header( $field => $value );
|
|
$ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
|
|
$ua->default_header('Accept-Language' => "no, en");
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This is just a shortcut for
|
|
<TT>"$ua->default_headers->header( $field => $value )"</TT>.
|
|
<A NAME="lbAN"> </A>
|
|
<H3>default_headers</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $headers = $ua->default_headers;
|
|
$ua->default_headers( $headers_obj );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the headers object that will provide default header values for
|
|
any requests sent. By default this will be an empty HTTP::Headers
|
|
object.
|
|
<A NAME="lbAO"> </A>
|
|
<H3>from</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $from = $ua->from;
|
|
$ua->from('<A HREF="mailto:foo@bar.com">foo@bar.com</A>');
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the email address for the human user who controls
|
|
the requesting user agent. The address should be machine-usable, as
|
|
defined in <FONT SIZE="-1">RFC2822</FONT> <<A HREF="https://tools.ietf.org/html/rfc2822">https://tools.ietf.org/html/rfc2822</A>>. The <TT>"from"</TT> value
|
|
is sent as the <TT>"From"</TT> header in the requests.
|
|
<P>
|
|
|
|
The default is to not send a <TT>"From"</TT> header. See
|
|
``default_headers'' in LWP::UserAgent for the more general interface that allow
|
|
any header to be defaulted.
|
|
<A NAME="lbAP"> </A>
|
|
<H3>local_address</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $address = $ua->local_address;
|
|
$ua->local_address( $address );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the local interface to bind to for network connections. The interface
|
|
can be specified as a hostname or an <FONT SIZE="-1">IP</FONT> address. This value is passed as the
|
|
<TT>"LocalAddr"</TT> argument to IO::Socket::INET.
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>max_redirect</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $max = $ua->max_redirect;
|
|
$ua->max_redirect( $n );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This reads or sets the object's limit of how many times it will obey
|
|
redirection responses in a given request cycle.
|
|
<P>
|
|
|
|
By default, the value is <TT>7</TT>. This means that if you call ``request'' in LWP::UserAgent
|
|
and the response is a redirect elsewhere which is in turn a
|
|
redirect, and so on seven times, then <FONT SIZE="-1">LWP</FONT> gives up after that seventh
|
|
request.
|
|
<A NAME="lbAR"> </A>
|
|
<H3>max_size</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $size = $ua->max_size;
|
|
$ua->max_size( $bytes );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the size limit for response content. The default is <TT>"undef"</TT>,
|
|
which means that there is no limit. If the returned response content
|
|
is only partial, because the size limit was exceeded, then a
|
|
<TT>"Client-Aborted"</TT> header will be added to the response. The content
|
|
might end up longer than <TT>"max_size"</TT> as we abort once appending a
|
|
chunk of data makes the length exceed the limit. The <TT>"Content-Length"</TT>
|
|
header, if present, will indicate the length of the full content and
|
|
will normally not be the same as <TT>"length($res->content)"</TT>.
|
|
<A NAME="lbAS"> </A>
|
|
<H3>parse_head</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $bool = $ua->parse_head;
|
|
$ua->parse_head( $boolean );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set a value indicating whether we should initialize response
|
|
headers from the <head> section of <FONT SIZE="-1">HTML</FONT> documents. The default is
|
|
true. <I>Do not turn this off</I> unless you know what you are doing.
|
|
<A NAME="lbAT"> </A>
|
|
<H3>protocols_allowed</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $aref = $ua->protocols_allowed; # get allowed protocols
|
|
$ua->protocols_allowed( \@protocols ); # allow ONLY these
|
|
$ua->protocols_allowed(undef); # delete the list
|
|
$ua->protocols_allowed(['http',]); # ONLY allow http
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
By default, an object has neither a <TT>"protocols_allowed"</TT> list, nor a
|
|
``protocols_forbidden'' in LWP::UserAgent list.
|
|
<P>
|
|
|
|
This reads (or sets) this user agent's list of protocols that the
|
|
request methods will exclusively allow. The protocol names are case
|
|
insensitive.
|
|
<P>
|
|
|
|
For example: <TT>"$ua->protocols_allowed( [ 'http', 'https'] );"</TT>
|
|
means that this user agent will <I>allow only</I> those protocols,
|
|
and attempts to use this user agent to access URLs with any other
|
|
schemes (like <TT>"<A HREF="ftp://...">ftp://...</A>"</TT>) will result in a 500 error.
|
|
<P>
|
|
|
|
Note that having a <TT>"protocols_allowed"</TT> list causes any
|
|
``protocols_forbidden'' in LWP::UserAgent list to be ignored.
|
|
<A NAME="lbAU"> </A>
|
|
<H3>protocols_forbidden</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $aref = $ua->protocols_forbidden; # get the forbidden list
|
|
$ua->protocols_forbidden(\@protocols); # do not allow these
|
|
$ua->protocols_forbidden(['http',]); # All http reqs get a 500
|
|
$ua->protocols_forbidden(undef); # delete the list
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This reads (or sets) this user agent's list of protocols that the
|
|
request method will <I>not</I> allow. The protocol names are case
|
|
insensitive.
|
|
<P>
|
|
|
|
For example: <TT>"$ua->protocols_forbidden( [ 'file', 'mailto'] );"</TT>
|
|
means that this user agent will <I>not</I> allow those protocols, and
|
|
attempts to use this user agent to access URLs with those schemes
|
|
will result in a 500 error.
|
|
<A NAME="lbAV"> </A>
|
|
<H3>requests_redirectable</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $aref = $ua->requests_redirectable;
|
|
$ua->requests_redirectable( \@requests );
|
|
$ua->requests_redirectable(['GET', 'HEAD',]); # the default
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This reads or sets the object's list of request names that
|
|
``redirect_ok'' in LWP::UserAgent will allow redirection for. By default, this
|
|
is <TT>"['GET', 'HEAD']"</TT>, as per <FONT SIZE="-1">RFC 2616</FONT> <<A HREF="https://tools.ietf.org/html/rfc2616">https://tools.ietf.org/html/rfc2616</A>>.
|
|
To change to include <TT>"POST"</TT>, consider:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
push @{ $ua->requests_redirectable }, 'POST';
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAW"> </A>
|
|
<H3>send_te</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $bool = $ua->send_te;
|
|
$ua->send_te( $boolean );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
If true, will send a <TT>"TE"</TT> header along with the request. The default is
|
|
true. Set it to false to disable the <TT>"TE"</TT> header for systems who can't
|
|
handle it.
|
|
<A NAME="lbAX"> </A>
|
|
<H3>show_progress</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $bool = $ua->show_progress;
|
|
$ua->show_progress( $boolean );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set a value indicating whether a progress bar should be displayed
|
|
on the terminal as requests are processed. The default is false.
|
|
<A NAME="lbAY"> </A>
|
|
<H3>ssl_opts</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my @keys = $ua->ssl_opts;
|
|
my $val = $ua->ssl_opts( $key );
|
|
$ua->ssl_opts( $key => $value );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the options for <FONT SIZE="-1">SSL</FONT> connections. Without argument return the list
|
|
of options keys currently set. With a single argument return the current
|
|
value for the given option. With 2 arguments set the option value and return
|
|
the old. Setting an option to the value <TT>"undef"</TT> removes this option.
|
|
<P>
|
|
|
|
The options that <FONT SIZE="-1">LWP</FONT> relates to are:
|
|
<DL COMPACT>
|
|
<DT id="1">"verify_hostname" => $bool<DD>
|
|
|
|
|
|
|
|
|
|
When <FONT SIZE="-1">TRUE LWP</FONT> will for secure protocol schemes ensure it connects to servers
|
|
that have a valid certificate matching the expected hostname. If <FONT SIZE="-1">FALSE</FONT> no
|
|
checks are made and you can't be sure that you communicate with the expected peer.
|
|
The no checks behaviour was the default for libwww-perl-5.837 and earlier releases.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is initialized from the <TT>"PERL_LWP_SSL_VERIFY_HOSTNAME"</TT> environment
|
|
variable. If this environment variable isn't set; then <TT>"verify_hostname"</TT>
|
|
defaults to 1.
|
|
<DT id="2">"SSL_ca_file" => $path<DD>
|
|
|
|
|
|
|
|
|
|
The path to a file containing Certificate Authority certificates.
|
|
A default setting for this option is provided by checking the environment
|
|
variables <TT>"PERL_LWP_SSL_CA_FILE"</TT> and <TT>"HTTPS_CA_FILE"</TT> in order.
|
|
<DT id="3">"SSL_ca_path" => $path<DD>
|
|
|
|
|
|
|
|
|
|
The path to a directory containing files containing Certificate Authority
|
|
certificates.
|
|
A default setting for this option is provided by checking the environment
|
|
variables <TT>"PERL_LWP_SSL_CA_PATH"</TT> and <TT>"HTTPS_CA_DIR"</TT> in order.
|
|
</DL>
|
|
<P>
|
|
|
|
Other options can be set and are processed directly by the <FONT SIZE="-1">SSL</FONT> Socket implementation
|
|
in use. See IO::Socket::SSL or Net::SSL for details.
|
|
<P>
|
|
|
|
The libwww-perl core no longer bundles protocol plugins for <FONT SIZE="-1">SSL.</FONT> You will need
|
|
to install LWP::Protocol::https separately to enable support for processing
|
|
https-URLs.
|
|
<A NAME="lbAZ"> </A>
|
|
<H3>timeout</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $secs = $ua->timeout;
|
|
$ua->timeout( $secs );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Get/set the timeout value in seconds. The default value is
|
|
180 seconds, i.e. 3 minutes.
|
|
<P>
|
|
|
|
The request is aborted if no activity on the connection to the server
|
|
is observed for <TT>"timeout"</TT> seconds. This means that the time it takes
|
|
for the complete transaction and the ``request'' in LWP::UserAgent method to
|
|
actually return might be longer.
|
|
<P>
|
|
|
|
When a request times out, a response object is still returned. The response
|
|
will have a standard <FONT SIZE="-1">HTTP</FONT> Status Code (500). This response will have the
|
|
``Client-Warning'' header set to the value of ``Internal response''. See the
|
|
``get'' in LWP::UserAgent method description below for further details.
|
|
<A NAME="lbBA"> </A>
|
|
<H2>PROXY ATTRIBUTES</H2>
|
|
|
|
|
|
|
|
The following methods set up when requests should be passed via a
|
|
proxy server.
|
|
<A NAME="lbBB"> </A>
|
|
<H3>env_proxy</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->env_proxy;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Load proxy settings from <TT>*_proxy</TT> environment variables. You might
|
|
specify proxies like this (sh-syntax):
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
gopher_proxy=<A HREF="http://proxy.my.place/">http://proxy.my.place/</A>
|
|
wais_proxy=<A HREF="http://proxy.my.place/">http://proxy.my.place/</A>
|
|
no_proxy="localhost,example.com"
|
|
export gopher_proxy wais_proxy no_proxy
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
csh or tcsh users should use the <TT>"setenv"</TT> command to define these
|
|
environment variables.
|
|
<P>
|
|
|
|
On systems with case insensitive environment variables there exists a
|
|
name clash between the <FONT SIZE="-1">CGI</FONT> environment variables and the <TT>"HTTP_PROXY"</TT>
|
|
environment variable normally picked up by <TT>"env_proxy"</TT>. Because of
|
|
this <TT>"HTTP_PROXY"</TT> is not honored for <FONT SIZE="-1">CGI</FONT> scripts. The
|
|
<TT>"CGI_HTTP_PROXY"</TT> environment variable can be used instead.
|
|
<A NAME="lbBC"> </A>
|
|
<H3>no_proxy</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->no_proxy( @domains );
|
|
$ua->no_proxy('localhost', 'example.com');
|
|
$ua->no_proxy(); # clear the list
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Do not proxy requests to the given domains. Calling <TT>"no_proxy"</TT> without
|
|
any domains clears the list of domains.
|
|
<A NAME="lbBD"> </A>
|
|
<H3>proxy</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->proxy(\@schemes, $proxy_url)
|
|
$ua->proxy(['http', 'ftp'], '<A HREF="http://proxy.sn.no:8001/');">http://proxy.sn.no:8001/');</A>
|
|
|
|
# For a single scheme:
|
|
$ua->proxy($scheme, $proxy_url)
|
|
$ua->proxy('gopher', '<A HREF="http://proxy.sn.no:8001/');">http://proxy.sn.no:8001/');</A>
|
|
|
|
# To set multiple proxies at once:
|
|
$ua->proxy([
|
|
ftp => '<A HREF="http://ftp.example.com:8001/',">http://ftp.example.com:8001/',</A>
|
|
[ 'http', 'https' ] => '<A HREF="http://http.example.com:8001/',">http://http.example.com:8001/',</A>
|
|
]);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Set/retrieve proxy <FONT SIZE="-1">URL</FONT> for a scheme.
|
|
<P>
|
|
|
|
The first form specifies that the <FONT SIZE="-1">URL</FONT> is to be used as a proxy for
|
|
access methods listed in the list in the first method argument,
|
|
i.e. <TT>"http"</TT> and <TT>"ftp"</TT>.
|
|
<P>
|
|
|
|
The second form shows a shorthand form for specifying
|
|
proxy <FONT SIZE="-1">URL</FONT> for a single access scheme.
|
|
<P>
|
|
|
|
The third form demonstrates setting multiple proxies at once. This is also
|
|
the only form accepted by the constructor.
|
|
<A NAME="lbBE"> </A>
|
|
<H2>HANDLERS</H2>
|
|
|
|
|
|
|
|
Handlers are code that injected at various phases during the
|
|
processing of requests. The following methods are provided to manage
|
|
the active handlers:
|
|
<A NAME="lbBF"> </A>
|
|
<H3>add_handler</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->add_handler( $phase => \&cb, %matchspec )
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Add handler to be invoked in the given processing phase. For how to
|
|
specify <TT>%matchspec</TT> see ``Matching'' in HTTP::Config.
|
|
<P>
|
|
|
|
The possible values <TT>$phase</TT> and the corresponding callback signatures are as
|
|
follows. Note that the handlers are documented in the order in which they will
|
|
be run, which is:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
request_preprepare
|
|
request_prepare
|
|
request_send
|
|
response_header
|
|
response_data
|
|
response_done
|
|
response_redirect
|
|
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="4">request_preprepare => sub { my($request, $ua, $handler) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
The handler is called before the <TT>"request_prepare"</TT> and other standard
|
|
initialization of the request. This can be used to set up headers
|
|
and attributes that the <TT>"request_prepare"</TT> handler depends on. Proxy
|
|
initialization should take place here; but in general don't register
|
|
handlers for this phase.
|
|
<DT id="5">request_prepare => sub { my($request, $ua, $handler) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
The handler is called before the request is sent and can modify the
|
|
request any way it see fit. This can for instance be used to add
|
|
certain headers to specific requests.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The method can assign a new request object to <TT>$_[0]</TT> to replace the
|
|
request that is sent fully.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The return value from the callback is ignored. If an exception is
|
|
raised it will abort the request and make the request method return a
|
|
``400 Bad request'' response.
|
|
<DT id="6">request_send => sub { my($request, $ua, $handler) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
This handler gets a chance of handling requests before they're sent to the
|
|
protocol handlers. It should return an HTTP::Response object if it
|
|
wishes to terminate the processing; otherwise it should return nothing.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"response_header"</TT> and <TT>"response_data"</TT> handlers will not be
|
|
invoked for this response, but the <TT>"response_done"</TT> will be.
|
|
<DT id="7">response_header => sub { my($response, $ua, $handler) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
This handler is called right after the response headers have been
|
|
received, but before any content data. The handler might set up
|
|
handlers for data and might croak to abort the request.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The handler might set the <TT>"$response->{default_add_content}"</TT> value to
|
|
control if any received data should be added to the response object
|
|
directly. This will initially be false if the <TT>"$ua->request()"</TT> method
|
|
was called with a <TT>$content_file</TT> or <TT>"$content_cb argument"</TT>; otherwise true.
|
|
<DT id="8">response_data => sub { my($response, $ua, $handler, $data) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
This handler is called for each chunk of data received for the
|
|
response. The handler might croak to abort the request.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This handler needs to return a <FONT SIZE="-1">TRUE</FONT> value to be called again for
|
|
subsequent chunks for the same request.
|
|
<DT id="9">response_done => sub { my($response, $ua, $handler) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
The handler is called after the response has been fully received, but
|
|
before any redirect handling is attempted. The handler can be used to
|
|
extract information or modify the response.
|
|
<DT id="10">response_redirect => sub { my($response, $ua, $handler) = @_; ... }<DD>
|
|
|
|
|
|
|
|
|
|
The handler is called in <TT>"$ua->request"</TT> after <TT>"response_done"</TT>. If the
|
|
handler returns an HTTP::Request object we'll start over with processing
|
|
this request instead.
|
|
</DL>
|
|
<P>
|
|
|
|
For all of these, <TT>$handler</TT> is a code reference to the handler that
|
|
is currently being run.
|
|
<A NAME="lbBG"> </A>
|
|
<H3>get_my_handler</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->get_my_handler( $phase, %matchspec );
|
|
$ua->get_my_handler( $phase, %matchspec, $init );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Will retrieve the matching handler as hash ref.
|
|
<P>
|
|
|
|
If <TT>$init</TT> is passed as a true value, create and add the
|
|
handler if it's not found. If <TT>$init</TT> is a subroutine reference, then
|
|
it's called with the created handler hash as argument. This sub might
|
|
populate the hash with extra fields; especially the callback. If
|
|
<TT>$init</TT> is a hash reference, merge the hashes.
|
|
<A NAME="lbBH"> </A>
|
|
<H3>handlers</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->handlers( $phase, $request )
|
|
$ua->handlers( $phase, $response )
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Returns the handlers that apply to the given request or response at
|
|
the given processing phase.
|
|
<A NAME="lbBI"> </A>
|
|
<H3>remove_handler</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->remove_handler( undef, %matchspec );
|
|
$ua->remove_handler( $phase, %matchspec );
|
|
$ua->remove_handler(); # REMOVE ALL HANDLERS IN ALL PHASES
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Remove handlers that match the given <TT>%matchspec</TT>. If <TT>$phase</TT> is not
|
|
provided, remove handlers from all phases.
|
|
<P>
|
|
|
|
Be careful as calling this function with <TT>%matchspec</TT> that is not
|
|
specific enough can remove handlers not owned by you. It's probably
|
|
better to use the ``set_my_handler'' in LWP::UserAgent method instead.
|
|
<P>
|
|
|
|
The removed handlers are returned.
|
|
<A NAME="lbBJ"> </A>
|
|
<H3>set_my_handler</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua->set_my_handler( $phase, $cb, %matchspec );
|
|
$ua->set_my_handler($phase, undef); # remove handler for phase
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Set handlers private to the executing subroutine. Works by defaulting
|
|
an <TT>"owner"</TT> field to the <TT>%matchspec</TT> that holds the name of the called
|
|
subroutine. You might pass an explicit <TT>"owner"</TT> to override this.
|
|
<P>
|
|
|
|
If <TT>$cb</TT> is passed as <TT>"undef"</TT>, remove the handler.
|
|
<A NAME="lbBK"> </A>
|
|
<H2>REQUEST METHODS</H2>
|
|
|
|
|
|
|
|
The methods described in this section are used to dispatch requests
|
|
via the user agent. The following request methods are provided:
|
|
<A NAME="lbBL"> </A>
|
|
<H3>delete</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $ua->delete( $url );
|
|
my $res = $ua->delete( $url, $field_name => $value, ... );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch a <TT>"DELETE"</TT> request on the given <FONT SIZE="-1">URL.</FONT> Additional
|
|
headers and content options are the same as for the ``get'' in LWP::UserAgent
|
|
method.
|
|
<P>
|
|
|
|
This method will use the <FONT SIZE="-1"><B>DELETE</B></FONT><B>()</B> function from HTTP::Request::Common
|
|
to build the request. See HTTP::Request::Common for a details on
|
|
how to pass form content and other advanced features.
|
|
<A NAME="lbBM"> </A>
|
|
<H3>get</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $ua->get( $url );
|
|
my $res = $ua->get( $url , $field_name => $value, ... );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch a <TT>"GET"</TT> request on the given <FONT SIZE="-1">URL.</FONT> Further
|
|
arguments can be given to initialize the headers of the request. These
|
|
are given as separate name/value pairs. The return value is a
|
|
response object. See HTTP::Response for a description of the
|
|
interface it provides.
|
|
<P>
|
|
|
|
There will still be a response object returned when <FONT SIZE="-1">LWP</FONT> can't connect to the
|
|
server specified in the <FONT SIZE="-1">URL</FONT> or when other failures in protocol handlers occur.
|
|
These internal responses use the standard <FONT SIZE="-1">HTTP</FONT> status codes, so the responses
|
|
can't be differentiated by testing the response status code alone. Error
|
|
responses that <FONT SIZE="-1">LWP</FONT> generates internally will have the ``Client-Warning'' header
|
|
set to the value ``Internal response''. If you need to differentiate these
|
|
internal responses from responses that a remote server actually generates, you
|
|
need to test this header value.
|
|
<P>
|
|
|
|
Fields names that start with ``:'' are special. These will not
|
|
initialize headers of the request but will determine how the response
|
|
content is treated. The following special field names are recognized:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
':content_file' => $filename
|
|
':content_cb' => \&callback
|
|
':read_size_hint' => $bytes
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
If a <TT>$filename</TT> is provided with the <TT>":content_file"</TT> option, then the
|
|
response content will be saved here instead of in the response
|
|
object. If a callback is provided with the <TT>":content_cb"</TT> option then
|
|
this function will be called for each chunk of the response content as
|
|
it is received from the server. If neither of these options are
|
|
given, then the response content will accumulate in the response
|
|
object itself. This might not be suitable for very large response
|
|
bodies. Only one of <TT>":content_file"</TT> or <TT>":content_cb"</TT> can be
|
|
specified. The content of unsuccessful responses will always
|
|
accumulate in the response object itself, regardless of the
|
|
<TT>":content_file"</TT> or <TT>":content_cb"</TT> options passed in. Note that errors
|
|
writing to the content file (for example due to permission denied
|
|
or the filesystem being full) will be reported via the <TT>"Client-Aborted"</TT>
|
|
or <TT>"X-Died"</TT> response headers, and not the <TT>"is_success"</TT> method.
|
|
<P>
|
|
|
|
The <TT>":read_size_hint"</TT> option is passed to the protocol module which
|
|
will try to read data from the server in chunks of this size. A
|
|
smaller value for the <TT>":read_size_hint"</TT> will result in a higher
|
|
number of callback invocations.
|
|
<P>
|
|
|
|
The callback function is called with 3 arguments: a chunk of data, a
|
|
reference to the response object, and a reference to the protocol
|
|
object. The callback can abort the request by invoking <B>die()</B>. The
|
|
exception message will show up as the ``X-Died'' header field in the
|
|
response returned by the <B>get()</B> function.
|
|
<A NAME="lbBN"> </A>
|
|
<H3>head</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $ua->head( $url );
|
|
my $res = $ua->head( $url , $field_name => $value, ... );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch a <TT>"HEAD"</TT> request on the given <FONT SIZE="-1">URL.</FONT>
|
|
Otherwise it works like the ``get'' in LWP::UserAgent method described above.
|
|
<A NAME="lbBO"> </A>
|
|
<H3>is_protocol_supported</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $bool = $ua->is_protocol_supported( $scheme );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
You can use this method to test whether this user agent object supports the
|
|
specified <TT>"scheme"</TT>. (The <TT>"scheme"</TT> might be a string (like <TT>"http"</TT> or
|
|
<TT>"ftp"</TT>) or it might be an <FONT SIZE="-1">URI</FONT> object reference.)
|
|
<P>
|
|
|
|
Whether a scheme is supported is determined by the user agent's
|
|
<TT>"protocols_allowed"</TT> or <TT>"protocols_forbidden"</TT> lists (if any), and by
|
|
the capabilities of <FONT SIZE="-1">LWP.</FONT> I.e., this will return true only if <FONT SIZE="-1">LWP</FONT>
|
|
supports this protocol <I>and</I> it's permitted for this particular
|
|
object.
|
|
<A NAME="lbBP"> </A>
|
|
<H3>is_online</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $bool = $ua->is_online;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Tries to determine if you have access to the Internet. Returns <TT>1</TT> (true)
|
|
if the built-in heuristics determine that the user agent is
|
|
able to access the Internet (over <FONT SIZE="-1">HTTP</FONT>) or <TT>0</TT> (false).
|
|
<P>
|
|
|
|
See also LWP::Online.
|
|
<A NAME="lbBQ"> </A>
|
|
<H3>mirror</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $ua->mirror( $url, $filename );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will get the document identified by <FONT SIZE="-1">URL</FONT> and store it in
|
|
file called <TT>$filename</TT>. If the file already exists, then the request
|
|
will contain an <TT>"If-Modified-Since"</TT> header matching the modification
|
|
time of the file. If the document on the server has not changed since
|
|
this time, then nothing happens. If the document has been updated, it
|
|
will be downloaded again. The modification time of the file will be
|
|
forced to match that of the server.
|
|
<P>
|
|
|
|
The return value is an HTTP::Response object.
|
|
<A NAME="lbBR"> </A>
|
|
<H3>patch # Any version of HTTP::Message works with this form: my $res = $ua->patch( $url, $field_name => $value, Content => $content );</H3>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# Using hash or array references requires HTTP::Message >= 6.12
|
|
use HTTP::Request 6.12;
|
|
my $res = $ua->patch( $url, \%form );
|
|
my $res = $ua->patch( $url, \@form );
|
|
my $res = $ua->patch( $url, \%form, $field_name => $value, ... );
|
|
my $res = $ua->patch( $url, $field_name => $value, Content => \%form );
|
|
my $res = $ua->patch( $url, $field_name => $value, Content => \@form );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch a <TT>"PATCH"</TT> request on the given <FONT SIZE="-1">URL,</FONT> with
|
|
<TT>%form</TT> or <TT>@form</TT> providing the key/value pairs for the fill-in form
|
|
content. Additional headers and content options are the same as for
|
|
the ``get'' in LWP::UserAgent method.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">CAVEAT:</FONT>
|
|
<P>
|
|
|
|
This method can only accept content that is in key-value pairs when using
|
|
HTTP::Request::Common prior to version <TT>6.12</TT>. Any use of hash or array
|
|
references will result in an error prior to version <TT>6.12</TT>.
|
|
<P>
|
|
|
|
This method will use the <TT>"PATCH"</TT> function from HTTP::Request::Common
|
|
to build the request. See HTTP::Request::Common for a details on
|
|
how to pass form content and other advanced features.
|
|
<A NAME="lbBS"> </A>
|
|
<H3>post</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $ua->post( $url, \%form );
|
|
my $res = $ua->post( $url, \@form );
|
|
my $res = $ua->post( $url, \%form, $field_name => $value, ... );
|
|
my $res = $ua->post( $url, $field_name => $value, Content => \%form );
|
|
my $res = $ua->post( $url, $field_name => $value, Content => \@form );
|
|
my $res = $ua->post( $url, $field_name => $value, Content => $content );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch a <TT>"POST"</TT> request on the given <FONT SIZE="-1">URL,</FONT> with
|
|
<TT>%form</TT> or <TT>@form</TT> providing the key/value pairs for the fill-in form
|
|
content. Additional headers and content options are the same as for
|
|
the ``get'' in LWP::UserAgent method.
|
|
<P>
|
|
|
|
This method will use the <TT>"POST"</TT> function from HTTP::Request::Common
|
|
to build the request. See HTTP::Request::Common for a details on
|
|
how to pass form content and other advanced features.
|
|
<A NAME="lbBT"> </A>
|
|
<H3>put</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# Any version of HTTP::Message works with this form:
|
|
my $res = $ua->put( $url, $field_name => $value, Content => $content );
|
|
|
|
# Using hash or array references requires HTTP::Message >= 6.07
|
|
use HTTP::Request 6.07;
|
|
my $res = $ua->put( $url, \%form );
|
|
my $res = $ua->put( $url, \@form );
|
|
my $res = $ua->put( $url, \%form, $field_name => $value, ... );
|
|
my $res = $ua->put( $url, $field_name => $value, Content => \%form );
|
|
my $res = $ua->put( $url, $field_name => $value, Content => \@form );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch a <TT>"PUT"</TT> request on the given <FONT SIZE="-1">URL,</FONT> with
|
|
<TT>%form</TT> or <TT>@form</TT> providing the key/value pairs for the fill-in form
|
|
content. Additional headers and content options are the same as for
|
|
the ``get'' in LWP::UserAgent method.
|
|
<P>
|
|
|
|
<FONT SIZE="-1">CAVEAT:</FONT>
|
|
<P>
|
|
|
|
This method can only accept content that is in key-value pairs when using
|
|
HTTP::Request::Common prior to version <TT>6.07</TT>. Any use of hash or array
|
|
references will result in an error prior to version <TT>6.07</TT>.
|
|
<P>
|
|
|
|
This method will use the <TT>"PUT"</TT> function from HTTP::Request::Common
|
|
to build the request. See HTTP::Request::Common for a details on
|
|
how to pass form content and other advanced features.
|
|
<A NAME="lbBU"> </A>
|
|
<H3>request</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $res = $ua->request( $request );
|
|
my $res = $ua->request( $request, $content_file );
|
|
my $res = $ua->request( $request, $content_cb );
|
|
my $res = $ua->request( $request, $content_cb, $read_size_hint );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method will dispatch the given <TT>$request</TT> object. Normally this
|
|
will be an instance of the HTTP::Request class, but any object with
|
|
a similar interface will do. The return value is an HTTP::Response object.
|
|
<P>
|
|
|
|
The <TT>"request"</TT> method will process redirects and authentication
|
|
responses transparently. This means that it may actually send several
|
|
simple requests via the ``simple_request'' in LWP::UserAgent method described below.
|
|
<P>
|
|
|
|
The request methods described above; ``get'' in LWP::UserAgent, ``head'' in LWP::UserAgent,
|
|
``post'' in LWP::UserAgent and ``mirror'' in LWP::UserAgent will all dispatch the request
|
|
they build via this method. They are convenience methods that simply hide the
|
|
creation of the request object for you.
|
|
<P>
|
|
|
|
The <TT>$content_file</TT>, <TT>$content_cb</TT> and <TT>$read_size_hint</TT> all correspond to
|
|
options described with the ``get'' in LWP::UserAgent method above. Note that errors
|
|
writing to the content file (for example due to permission denied
|
|
or the filesystem being full) will be reported via the <TT>"Client-Aborted"</TT>
|
|
or <TT>"X-Died"</TT> response headers, and not the <TT>"is_success"</TT> method.
|
|
<P>
|
|
|
|
You are allowed to use a <FONT SIZE="-1">CODE</FONT> reference as <TT>"content"</TT> in the request
|
|
object passed in. The <TT>"content"</TT> function should return the content
|
|
when called. The content can be returned in chunks. The content
|
|
function will be invoked repeatedly until it return an empty string to
|
|
signal that there is no more content.
|
|
<A NAME="lbBV"> </A>
|
|
<H3>simple_request</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $request = HTTP::Request->new( ... );
|
|
my $res = $ua->simple_request( $request );
|
|
my $res = $ua->simple_request( $request, $content_file );
|
|
my $res = $ua->simple_request( $request, $content_cb );
|
|
my $res = $ua->simple_request( $request, $content_cb, $read_size_hint );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method dispatches a single request and returns the response
|
|
received. Arguments are the same as for the ``request'' in LWP::UserAgent described above.
|
|
<P>
|
|
|
|
The difference from ``request'' in LWP::UserAgent is that <TT>"simple_request"</TT> will not try to
|
|
handle redirects or authentication responses. The ``request'' in LWP::UserAgent method
|
|
will, in fact, invoke this method for each simple request it sends.
|
|
<A NAME="lbBW"> </A>
|
|
<H2>CALLBACK METHODS</H2>
|
|
|
|
|
|
|
|
The following methods will be invoked as requests are processed. These
|
|
methods are documented here because subclasses of LWP::UserAgent
|
|
might want to override their behaviour.
|
|
<A NAME="lbBX"> </A>
|
|
<H3>get_basic_credentials</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# This checks wantarray and can either return an array:
|
|
my ($user, $pass) = $ua->get_basic_credentials( $realm, $uri, $isproxy );
|
|
# or a string that looks like "user:pass"
|
|
my $creds = $ua->get_basic_credentials($realm, $uri, $isproxy);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This is called by ``request'' in LWP::UserAgent to retrieve credentials for documents
|
|
protected by Basic or Digest Authentication. The arguments passed in
|
|
is the <TT>$realm</TT> provided by the server, the <TT>$uri</TT> requested and a
|
|
<TT>"boolean flag"</TT> to indicate if this is authentication against a proxy server.
|
|
<P>
|
|
|
|
The method should return a username and password. It should return an
|
|
empty list to abort the authentication resolution attempt. Subclasses
|
|
can override this method to prompt the user for the information. An
|
|
example of this can be found in <TT>"lwp-request"</TT> program distributed
|
|
with this library.
|
|
<P>
|
|
|
|
The base implementation simply checks a set of pre-stored member
|
|
variables, set up with the ``credentials'' in LWP::UserAgent method.
|
|
<A NAME="lbBY"> </A>
|
|
<H3>prepare_request</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$request = $ua->prepare_request( $request );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method is invoked by ``simple_request'' in LWP::UserAgent. Its task is
|
|
to modify the given <TT>$request</TT> object by setting up various headers based
|
|
on the attributes of the user agent. The return value should normally be the
|
|
<TT>$request</TT> object passed in. If a different request object is returned
|
|
it will be the one actually processed.
|
|
<P>
|
|
|
|
The headers affected by the base implementation are; <TT>"User-Agent"</TT>,
|
|
<TT>"From"</TT>, <TT>"Range"</TT> and <TT>"Cookie"</TT>.
|
|
<A NAME="lbBZ"> </A>
|
|
<H3>progress</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $prog = $ua->progress( $status, $request_or_response );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This is called frequently as the response is received regardless of
|
|
how the content is processed. The method is called with <TT>$status</TT>
|
|
``begin'' at the start of processing the request and with <TT>$state</TT> ``end''
|
|
before the request method returns. In between these <TT>$status</TT> will be
|
|
the fraction of the response currently received or the string ``tick''
|
|
if the fraction can't be calculated.
|
|
<P>
|
|
|
|
When <TT>$status</TT> is ``begin'' the second argument is the HTTP::Request object,
|
|
otherwise it is the HTTP::Response object.
|
|
<A NAME="lbCA"> </A>
|
|
<H3>redirect_ok</H3>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
my $bool = $ua->redirect_ok( $prospective_request, $response );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This method is called by ``request'' in LWP::UserAgent before it tries to follow a
|
|
redirection to the request in <TT>$response</TT>. This should return a true
|
|
value if this redirection is permissible. The <TT>$prospective_request</TT>
|
|
will be the request to be sent if this method returns true.
|
|
<P>
|
|
|
|
The base implementation will return false unless the method
|
|
is in the object's <TT>"requests_redirectable"</TT> list,
|
|
false if the proposed redirection is to a <TT>"<A HREF="file://...">file://...</A>"</TT>
|
|
<FONT SIZE="-1">URL,</FONT> and true otherwise.
|
|
<A NAME="lbCB"> </A>
|
|
<H2>BEST PRACTICES</H2>
|
|
|
|
|
|
|
|
The default settings can get you up and running quickly, but there are settings
|
|
you can change in order to make your life easier.
|
|
<A NAME="lbCC"> </A>
|
|
<H3>Handling Cookies</H3>
|
|
|
|
|
|
|
|
You are encouraged to install Mozilla::PublicSuffix and use
|
|
HTTP::CookieJar::LWP as your cookie jar. HTTP::CookieJar::LWP provides a
|
|
better security model matching that of current Web browsers when
|
|
Mozilla::PublicSuffix is installed.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
use HTTP::CookieJar::LWP ();
|
|
|
|
my $jar = HTTP::CookieJar::LWP->new;
|
|
my $ua = LWP::UserAgent->new( cookie_jar => $jar );
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
See ``cookie_jar'' for more information.
|
|
<A NAME="lbCD"> </A>
|
|
<H3>Managing Protocols</H3>
|
|
|
|
|
|
|
|
<TT>"protocols_allowed"</TT> gives you the ability to whitelist the protocols you're
|
|
willing to allow.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $ua = LWP::UserAgent->new(
|
|
protocols_allowed => [ 'http', 'https' ]
|
|
);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This will prevent you from inadvertently following URLs like
|
|
<TT>"<A HREF="file:///etc/passwd">file:///etc/passwd</A>"</TT>. See ``protocols_allowed''.
|
|
<P>
|
|
|
|
<TT>"protocols_forbidden"</TT> gives you the ability to blacklist the protocols you're
|
|
unwilling to allow.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
my $ua = LWP::UserAgent->new(
|
|
protocols_forbidden => [ 'file', 'mailto', 'ssh', ]
|
|
);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This can also prevent you from inadvertently following URLs like
|
|
<TT>"<A HREF="file:///etc/passwd">file:///etc/passwd</A>"</TT>. See ``protocols_forbidden''.
|
|
<A NAME="lbCE"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
See <FONT SIZE="-1">LWP</FONT> for a complete overview of libwww-perl5. See lwpcook
|
|
and the scripts <I>lwp-request</I> and <I>lwp-download</I> for examples of
|
|
usage.
|
|
<P>
|
|
|
|
See HTTP::Request and HTTP::Response for a description of the
|
|
message objects dispatched and received. See HTTP::Request::Common
|
|
and HTML::Form for other ways to build request objects.
|
|
<P>
|
|
|
|
See WWW::Mechanize and WWW::Search for examples of more
|
|
specialized user agents based on LWP::UserAgent.
|
|
<A NAME="lbCF"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
Copyright 1995-2009 Gisle Aas.
|
|
<P>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="11"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="12"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="13"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="14"><A HREF="#lbAE">CONSTRUCTOR METHODS</A><DD>
|
|
<DL>
|
|
<DT id="15"><A HREF="#lbAF">clone</A><DD>
|
|
<DT id="16"><A HREF="#lbAG">new</A><DD>
|
|
</DL>
|
|
<DT id="17"><A HREF="#lbAH">ATTRIBUTES</A><DD>
|
|
<DL>
|
|
<DT id="18"><A HREF="#lbAI">agent</A><DD>
|
|
<DT id="19"><A HREF="#lbAJ">conn_cache</A><DD>
|
|
<DT id="20"><A HREF="#lbAK">cookie_jar</A><DD>
|
|
<DT id="21"><A HREF="#lbAL">credentials</A><DD>
|
|
<DT id="22"><A HREF="#lbAM">default_header</A><DD>
|
|
<DT id="23"><A HREF="#lbAN">default_headers</A><DD>
|
|
<DT id="24"><A HREF="#lbAO">from</A><DD>
|
|
<DT id="25"><A HREF="#lbAP">local_address</A><DD>
|
|
<DT id="26"><A HREF="#lbAQ">max_redirect</A><DD>
|
|
<DT id="27"><A HREF="#lbAR">max_size</A><DD>
|
|
<DT id="28"><A HREF="#lbAS">parse_head</A><DD>
|
|
<DT id="29"><A HREF="#lbAT">protocols_allowed</A><DD>
|
|
<DT id="30"><A HREF="#lbAU">protocols_forbidden</A><DD>
|
|
<DT id="31"><A HREF="#lbAV">requests_redirectable</A><DD>
|
|
<DT id="32"><A HREF="#lbAW">send_te</A><DD>
|
|
<DT id="33"><A HREF="#lbAX">show_progress</A><DD>
|
|
<DT id="34"><A HREF="#lbAY">ssl_opts</A><DD>
|
|
<DT id="35"><A HREF="#lbAZ">timeout</A><DD>
|
|
</DL>
|
|
<DT id="36"><A HREF="#lbBA">PROXY ATTRIBUTES</A><DD>
|
|
<DL>
|
|
<DT id="37"><A HREF="#lbBB">env_proxy</A><DD>
|
|
<DT id="38"><A HREF="#lbBC">no_proxy</A><DD>
|
|
<DT id="39"><A HREF="#lbBD">proxy</A><DD>
|
|
</DL>
|
|
<DT id="40"><A HREF="#lbBE">HANDLERS</A><DD>
|
|
<DL>
|
|
<DT id="41"><A HREF="#lbBF">add_handler</A><DD>
|
|
<DT id="42"><A HREF="#lbBG">get_my_handler</A><DD>
|
|
<DT id="43"><A HREF="#lbBH">handlers</A><DD>
|
|
<DT id="44"><A HREF="#lbBI">remove_handler</A><DD>
|
|
<DT id="45"><A HREF="#lbBJ">set_my_handler</A><DD>
|
|
</DL>
|
|
<DT id="46"><A HREF="#lbBK">REQUEST METHODS</A><DD>
|
|
<DL>
|
|
<DT id="47"><A HREF="#lbBL">delete</A><DD>
|
|
<DT id="48"><A HREF="#lbBM">get</A><DD>
|
|
<DT id="49"><A HREF="#lbBN">head</A><DD>
|
|
<DT id="50"><A HREF="#lbBO">is_protocol_supported</A><DD>
|
|
<DT id="51"><A HREF="#lbBP">is_online</A><DD>
|
|
<DT id="52"><A HREF="#lbBQ">mirror</A><DD>
|
|
<DT id="53"><A HREF="#lbBR">patch # Any version of HTTP::Message works with this form: my $res = $ua->patch( $url, $field_name => $value, Content => $content );</A><DD>
|
|
<DT id="54"><A HREF="#lbBS">post</A><DD>
|
|
<DT id="55"><A HREF="#lbBT">put</A><DD>
|
|
<DT id="56"><A HREF="#lbBU">request</A><DD>
|
|
<DT id="57"><A HREF="#lbBV">simple_request</A><DD>
|
|
</DL>
|
|
<DT id="58"><A HREF="#lbBW">CALLBACK METHODS</A><DD>
|
|
<DL>
|
|
<DT id="59"><A HREF="#lbBX">get_basic_credentials</A><DD>
|
|
<DT id="60"><A HREF="#lbBY">prepare_request</A><DD>
|
|
<DT id="61"><A HREF="#lbBZ">progress</A><DD>
|
|
<DT id="62"><A HREF="#lbCA">redirect_ok</A><DD>
|
|
</DL>
|
|
<DT id="63"><A HREF="#lbCB">BEST PRACTICES</A><DD>
|
|
<DL>
|
|
<DT id="64"><A HREF="#lbCC">Handling Cookies</A><DD>
|
|
<DT id="65"><A HREF="#lbCD">Managing Protocols</A><DD>
|
|
</DL>
|
|
<DT id="66"><A HREF="#lbCE">SEE ALSO</A><DD>
|
|
<DT id="67"><A HREF="#lbCF">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:47 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|