ch20_03.htm

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

<a name="INDEX-2469" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>current_age</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">resp</em>-&gt;current_age(  )
</pre><p><a name="INDEX-2469" />Returns the number of seconds
since the response was generated by the original server.
</p></div>

<a name="INDEX-2470" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>error_as_HTML</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">resp</em>-&gt;error_as_HTML(  )
</pre><p><a name="INDEX-2470" />When
<tt class="literal">is_error</tt> is true, this method returns an HTML
explanation of what happened.
</p></div>

<a name="INDEX-2471" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>freshness_lifetime</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">resp</em>-&gt;freshness_lifetime(  )
</pre><p><a name="INDEX-2471" />Returns the number of seconds
until the response expires. If expiration was not specified by the
server, LWP will make an informed guess based on the Last-Modified
header of the response.
</p></div>

<a name="INDEX-2472" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>fresh_until</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">resp</em>-&gt;fresh_until(  )
</pre><p><a name="INDEX-2472" />Returns the time when the
response expires. The time is based on the number of seconds since
January 1, 1970, UTC.
</p></div>

<a name="INDEX-2473" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_error</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">resp</em>-&gt;is_error(  )
</pre><p><a name="INDEX-2473" />Returns true when the response code is
400 through 599. When an error occurs, you might want to use
<tt class="literal">error_as_HTML</tt> to generate an HTML explanation of
the error.
</p></div>

<a name="INDEX-2474" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_fresh</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">resp</em>-&gt;is_fresh(  )
</pre><p><a name="INDEX-2474" />Returns true if the response
has not yet expired.
</p></div>

<a name="INDEX-2475" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_info</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">resp</em>-&gt;is_info(  )
</pre><p><a name="INDEX-2475" />Returns true when the response code is
100 through 199.
</p></div>

<a name="INDEX-2476" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_redirect</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">resp</em>-&gt;is_redirect(  )
</pre><p><a name="INDEX-2476" />Returns true when the response code is
300 through 399.
</p></div>

<a name="INDEX-2477" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>is_success</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">resp</em>-&gt;is_success(  )
</pre><p><a name="INDEX-2477" />Returns true when the response code is
200 through 299.
</p></div>

<a name="INDEX-2478" /><a name="INDEX-2479" /><a name="INDEX-2480" /><a name="INDEX-2481" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>message</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">resp</em>-&gt;message ([<em class="replaceable">msg</em>])
</pre><p><a name="INDEX-2478" />When invoked without any
parameters, <tt class="literal">message</tt> returns the
object's status code message (the short string
describing the response code). When invoked with a scalar
<em class="replaceable"><tt>msg</tt></em> argument, this method defines the
object's message.<a name="INDEX-2479" /><a name="INDEX-2480" /><a name="INDEX-2481" /> 
</p></div>

<a name="INDEX-2482" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>status_line</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">resp</em>-&gt;status_line(  )
</pre><p><a name="INDEX-2482" />Returns a string with the
HTTP status code and message. If the <tt class="literal">message</tt>
attribute is unspecified, the official message associated with
<tt class="literal">code</tt> is used.
</p></div>

</div>
<a name="perlnut2-CHP-20-SECT-3.3" /><div class="sect2">
<h3 class="sect2">20.3.3. HTTP::Headers</h3>

<p><a name="INDEX-2483" /><a name="INDEX-2484" /><a name="INDEX-2485" />This module deals with HTTP header
definition and manipulation. You can use these methods on
HTTP::Request and HTTP::Response objects to retrieve headers they
contain, or to set new headers and values for new objects you are
building.
</p>

<p><a name="INDEX-2486" />The constructor for an HTTP::Headers
object looks like this:
</p>

<blockquote><pre class="code">$h = HTTP::Headers-&gt;new([<em class="replaceable"><tt>name</em> =&gt; <em class="replaceable">val</tt></em>],...);</pre></blockquote>

<p>This code creates a new headers object. You can set headers in the
constructor by providing a header name and its value. Multiple
<em class="replaceable"><tt>name</em><tt class="literal">=&gt;</tt><em class="replaceable">val</tt></em>pairs can be used to set multiple headers.
</p>

<p>The following methods can be used by objects in the HTTP::Headers
class. These methods can also be used on objects from HTTP::Request
and HTTP::Response, since they inherit from HTTP::Headers. In fact,
most header manipulation will occur on the request and response
objects in LWP applications.
</p>


