ch20_03.htm

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

object <tt class="literal">$</tt><em class="replaceable"><tt>response</tt></em> for
any Set-Cookie and Set-Cookie2 headers and stores the cookie
information in the cookie jar.
</p></div>

<a name="INDEX-2526" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>load</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;load( [<em class="replaceable">file</em>] )
</pre><p><a name="INDEX-2526" />Loads cookie information into the
cookie jar from the file specified during construction (default) or
from the named <em class="replaceable"><tt>file</tt></em>. The file must be in
the format produced by the <tt class="literal">save</tt> method.
</p></div>

<a name="INDEX-2527" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>revert</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;revert
</pre><p><a name="INDEX-2527" />Restores the cookie jar to its
state before the last save.
</p></div>

<a name="INDEX-2528" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>save</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;save( [<em class="replaceable">file</em>] )
</pre><p><a name="INDEX-2528" />Saves the state of the cookie jar to
the file specified during construction (by default) or to the named
<em class="replaceable"><tt>file</tt></em>. The cookies are saved in a special
LWP format as Set-Cookie3 header lines. This format is not compatible
with the standard Set-Cookie and Set-Cookie2 headers, but you are not
likely to use this file to set new cookies in response headers.
</p></div>

<a name="INDEX-2529" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>set_cookie</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;set_cookie(<em class="replaceable">version</em>, <em class="replaceable">key</em>, <em class="replaceable">val</em>, <em class="replaceable">path</em>, <em class="replaceable">domain</em>, <em class="replaceable">port</em>, <em class="replaceable">path_spec</em>, <em class="replaceable">secure</em>, <em class="replaceable">maxages</em>, <em class="replaceable">discard</em>, \%<em class="replaceable">misc</em>)
</pre><p><a name="INDEX-2529" />Sets a cookie in the cookie
jar with the information given in the arguments. The number and order
of arguments represent the structure of elements in the Set-Cookie3
header lines used to save the cookies in a file.
</p><dl>
<dt><i><em class="replaceable"><tt>version</tt></em></i></dt>
<dd>
A string containing the cookie-spec version number.</p>
</dd>


<dt><i><em class="replaceable"><tt>key</tt></em></i></dt>
<dd>
The name of the cookie.</p>
</dd>


<dt><i><em class="replaceable"><tt>val</tt></em></i></dt>
<dd>
The value of the cookie.</p>
</dd>


<dt><i><em class="replaceable"><tt>path</tt></em></i></dt>
<dd>
The pathname of the URL for which the cookie is set.</p>
</dd>


<dt><i><em class="replaceable"><tt>domain</tt></em></i></dt>
<dd>
The domain name for which the cookie is set.</p>
</dd>


<dt><i><em class="replaceable"><tt>port</tt></em></i></dt>
<dd>
The port number of the URL for which the cookie is set.</p>
</dd>


<dt><i><em class="replaceable"><tt>path_spec</tt></em></i></dt>
<dd>
A Boolean value indicating if the cookie is valid for the specific
URL path or all the URLs in the domain. The path is used if true;
otherwise, the cookie is valid for the entire domain.
</p>
</dd>


<dt><i><em class="replaceable"><tt>secure</tt></em></i></dt>
<dd>
A Boolean value indicating that the cookie should only be sent over a
secure connection for true, or over any connection for false.
</p>
</dd>


<dt><i><em class="replaceable"><tt>maxage</tt></em></i></dt>
<dd>
The number of seconds that the cookie will be valid from the time it
was received. Adding the <em class="replaceable"><tt>maxage</tt></em> to the
current time will yield a value that can be used for an expiration
date.
</p>
</dd>


<dt><i><em class="replaceable"><tt>discard</tt></em></i></dt>
<dd>
A Boolean value indicating that the cookie should not be sent in any
future requests and should be discarded upon saving the cookie jar,
unless the <tt class="literal">ignore_discard</tt> parameter was set to
true in the constructor.
</p>
</dd>


<dt><b><tt class="literal">%</tt><em class="replaceable">misc</em></b></dt>
<dd>
The final argument is a reference to a hash,
<tt class="literal">%</tt><em class="replaceable"><tt>misc</tt></em>, that contains
any additional parameters from the Set-Cookie headers such as Comment
and URLComment, in key/value pairs.
</p>
</dd>

</dl></div>

<a name="INDEX-2530" /><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">cjar</em>-&gt;scan( \&amp;<em class="replaceable">callback</em> )
</pre><p><a name="INDEX-2530" />Invokes the
<em class="emphasis">callback</em> subroutine for each cookie in the
cookie jar. The subroutine is called with the same arguments given to
the <tt class="literal">save</tt> method, described above. Any undefined
arguments will be given the value <tt class="literal">undef</tt>.
</p></div>
<a name="perlnut2-CHP-20-SECT-3.6.1" /><div class="sect3">
<h3 class="sect3">20.3.6.1. HTTP::Cookies::Netscape</h3>

