ch20_02.htm

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

arguments, this method returns the current value of the email address
used in the From header. If invoked with an argument, the From header
will use that email address in the future. (The From header tells the
web server the email address of the person running the client
software.)
</p></div>

<a name="INDEX-2432" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get</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;get($<em class="replaceable">url</em>, [<em class="replaceable">Header =&gt; Value</em>])
</pre><p><a name="INDEX-2432" />Shortcut for
<tt class="literal">$</tt><em class="replaceable"><tt>ua</tt></em><tt class="literal">-&gt;request(HTTP::Request::Common::GET(
$</tt><em class="replaceable"><tt>url</tt></em><tt class="literal">,</tt>
<em class="replaceable"><tt>Header</tt></em> <tt class="literal">=&gt;</tt>
<em class="replaceable"><tt>Value</tt></em><tt class="literal">,...</tt>
<tt class="literal">))</tt>.
</p></div>

<a name="INDEX-2433" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>get_basic_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;get_basic_credentials(<em class="replaceable">realm</em>, <em class="replaceable">url</em>)
</pre><p><a name="INDEX-2433" />Returns the list containing
the username and password for the given
<em class="replaceable"><tt>realm</em> and <em class="replaceable">url</tt></em>when authentication is required by the server. This function is
usually called internally by <tt class="literal">request</tt>. This method
becomes useful when creating a subclass of LWP::UserAgent with its
own version of <tt class="literal">get_basic_credentials</tt>. From there,
you can rewrite <tt class="literal">get_basic_credentials</tt> to do more
flexible things, such as asking the user for the account information,
or referring to authentication information in a file. All you need to
do is return a list in which the first element is a username and the
second element is a password.
</p></div>

<a name="INDEX-2434" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>head</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;head($<em class="replaceable">url</em>, [<em class="replaceable">Header =&gt; Value</em>])
</pre><p><a name="INDEX-2434" />Shortcut for
<tt class="literal">$</tt><em class="replaceable"><tt>ua</tt></em><tt class="literal">-&gt;request(HTTP::Request::Common::HEAD(
$</tt><em class="replaceable"><tt>url</tt></em><tt class="literal">,</tt>
<em class="replaceable"><tt>Header</tt></em> <tt class="literal">=&gt;</tt>
<em class="replaceable"><tt>Value</tt></em><tt class="literal">,...))</tt>.
</p></div>

<a name="INDEX-2435" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_protocol_supported</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;is_protocol_supported(<em class="replaceable">proto</em>)
</pre><p><a name="INDEX-2435" />Given a scheme, this method
returns a true or false (nonzero or zero) value. A true value means
that LWP knows how to handle a URL with the specified protocol. If it
returns a false value, LWP does not know how to handle the URL.
</p></div>

<a name="INDEX-2436" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>max_size</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;max_size([<em class="replaceable">size</em>])
</pre><p><a name="INDEX-2436" />Sets or returns the maximum
<em class="replaceable"><tt>size</tt></em> (in bytes) for response content. The
default is <tt class="literal">undef</tt>, which means that there is no
limit. If the returned content is partial because the size limit was
exceeded, then an X-Content-Range header will be added to the
response.
</p></div>

<a name="INDEX-2437" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>mirror</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;mirror(<em class="replaceable">url</em>, <em class="replaceable">file</em>)
</pre><p><a name="INDEX-2437" />Given a URL and file path, this method
copies the contents of <em class="replaceable"><tt>url</tt></em> into the file
when the length or modification date headers are different from any
previous retrieval. If the file does not exist, it is created. This
method returns an HTTP::Response object, in which the response code
indicates what happened.
</p></div>

<a name="INDEX-2438" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>no_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;no_proxy(<em class="replaceable">domains</em>)
</pre><p><a name="INDEX-2438" />Does not use a proxy server
for the specified <em class="replaceable"><tt>domains</tt></em>.
</p></div>

<a name="INDEX-2439" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>parse_head</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;parse_head([<em class="replaceable">boolean</em>])
</pre><p><a name="INDEX-2439" />Sets or returns a true or
false value indicating whether response headers from the
<tt class="literal">&lt;head&gt;</tt> sections of HTML documents are
initialized. The default is true.
</p></div>

