ch20_03.htm

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

<dt><b><tt class="literal">is_error</tt></b></dt>
<dd>
<a name="INDEX-2503" />Returns true when the response code is
400-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>
</dd>

</dl>

<p>HTTP::Status exports the following constant functions to use as
mnemonic substitutes for status codes. For example, you could do
something like<a name="INDEX-2504" />:
</p>

<blockquote><pre class="code">if ($rc = RC_OK) {....}</pre></blockquote>

<p>Here are the mnemonics, followed by the status codes they represent: </p>

<blockquote><pre class="code">RC_CONTINUE (100)
RC_SWITCHING_PROTOCOLS (101)
RC_OK (200)
RC_CREATED (201)
RC_ACCEPTED (202)
RC_NON_AUTHORITATIVE_INFORMATION (203)
RC_NO_CONTENT (204)
RC_RESET_CONTENT (205)
RC_PARTIAL_CONTENT (206)
RC_MULTIPLE_CHOICES (300)
RC_MOVED_PERMANENTLY (301)
RC_MOVED_TEMPORARILY (302)
RC_SEE_OTHER (303)
RC_NOT_MODIFIED (304)
RC_USE_PROXY (305)
RC_BAD_REQUEST (400)
RC_UNAUTHORIZED (401)
RC_PAYMENT_REQUIRED (402)
RC_FORBIDDEN (403)
RC_NOT_FOUND (404)
RC_METHOD_NOT_ALLOWED (405)
RC_NOT_ACCEPTABLE (406)
RC_PROXY_AUTHENTICATION_REQUIRED (407)
RC_REQUEST_TIMEOUT (408)
RC_CONFLICT (409)
RC_GONE (410)
RC_LENGTH_REQUIRED (411)
RC_PRECONDITION_FAILED (412)
RC_REQUEST_ENTITY_TOO_LARGE (413)
RC_REQUEST_URI_TOO_LARGE (414)
RC_UNSUPPORTED_MEDIA_TYPE (415)
RC_REQUEST_RANGE_NOT_SATISFIABLE (416)
RC_INTERNAL_SERVER_ERROR (500)
RC_NOT_IMPLEMENTED (501)
RC_BAD_GATEWAY (502)
RC_SERVICE_UNAVAILABLE (503)
RC_GATEWAY_TIMEOUT (504)
RC_HTTP_VERSION_NOT_SUPPORTED (505)</pre></blockquote>

</div>
<a name="perlnut2-CHP-20-SECT-3.5" /><div class="sect2">
<h3 class="sect2">20.3.5. HTTP::Date</h3><a name="INDEX-2505" /><a name="INDEX-2506" />

<p><a name="INDEX-2507" /><a name="INDEX-2508" /><a name="INDEX-2509" />The HTTP::Date module is useful when
you want to process a date string. It exports two functions that
convert date strings to and from standard time formats.
</p>



<a name="INDEX-2510" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>parse_date</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
parse_date($<em class="replaceable">str</em>)
</pre><p><a name="INDEX-2510" />Parses a date string and returns
it as a list of numerical values followed by a time zone
specification. If the date is unrecognized, then the empty list is
returned.
</p></div>

<a name="INDEX-2511" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>str2time</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
str2time(<em class="replaceable">str</em> [, <em class="replaceable">zone</em>])
</pre><p><a name="INDEX-2511" />Converts the time specified as a
string in the first parameter into the number of seconds since epoch.
This function recognizes a wide variety of formats, including RFC
1123 (standard HTTP), RFC 850, ANSI C <tt class="literal">asctime</tt>,
common log file format, Unix <em class="emphasis">ls -l</em>, and Windows
<em class="emphasis">dir</em>, among others. When a time zone is not
implicit in the first parameter, this function will use an optional
time zone specified as the second parameter, such as -0800, +0500, or
GMT. If the second parameter is omitted, and the time zone is
ambiguous, the local time zone is used.
</p></div>

<a name="INDEX-2512" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>time2iso</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
time2iso([$<em class="replaceable">time</em>])
</pre><p><a name="INDEX-2512" />Same as <tt class="literal">time2str(
)</tt>, but returns a "YYYY-MM-DD
hh:mm:ss"-formatted string representing time in the
local time zone.
</p></div>

<a name="INDEX-2513" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>time2isoz</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
time2isoz([$<em class="replaceable">time</em>])
</pre><p><a name="INDEX-2513" />Same as <tt class="literal">time2str(
)</tt>, but returns a "YYYY-MM-DD
hh:mm:ssZ"-formatted string representing Universal
Time.
</p></div>

<a name="INDEX-2514" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>time2str</b></font></td><td align="right"><i></i></td></tr></table><hr width="515" size="3" noshade="true" align="left" color="black" /><pre>
time2str([<em class="replaceable">time</em>])
</pre><p><a name="INDEX-2514" />Given the number of seconds since
machine epoch, this function generates the equivalent time as
specified in RFC 1123, which is the recommended time format used in
HTTP. When invoked with no parameter, the current time is used.
</p></div>

</div>
<a name="perlnut2-CHP-20-SECT-3.6" /><div class="sect2">
<h3 class="sect2">20.3.6. HTTP::Cookies</h3>

