ch20_02.htm

by Randal L. Schwartz and Tom Phoenix ISBN 0-596-00132-0 Third Edition, published July 2001. (See

<p><a name="INDEX-2419" /><a name="INDEX-2420" /><a name="INDEX-2421" />Requests over the network are performed
with LWP::UserAgent objects. To create an LWP::UserAgent object, use:
</p>

<blockquote><pre class="code">$ua = LWP::UserAgent-&gt;new( );</pre></blockquote>

<p>You give the object a request, which it uses to contact the server,
and the information you requested is returned<a name="INDEX-2422" />. The most often used method
in this module is <tt class="literal">request</tt>, which contacts a server
and returns the result of your query. Other methods in this module
change the way <tt class="literal">request</tt> behaves. You can change the
timeout value, customize the value of the User-Agent header, or use a
proxy server.
</p>

<p>The following methods are supplied by LWP::UserAgent.</p>



<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>new</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;new(%<em class="replaceable">options</em>)
</pre><p>Constructs a new LWP::UserAgent object and returns a reference to it.
Key/value arguments may be provided to set up the initial state of
the user agent. <tt class="literal">new</tt> accepts several options that
correspond to the following attribute methods:
</p><a name="ch20-16-fm2xml" /><table border="1" cellpadding="3">



<tr>
<th>
<p>Key</p>
</th>
<th>
<p>Default</p>
</th>
</tr>


<tr>
<td>
<p><tt class="literal">agent</tt></p>
</td>
<td>
<p><tt class="literal">"libwww-perl/#.##"</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">from</tt></p>
</td>
<td>
<p><tt class="literal">undef</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">timeout</tt></p>
</td>
<td>
<p><tt class="literal">180</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">use_eval</tt></p>
</td>
<td>
<p><tt class="literal">1</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">parse_head</tt></p>
</td>
<td>
<p><tt class="literal">1</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">max_size</tt></p>
</td>
<td>
<p><tt class="literal">undef</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">cookie_jar</tt></p>
</td>
<td>
<p><tt class="literal">undef</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">conn_cache</tt></p>
</td>
<td>
<p><tt class="literal">undef</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">protocols_allowed</tt></p>
</td>
<td>
<p><tt class="literal">undef</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">protocols_forbidden</tt></p>
</td>
<td>
<p><tt class="literal">undef</tt></p>
</td>
</tr>
<tr>
<td>
<p><tt class="literal">requests_redirectable</tt></p>
</td>
<td>
<p><tt class="literal">["GET", "HEAD"]</tt></p>
</td>
</tr>

</table><p><p>The options are:</p><dl>
<dt><b><tt class="literal">env_proxy</tt></b></dt>
<dd>
If set to true, proxy settings are read from environment variables.</p>
</dd>


<dt><b><tt class="literal">keep_alive</tt></b></dt>
<dd>
A number that will be passed on as the
<tt class="literal">total_capacity</tt> for the connection. A
LWP::ConnCache is set up (see the <tt class="literal">conn_cache</tt>
method), and the HTTP/1.1 protocol module is enabled.
</p>
</dd>

</dl></div>
<a name="INDEX-2423" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>agent</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;agent([<em class="replaceable">string</em>])
</pre><p><a name="INDEX-2423" />When invoked with no
arguments, this method returns the current value of the identifier
used in the User-Agent HTTP header. If invoked with an argument, the
User-Agent header will use <em class="replaceable"><tt>string</tt></em> as its
identifier in the future.
</p></div>

<a name="INDEX-2424" /><a name="INDEX-2425" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>_agent</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;_agent(  )
</pre><p><a name="INDEX-2424" /> <a name="INDEX-2425" />Returns the default agent
identifier. This is a string of the form
<tt class="literal">"libwww-perl/#.##"</tt>, in which
<tt class="literal">#.##</tt> is substituted with the version number of
this library.
</p></div>

<a name="INDEX-2426" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>clone</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;clone(  )
</pre><p><a name="INDEX-2426" />Returns a copy of the LWP::UserAgent
object.
</p></div>

<a name="INDEX-2427" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>conn_cache</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;conn_cache([$<em class="replaceable">cache_object</em>])
</pre><p><a name="INDEX-2427" />Defines the LWP::ConnCache
object to use. With no arguments, returns the current LWP::ConnCache
object.
</p></div>

<a name="INDEX-2428" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>cookie_jar</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;cookie_jar([$<em class="replaceable">cjar</em>])
</pre><p><a name="INDEX-2428" />Specifies the "cookie
jar" object to use with the UserAgent object, or
returns it if invoked with no argument.
<tt class="literal">$</tt><em class="replaceable"><tt>cjar</tt></em> is a reference to
an HTTP::Cookies object that contains client cookie data. See the
HTTP::Cookies section for more information.
</p></div>

<a name="INDEX-2429" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>credentials</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;credentials(<em class="replaceable">netloc</em>, <em class="replaceable">realm</em>, <em class="replaceable">uname</em>, <em class="replaceable">pass</em>)
</pre><p><a name="INDEX-2429" />Uses the given username and
password for authentication at the given network location and realm.
This method sets the parameters for either the WWW-Authenticate or
Proxy-Authenticate headers in a request. The
<tt class="literal">get_basic_credentials</tt> method is called by
<tt class="literal">request</tt> to retrieve the username and passwords, if
they exist. The arguments are:
</p><dl>
<dt><i><em class="replaceable"><tt>netloc</tt></em></i></dt>
<dd>
The network location (usually a URL string) to which the username and
password apply.
</p>
</dd>


<dt><i><em class="replaceable"><tt>realm</tt></em></i></dt>
<dd>
The name of the server-defined range of URLs that this data applies
to.
</p>
</dd>


<dt><i><em class="replaceable"><tt>uname</tt></em></i></dt>
<dd>
The username for authentication.</p>
</dd>


<dt><i><em class="replaceable"><tt>pass</tt></em></i></dt>
<dd>
The password for authentication. By default, the password will be
transmitted with MIME base-64 encoding.
</p>
</dd>

</dl></div>

<a name="INDEX-2430" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>env_proxy</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;env_proxy(  )
</pre><p><a name="INDEX-2430" />Defines a scheme/proxy URL
mapping by looking at environment variables. For example, to define
the HTTP proxy, one would define the HTTP_PROXY environment variable
with the proxy's URL. To define a domain to avoid
the proxy, one would define the NO_PROXY environment variable with
the domain that doesn't need a proxy.
</p></div>

<a name="INDEX-2431" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>from</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$<em class="replaceable">ua</em>-&gt;from([<em class="replaceable">email</em>])
</pre><p><a name="INDEX-2431" />When invoked with no