<a name="INDEX-2440" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>post</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;post($<em class="replaceable">url</em>, \%<em class="replaceable">formref</em>, [<em class="replaceable">Header =&gt; Value</em>])
</pre><p><a name="INDEX-2440" />Shortcut for
<tt class="literal">$</tt><em class="replaceable"><tt>ua</tt></em><tt class="literal">-&gt;request(HTTP::Request::Common::POST(
$</tt><em class="replaceable"><tt>url</tt></em><tt class="literal">,
\%</tt><em class="replaceable"><tt>formref</tt></em><tt class="literal">,</tt>
<em class="replaceable"><tt>Header</tt></em> <tt class="literal">=&gt;</tt>
<em class="replaceable"><tt>Value</tt></em><tt class="literal">,... ))</tt>. The form
reference is optional and can be either a hashref or an arrayref.
</p></div>

<a name="INDEX-2441" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>protocols_allowed</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;protocols_allowed([\@<em class="replaceable">protocols</em>])
</pre><p><a name="INDEX-2441" />Assigns the list of protocols
that <tt class="literal">$ua-&gt;request</tt> and
<tt class="literal">$ua-&gt;simple_request</tt> will exclusively allow.
With no arguments, returns a list of the protocols currently allowed.
Assigning to a value of <tt class="literal">undef</tt> deletes the list.
</p></div>

<a name="INDEX-2442" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>protocols_forbidden</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;protocols_forbidden([\@<em class="replaceable">protocols</em>])
</pre><p><a name="INDEX-2442" />Assigns the list of procotols
that <tt class="literal">$ua-&gt;request</tt> and
<tt class="literal">$ua-&gt;simple_request</tt> will not allow. With no
arguments, returns a list of the protocols currently prohibited.
Assigning to a value of <tt class="literal">undef</tt> deletes the list.
</p></div>

<a name="INDEX-2443" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>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;proxy(<em class="replaceable">prot</em>, <em class="replaceable">proxy_url</em>)
</pre><p><a name="INDEX-2443" />Defines a URL
(<em class="replaceable"><tt>proxy_url</tt></em>) to use with the specified
protocols, <em class="replaceable"><tt>prot</tt></em>. The first parameter can
be a reference to a list of protocol names or a scalar that contains
a single protocol. The second argument defines a proxy URL to use
with the protocol.
</p></div>

<a name="INDEX-2444" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>put</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><table width="515" border="0" cellpadding="5"><tr><td align="left"><pre>
$<em class="replaceable">ua</em>-&gt;put($<em class="replaceable">url</em>, [<em class="replaceable">Header =&gt; Value</em>])
<a name="INDEX-2444" />$<em class="replaceable">ua</em> -- &gt;gt;put($<em class="replaceable">url</em>, <em class="replaceable">Header</em> ==&gt;gt; <em class="replaceable">Value</em>,...)
</pre></td><td align="right" /></tr></table><p><p>Shortcut for
<tt class="literal">$</tt><em class="replaceable"><tt>ua</tt></em><tt class="literal">-&gt;request(HTTP::Request::Common::PUT(
$</tt><em class="replaceable"><tt>url</tt></em><tt class="literal">,</tt>
<em class="replaceable"><tt>Header</tt></em> <tt class="literal">=&gt;</tt>
<em class="replaceable"><tt>Value</tt></em><tt class="literal">,...))</tt>.
</p></div>

<a name="INDEX-2445" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>redirect_ok</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;redirect_ok($<em class="replaceable">this_request</em>)
</pre><p><a name="INDEX-2445" />This method is called by
<tt class="literal">request</tt> before it tries to follow a redirection to
the request in
<tt class="literal">$</tt><em class="replaceable"><tt>this_request</tt></em>. This
should return a true value if this redirection is permissible.
</p></div>

<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>request</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;request($<em class="replaceable">request</em>, [<em class="replaceable">file</em> | $<em class="replaceable">sub</em>, <em class="replaceable">size</em>])
</pre><p>Performs a request for the resource specified by
<tt class="literal">$</tt><em class="replaceable"><tt>request</tt></em>, which is an
HTTP::Request object. Returns the information received from the
server as an HTTP::Response object. Normally, doing a
<tt class="literal">$ua-&gt;request($request)</tt> is enough. You can also
specify a subroutine to process the data as it comes in or provide a
filename in which to store the entity body of the response. The
arguments are:
</p><dl>
<dt><b><tt class="literal">$</tt><em class="replaceable">request</em></b></dt>
<dd>
An HTTP::Request object. The object must contain the method and URL
of the site to be queried. This object must exist before
<tt class="literal">request</tt> is called.
</p>
</dd>