<p><a name="INDEX-2515" /><a name="INDEX-2516" /><a name="INDEX-2517" />HTTP
cookies provide a mechanism for preserving information about a client
or user across several different visits to a site or page. The
"cookie" is a name/value pair sent
to the client on its initial visit to a page. This cookie is stored
by the client and sent back in the request upon revisit to the same
page.
</p>

<p><a name="INDEX-2518" /><a name="INDEX-2519" />A server initializes
a cookie with the Set-Cookie header. Set-Cookie sets the name and
value of a cookie, as well as other parameters such as how long the
cookie is valid and the range of URLs to which the cookie applies.
Each cookie (a single name/value pair) is sent in its own Set-Cookie
header, so if there is more than one cookie sent to a client,
multiple Set-Cookie headers are sent in the response. Two Set-Cookie
headers may be used in server responses: Set-Cookie is defined in the
original Netscape cookie specification, and Set-Cookie2 is the
latest, IETF-defined header. Both header styles are supported by
HTTP::Cookies. The latest browsers also support both styles.
</p>

<p>If a client visits a page for which it has a valid cookie stored, the
client <a name="INDEX-2520" />sends
the cookie in the request with the Cookie header. This
header's value contains any name/value pairs that
apply to the URL. Multiple cookies are separated by semicolons in the
header.
</p>

<p>The HTTP::Cookies module is used to retrieve, return, and manage the
cookies used by an LWP::UserAgent client application. Setting cookies
from an LWP-created server requires only the coding of the proper
response headers sent by an HTTP::Daemon server application.
HTTP::Cookies is not designed to be used in setting cookies on the
server side, although you may find use for it in managing sent
cookies.
</p>

<p><a name="INDEX-2521" />The <tt class="literal">new</tt> constructor
for HTTP::Cookies creates an object called a cookie jar, which
represents a collection of saved cookies usually read from a file.
Methods on the cookie jar object allow you to add new cookies or send
cookie information in a client request to a specific URL. The
constructor may take optional parameters, as shown in the following
example:
</p>

<blockquote><pre class="code">$cjar = HTTP::Cookies-&gt;new( file =&gt; 'cookies.txt', 
                            autosave =&gt; 1,
                            ignore_discard =&gt; 0 );</pre></blockquote>

<p>The cookie jar object <tt class="literal">$cjar</tt> created here contains
any cookie information stored in the file
<em class="emphasis">cookies.txt</em>. The <tt class="literal">autosave</tt>
parameter takes a Boolean value that determines if the state of the
cookie jar is saved to the file upon destruction of the object.
<tt class="literal">ignore_discard</tt> also takes a Boolean value to
determine if cookies marked to be discarded are still saved to the
file.
</p>

<p>Cookies received by a client are added to the cookie jar with the
<tt class="literal">extract_cookies</tt> method. This method searches an
HTTP::Response object for Set-Cookie and Set-Cookie2 headers and adds
them to the cookie jar. Cookies are sent in a client request using
the <tt class="literal">add-cookie-header</tt> method. This method takes an
HTTP::Request object with the URL component already set, and if the
URL matches any entries in the cookie jar, adds the appropriate
Cookie headers to the request.
</p>

<p>These methods can be used on a cookie jar object created by
HTTP::Cookies.
</p>


<a name="INDEX-2522" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>add_cookie_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">cjar</em>-&gt;add_cookie_header($<em class="replaceable">request</em>)
</pre><p><a name="INDEX-2522" />Adds appropriate Cookie
headers to an HTTP::Request object
<tt class="literal">$</tt><em class="replaceable"><tt>request</tt></em>.
<tt class="literal">$</tt><em class="replaceable"><tt>request</tt></em> must already
be created with a valid URL address. This method will search the
cookie jar for any cookies matching the request URL. If the cookies
are valid (i.e., have not expired), they are used to create Cookie
headers and are added to the request.
</p></div>

<a name="INDEX-2523" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>as_string</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">cjar</em>-&gt;as_string([<em class="replaceable">discard</em>])
</pre><p><a name="INDEX-2523" />Returns the current contents of the
cookie jar as a string. Each cookie is output as a Set-Cookie3 header
line followed by "0". If
<em class="replaceable"><tt>discard</tt></em> is given and is true, cookies
marked to be discarded will not be output. Set-Cookie3 is a special
LWP format used to store cookie information in the save file.
</p></div>

<a name="INDEX-2524" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>clear</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">cjar</em>-&gt;clear( [<em class="replaceable">domain</em>, [<em class="replaceable">path</em>, [<em class="replaceable">key</em>] ] ])
</pre><p><a name="INDEX-2524" />Without arguments, this method
clears the entire contents of the cookie jar. Given arguments,
cookies belonging to a specific <em class="replaceable"><tt>domain</tt></em>,
<em class="replaceable"><tt>path</tt></em>, or with a name,
<em class="replaceable"><tt>key</tt></em>, will be cleared. The arguments are
ordered for increasing specificity. If only one argument is given,
all cookies for that domain will be deleted. A second argument
specifies a distinct <em class="replaceable"><tt>path</tt></em> within the
<em class="replaceable"><tt>domain</tt></em>. To remove a cookie by keyname, you
must use all three arguments.
</p></div>

<a name="INDEX-2525" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>extract_cookies</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">cjar</em>-&gt;extract_cookies($<em class="replaceable">response</em>)
</pre><p><a name="INDEX-2525" />Searches an HTTP::Response