<p><a name="INDEX-2531" /><a name="INDEX-2532" /><a name="INDEX-2533" />The
HTTP::Cookies class contains one subclass that supports
Netscape-style cookies within a cookie jar object. Netscape-style
cookies were defined in the original cookie specification for
Navigator 1.1, which outlined the syntax for the Cookie and
Set-Cookie HTTP headers. Netscape cookie headers are different from
the newer Set-Cookie2-style cookies in that they
don't support as many additional parameters when a
cookie is set. The Cookie header also does not use a version-number
attribute. Many browsers and servers still use the original Netscape
cookies, and the Netscape subclass of HTTP::Cookies can be used to
support this style.
</p>

<p><a name="INDEX-2534" />The <tt class="literal">new</tt> constructor
for this subclass creates a Netscape-compatible cookie jar object
like this:
</p>

<blockquote><pre class="code">$njar = HTTP::Cookies::Netscape-&gt;new(
                  File     =&gt; "$ENV{HOME}/.netscape/cookies",
                  AutoSave =&gt; 1 );</pre></blockquote>

<p>The methods described above can be used on this object, although many
of the parameters used in Set-Cookie2 headers will simply be lost
when cookies are saved to the cookie jar<a name="INDEX-2535" /><a name="INDEX-2536" /><a name="INDEX-2537" />. 
</p>

</div>
</div>
<a name="perlnut2-CHP-20-SECT-3.7" /><div class="sect2">
<h3 class="sect2">20.3.7. HTTP::Daemon</h3>

<p><a name="INDEX-2538" /><a name="INDEX-2539" />The
HTTP::Daemon module creates HTTP server applications. The module
provides objects based on the IO::Socket::INET class that can listen
on a socket for client requests and send server responses. The
objects implemented by the module are HTTP 1.1 servers. Client
requests are stored as HTTP::Request objects, and all the methods for
that class can be used to obtain information about the request.
HTTP::Response objects can be used to send information back to the
client.
</p>

<p><a name="INDEX-2540" />An HTTP::Daemon object is created by
using the <tt class="literal">new</tt> constructor. Since the base class
for this object is IO::Socket::INET, the parameters used in that
class's constructor are the same here. For example:
</p>

<blockquote><pre class="code">$d = HTTP::Daemon-&gt;new ( LocalAddr =&gt; 'maude.oreilly.com',
                         LocalPort =&gt; 8888,
                         Listen =&gt; 5 );</pre></blockquote>

<p>The HTTP::Daemon object is a server socket that automatically listens
for requests on the specified port (or on the default port if none is
given). When a client request is received, the object uses the
<tt class="literal">accept</tt> method to create a connection with the
client on the network.
</p>

<blockquote><pre class="code">$d = HTTP::Daemon-&gt;new;
while ( $c = $d-&gt;accept ) {
     $req = $c-&gt;get_request;
     # Process request and send response here
     }
$c = undef;   # Don't forget to close the socket</pre></blockquote>

<p><a name="INDEX-2541" />The <tt class="literal">accept</tt> method
returns a reference to a new object of the HTTP::Daemon::ClientConn
class. This class is also based on IO::Socket::INET and is used to
extract the request message and send the response and any requested
file content.
</p>

<p>The sockets created by both HTTP::Daemon and HTTP::Daemon::ClientConn
work the same way as those in IO::Socket::INET. The methods are also
the same except for some slight variations in usage. The methods for
the HTTP::Daemon classes are listed in the sections below and include
the adjusted IO::Socket::INET methods. For more detailed information
about sockets and the IO::Socket classes and methods, see <a href="ch13_01.htm">Chapter 13, "XML and Perl"</a>. 
</p>

<p>The following methods can be used on HTTP::Daemon objects.</p>


<div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>accept</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">d</em>-&gt;accept ([<em class="replaceable">pkg</em>])
</pre><p>Accepts a client request on a socket object and creates a connection
with the client. This method is the same as
<tt class="literal">IO::Socket-&gt;accept</tt>, except it will return a
reference to a new HTTP::Daemon::ClientConn object. If an argument is
given, the connection object will be created in the package named by
<em class="replaceable"><tt>pkg</tt></em>. If no connection is made before a
specified timeout, the method will return <tt class="literal">undef</tt>.
</p></div>

<a name="INDEX-2542" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>product_tokens</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">d</em>-&gt;product_tokens
</pre><p><a name="INDEX-2542" />Returns the string that the
server uses to identify itself in the Server response header.
</p></div>

<a name="INDEX-2543" /><div class="refentry"><table width="515" border="0" cellpadding="5"><tr><td align="left"><font size="+1"><b>url</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">d</em>-&gt;url