<dt><i><em class="replaceable"><tt>file</tt></em></i></dt>
<dd>
Name of the file in which to store the response's
entity body. When this option is used on <tt class="literal">request</tt>,
the entity body of the returned response object will be empty.
</p>
</dd>


<dt><b><tt class="literal">$</tt><em class="replaceable">sub</em></b></dt>
<dd>
A reference to a subroutine that will process the data of the
response. If you use the optional third argument,
<em class="replaceable"><tt>size</tt></em>, the subroutine will be called any
time that number of bytes is received as response data. The
subroutine should expect each chunk of the entity body data as a
scalar in the first argument, an HTTP::Response object as the second
argument, and an LWP::Protocol object as the third argument.
</p>
</dd>


<dt><i><em class="replaceable"><tt>size</tt></em></i></dt>

<dd>
Optional argument specifying the number of bytes of the entity body
received before the <em class="emphasis">sub</em> callback is called to
process response data.
</p>
</dd>

</dl></div>

<a name="INDEX-2446" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>requests_redirectable</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;requests_redirectable([\@<em class="replaceable">requests</em>])
</pre><p><a name="INDEX-2446" />Assigns the
list of request names that <tt class="literal">$ua-&gt;redirect_ok</tt>
will allow to be redirected. With no arguments, returns the current
list of request names. By default, GET and HEAD requests are allowed;
to include POST requests, enter:
</p><blockquote><pre class="code">push @{ $ua-&gt;requests_redirectable }, 'POST';</pre></blockquote></div>

<a name="INDEX-2447" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>timeout</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;timeout([<em class="replaceable">secs</em>])
</pre><p><a name="INDEX-2447" />When invoked with no arguments,
<tt class="literal">timeout</tt> returns the timeout value of a request. By
default, this value is three minutes. Therefore, if the client
software doesn't hear back from the server within
three minutes, it will stop the transaction and indicate that a
timeout occurred in the HTTP response code. If invoked with an
argument, the timeout value is redefined to be that value.
</p></div>

<a name="INDEX-2448" /><a name="INDEX-2449" /><a name="INDEX-2450" /><a name="INDEX-2451" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>use_alarm</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;use_alarm([<em class="replaceable">boolean</em>])
</pre><p><a name="INDEX-2448" />Retrieves or defines the
ability to use <tt class="literal">alarm</tt> for timeouts. By default,
timeouts with <tt class="literal">alarm</tt> are enabled. If you plan on
using <tt class="literal">alarm</tt> for your own purposes, or it
isn't supported on your system, it is recommended
that you disable <tt class="literal">alarm</tt> by calling this method with
a value of <tt class="literal">0</tt>.<a name="INDEX-2449" /><a name="INDEX-2450" /><a name="INDEX-2451" /> 
</p></div>
</div>


<hr width="684" align="left" />
<div class="navbar"><table width="684" border="0"><tr><td align="left" valign="top" width="228"><a href="ch20_01.htm"><img src="../gifs/txtpreva.gif" alt="Previous" border="0" /></a></td><td align="center" valign="top" width="228"><a href="index.htm"><img src="../gifs/txthome.gif" alt="Home" border="0" /></a></td><td align="right" valign="top" width="228"><a href="ch20_03.htm"><img src="../gifs/txtnexta.gif" alt="Next" border="0" /></a></td></tr><tr><td align="left" valign="top" width="228">20. The LWP Library</td><td align="center" valign="top" width="228"><a href="index/index.htm"><img src="../gifs/index.gif" alt="Book Index" border="0" /></a></td><td align="right" valign="top" width="228">20.3. The HTTP Modules</td></tr></table></div>
<hr width="684" align="left" />

<img src="../gifs/navbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links" />
<p><p><font size="-1"><a href="copyrght.htm">Copyright &copy; 2002</a> O'Reilly &amp; Associates. All rights reserved.</font></p>

<map name="library-map">
<area shape="rect" coords="1,0,85,94" href="../index.htm"><area shape="rect" coords="86,1,178,103" href="../lwp/index.htm"><area shape="rect" coords="180,0,265,103" href="../lperl/index.htm"><area shape="rect" coords="267,0,353,105" href="../perlnut/index.htm"><area shape="rect" coords="354,1,446,115" href="../prog/index.htm"><area shape="rect" coords="448,0,526,132" href="../tk/index.htm"><area shape="rect" coords="528,1,615,119" href="../cookbook/index.htm"><area shape="rect" coords="617,0,690,135" href="../pxml/index.htm">
</map>

</body></html>