<a name="INDEX-2487" /><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">h</em>-&gt;clone(  )
</pre><p><a name="INDEX-2487" />Creates a copy of the current object,
<tt class="literal">$</tt><em class="replaceable"><tt>h</tt></em>, and returns a
reference to it.
</p></div>

<a name="INDEX-2488" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>header</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">h</em>-&gt;header(<em class="replaceable">field</em> [=&gt; $<em class="replaceable">val</em>],...)
</pre><p><a name="INDEX-2488" />When called with just an HTTP header as
a parameter, this method returns the current value for the header.
For example, <tt class="literal">$myobject-&gt;('content-type')</tt> would
return the value for the object's Content-Type
header. To define a new header value, invoke
<tt class="literal">header</tt> with a hash of
<tt class="literal">header=&gt;value</tt> pairs, in which the value is a
scalar or reference to an array. For example, to define the
Content-Type header, you would do this:
</p><blockquote><pre class="code">$h-&gt;header('content-type' =&gt; 'text/plain');</pre></blockquote></div>

<a name="INDEX-2489" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>init_header</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$h-&gt;init_header($field, $value)
</pre><p><a name="INDEX-2489" />Sets the specified header to
the given value, but only if no previous value for that field is set.
The header field name is not case-sensitive, and <tt class="literal">_</tt>
can be used as a replacement for <tt class="literal">-</tt>. The
<tt class="literal">$value</tt> argument may be a scalar or a reference to
a list of scalars. Previous values of the field are not removed.
</p></div>

<a name="INDEX-2490" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>push_header</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
$h-&gt;push_header(field =&gt; val)
</pre><p><a name="INDEX-2490" />Adds a new header field and
value to the object. Previous values of the field are not removed.
</p><blockquote><pre class="code">$h-&gt;push_header(Accept =&gt; 'image/jpeg');</pre></blockquote></div>

<a name="INDEX-2491" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>remove_header</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">h</em>-&gt;remove_header(<em class="replaceable">field</em>,...)
</pre><p><a name="INDEX-2491" />Removes the header specified
in the parameter(s) and the header's associated
value.
</p></div>

<a name="INDEX-2492" /><a name="INDEX-2493" /><a name="INDEX-2494" /><a name="INDEX-2495" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>scan</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">h</em>-&gt;scan($<em class="replaceable">sub</em>)
</pre><p><a name="INDEX-2492" />Invokes the subroutine referenced by
<tt class="literal">$</tt><em class="replaceable"><tt>sub</tt></em> for each header
field in the object. The subroutine is passed the name of the header
and its value as a pair of arguments. For header fields with more
than one value, the subroutine will be called once for each value.
</p><p>The HTTP::Headers class allows you to use a number of convenience
methods on header objects to set (or read) common field values. If
you supply a value for an argument, that value will be set for the
field. The previous value for the header is always returned. The
following methods are available:
</p><blockquote><pre class="code">date
expires
if_modified_since
if_unmodified_since
last_modified
content_type
content_encoding
content_length
content_language
title
user_agent
server
from
referrer
www_authenticate
proxy_authenticate
authorization
proxy_authorization
authorization_basic
proxy_authorization_basic</pre></blockquote><a name="INDEX-2493" /><a name="INDEX-2494" /><a name="INDEX-2495" /></div>
</div>
<a name="perlnut2-CHP-20-SECT-3.4" /><div class="sect2">
<h3 class="sect2">20.3.4. HTTP::Status</h3>

<p><a name="INDEX-2496" /><a name="INDEX-2497" />This
module provides methods to determine the type of a response code. It
also exports a list of mnemonics that can be used by the programmer
to refer to a status code.
</p>

<p>The following methods are used on response objects:</p>

<dl>
<dt><b><tt class="literal">is_info</tt></b></dt>
<dd>
<a name="INDEX-2498" />Returns true when the response code is
100-199. 
</p>
</dd>


<dt><b><tt class="literal">is_success</tt></b></dt>
<dd>
<a name="INDEX-2499" />Returns true when the response code is
200-299. 
</p>
</dd>


<dt><b><tt class="literal">is_redirect</tt></b></dt>
<dd>
<a name="INDEX-2500" />Returns true when the response code is
300-399. 
</p>
</dd>


<dt><b><tt class="literal">is_client_error</tt></b></dt>
<dd>
<a name="INDEX-2501" />Returns true when the response
code is 400-499.
</p>
</dd>


<dt><b><tt class="literal">is_server_error</tt></b></dt>
<dd>
<a name="INDEX-2502" />Returns true when the response
code is 500-599.
</p>
</dd>