File: C:/Ruby27-x64/share/doc/ruby/html/CGI/Session.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class CGI::Session - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
var index_rel_prefix = "../";
</script>
<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div class="nav-section">
<h3>Table of Contents</h3>
<ul class="link-list" role="directory">
<li><a href="#class-CGI::Session-label-Overview">Overview</a>
<li><a href="#class-CGI::Session-label-Lifecycle">Lifecycle</a>
<li><a href="#class-CGI::Session-label-Setting+and+retrieving+session+data.">Setting and retrieving session data.</a>
<li><a href="#class-CGI::Session-label-Storing+session+state">Storing session state</a>
<li><a href="#class-CGI::Session-label-Maintaining+the+session+id.">Maintaining the session id.</a>
<li><a href="#class-CGI::Session-label-Examples+of+use">Examples of use</a>
<li><a href="#class-CGI::Session-label-Setting+the+user-27s+name">Setting the user's name</a>
<li><a href="#class-CGI::Session-label-Creating+a+new+session+safely">Creating a new session safely</a>
</ul>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="../Object.html">Object</a>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-i-5B-5D">#[]</a>
<li ><a href="#method-i-5B-5D-3D">#[]=</a>
<li ><a href="#method-i-close">#close</a>
<li ><a href="#method-i-create_new_id">#create_new_id</a>
<li ><a href="#method-i-delete">#delete</a>
<li ><a href="#method-i-update">#update</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-CGI::Session">
<h1 id="class-CGI::Session" class="class">
class CGI::Session
</h1>
<section class="description">
<h2 id="class-CGI::Session-label-Overview">Overview<span><a href="#class-CGI::Session-label-Overview">¶</a> <a href="#top">↑</a></span></h2>
<p>This file provides the <a href="Session.html"><code>CGI::Session</code></a> class, which provides session support for <a href="../CGI.html"><code>CGI</code></a> scripts. A session is a sequence of HTTP requests and responses linked together and associated with a single client. Information associated with the session is stored on the server between requests. A session id is passed between client and server with every request and response, transparently to the user. This adds state information to the otherwise stateless HTTP request/response protocol.</p>
<h2 id="class-CGI::Session-label-Lifecycle">Lifecycle<span><a href="#class-CGI::Session-label-Lifecycle">¶</a> <a href="#top">↑</a></span></h2>
<p>A <a href="Session.html"><code>CGI::Session</code></a> instance is created from a <a href="../CGI.html"><code>CGI</code></a> object. By default, this <a href="Session.html"><code>CGI::Session</code></a> instance will start a new session if none currently exists, or continue the current session for this client if one does exist. The <code>new_session</code> option can be used to either always or never create a new session. See new() for more details.</p>
<p><a href="Session.html#method-i-delete"><code>delete()</code></a> deletes a session from session storage. It does not however remove the session id from the client. If the client makes another request with the same id, the effect will be to start a new session with the old session's id.</p>
<h2 id="class-CGI::Session-label-Setting+and+retrieving+session+data.">Setting and retrieving session data.<span><a href="#class-CGI::Session-label-Setting+and+retrieving+session+data.">¶</a> <a href="#top">↑</a></span></h2>
<p>The <a href="Session.html"><code>Session</code></a> class associates data with a session as key-value pairs. This data can be set and retrieved by indexing the <a href="Session.html"><code>Session</code></a> instance using '[]', much the same as hashes (although other hash methods are not supported).</p>
<p>When session processing has been completed for a request, the session should be closed using the close() method. This will store the session's state to persistent storage. If you want to store the session's state to persistent storage without finishing session processing for this request, call the update() method.</p>
<h2 id="class-CGI::Session-label-Storing+session+state">Storing session state<span><a href="#class-CGI::Session-label-Storing+session+state">¶</a> <a href="#top">↑</a></span></h2>
<p>The caller can specify what form of storage to use for the session's data with the <code>database_manager</code> option to <a href="Session.html#method-c-new"><code>CGI::Session::new</code></a>. The following storage classes are provided as part of the standard library:</p>
<dl class="rdoc-list note-list"><dt><a href="Session/FileStore.html"><code>CGI::Session::FileStore</code></a>
<dd>
<p>stores data as plain text in a flat file. Only works with <a href="../String.html"><code>String</code></a> data. This is the default storage type.</p>
</dd><dt><a href="Session/MemoryStore.html"><code>CGI::Session::MemoryStore</code></a>
<dd>
<p>stores data in an in-memory hash. The data only persists for as long as the current Ruby interpreter instance does.</p>
</dd><dt><a href="Session/PStore.html"><code>CGI::Session::PStore</code></a>
<dd>
<p>stores data in Marshalled format. Provided by cgi/session/pstore.rb. Supports data of any type, and provides file-locking and transaction support.</p>
</dd></dl>
<p>Custom storage types can also be created by defining a class with the following methods:</p>
<pre class="ruby"><span class="ruby-identifier">new</span>(<span class="ruby-identifier">session</span>, <span class="ruby-identifier">options</span>)
<span class="ruby-identifier">restore</span> <span class="ruby-comment"># returns hash of session data.</span>
<span class="ruby-identifier">update</span>
<span class="ruby-identifier">close</span>
<span class="ruby-identifier">delete</span>
</pre>
<p>Changing storage type mid-session does not work. Note in particular that by default the <a href="Session/FileStore.html"><code>FileStore</code></a> and <a href="Session/PStore.html"><code>PStore</code></a> session data files have the same name. If your application switches from one to the other without making sure that filenames will be different and clients still have old sessions lying around in cookies, then things will break nastily!</p>
<h2 id="class-CGI::Session-label-Maintaining+the+session+id.">Maintaining the session id.<span><a href="#class-CGI::Session-label-Maintaining+the+session+id.">¶</a> <a href="#top">↑</a></span></h2>
<p>Most session state is maintained on the server. However, a session id must be passed backwards and forwards between client and server to maintain a reference to this session state.</p>
<p>The simplest way to do this is via cookies. The <a href="Session.html"><code>CGI::Session</code></a> class provides transparent support for session id communication via cookies if the client has cookies enabled.</p>
<p>If the client has cookies disabled, the session id must be included as a parameter of all requests sent by the client to the server. The <a href="Session.html"><code>CGI::Session</code></a> class in conjunction with the <a href="../CGI.html"><code>CGI</code></a> class will transparently add the session id as a hidden input field to all forms generated using the CGI#form() HTML generation method. No built-in support is provided for other mechanisms, such as URL re-writing. The caller is responsible for extracting the session id from the <a href="Session.html#attribute-i-session_id"><code>session_id</code></a> attribute and manually encoding it in URLs and adding it as a hidden input to HTML forms created by other mechanisms. Also, session expiry is not automatically handled.</p>
<h2 id="class-CGI::Session-label-Examples+of+use">Examples of use<span><a href="#class-CGI::Session-label-Examples+of+use">¶</a> <a href="#top">↑</a></span></h2>
<h3 id="class-CGI::Session-label-Setting+the+user-27s+name">Setting the user's name<span><a href="#class-CGI::Session-label-Setting+the+user-27s+name">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'cgi'</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">'cgi/session'</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">'cgi/session/pstore'</span> <span class="ruby-comment"># provides CGI::Session::PStore</span>
<span class="ruby-identifier">cgi</span> = <span class="ruby-constant">CGI</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"html4"</span>)
<span class="ruby-identifier">session</span> = <span class="ruby-constant">CGI</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">cgi</span>,
<span class="ruby-string">'database_manager'</span> <span class="ruby-operator">=></span> <span class="ruby-constant">CGI</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span><span class="ruby-operator">::</span><span class="ruby-constant">PStore</span>, <span class="ruby-comment"># use PStore</span>
<span class="ruby-string">'session_key'</span> <span class="ruby-operator">=></span> <span class="ruby-string">'_rb_sess_id'</span>, <span class="ruby-comment"># custom session key</span>
<span class="ruby-string">'session_expires'</span> <span class="ruby-operator">=></span> <span class="ruby-constant">Time</span>.<span class="ruby-identifier">now</span> <span class="ruby-operator">+</span> <span class="ruby-value">30</span> <span class="ruby-operator">*</span> <span class="ruby-value">60</span>, <span class="ruby-comment"># 30 minute timeout</span>
<span class="ruby-string">'prefix'</span> <span class="ruby-operator">=></span> <span class="ruby-string">'pstore_sid_'</span>) <span class="ruby-comment"># PStore option</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">cgi</span>.<span class="ruby-identifier">has_key?</span>(<span class="ruby-string">'user_name'</span>) <span class="ruby-keyword">and</span> <span class="ruby-identifier">cgi</span>[<span class="ruby-string">'user_name'</span>] <span class="ruby-operator">!=</span> <span class="ruby-string">''</span>
<span class="ruby-comment"># coerce to String: cgi[] returns the</span>
<span class="ruby-comment"># string-like CGI::QueryExtension::Value</span>
<span class="ruby-identifier">session</span>[<span class="ruby-string">'user_name'</span>] = <span class="ruby-identifier">cgi</span>[<span class="ruby-string">'user_name'</span>].<span class="ruby-identifier">to_s</span>
<span class="ruby-keyword">elsif</span> <span class="ruby-operator">!</span><span class="ruby-identifier">session</span>[<span class="ruby-string">'user_name'</span>]
<span class="ruby-identifier">session</span>[<span class="ruby-string">'user_name'</span>] = <span class="ruby-string">"guest"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">session</span>.<span class="ruby-identifier">close</span>
</pre>
<h3 id="class-CGI::Session-label-Creating+a+new+session+safely">Creating a new session safely<span><a href="#class-CGI::Session-label-Creating+a+new+session+safely">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'cgi'</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">'cgi/session'</span>
<span class="ruby-identifier">cgi</span> = <span class="ruby-constant">CGI</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"html4"</span>)
<span class="ruby-comment"># We make sure to delete an old session if one exists,</span>
<span class="ruby-comment"># not just to free resources, but to prevent the session</span>
<span class="ruby-comment"># from being maliciously hijacked later on.</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-identifier">session</span> = <span class="ruby-constant">CGI</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">cgi</span>, <span class="ruby-string">'new_session'</span> <span class="ruby-operator">=></span> <span class="ruby-keyword">false</span>)
<span class="ruby-identifier">session</span>.<span class="ruby-identifier">delete</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">ArgumentError</span> <span class="ruby-comment"># if no old session</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">session</span> = <span class="ruby-constant">CGI</span><span class="ruby-operator">::</span><span class="ruby-constant">Session</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">cgi</span>, <span class="ruby-string">'new_session'</span> <span class="ruby-operator">=></span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">session</span>.<span class="ruby-identifier">close</span>
</pre>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="attribute-method-details" class="method-section">
<header>
<h3>Attributes</h3>
</header>
<div id="attribute-i-new_session" class="method-detail">
<div class="method-heading attribute-method-heading">
<span class="method-name">new_session</span><span
class="attribute-access-type">[R]</span>
</div>
<div class="method-description">
<p>The id of this session.</p>
</div>
</div>
<div id="attribute-i-session_id" class="method-detail">
<div class="method-heading attribute-method-heading">
<span class="method-name">session_id</span><span
class="attribute-access-type">[R]</span>
</div>
<div class="method-description">
<p>The id of this session.</p>
</div>
</div>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-name">new</span><span
class="method-args">(request, option={})</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Create a new <a href="Session.html"><code>CGI::Session</code></a> object for <code>request</code>.</p>
<p><code>request</code> is an instance of the <code>CGI</code> class (see cgi.rb). <code>option</code> is a hash of options for initialising this <a href="Session.html"><code>CGI::Session</code></a> instance. The following options are recognised:</p>
<dl class="rdoc-list note-list"><dt>session_key
<dd>
<p>the parameter name used for the session id. Defaults to '_session_id'.</p>
</dd><dt><a href="Session.html#attribute-i-session_id"><code>session_id</code></a>
<dd>
<p>the session id to use. If not provided, then it is retrieved from the <code>session_key</code> parameter of the request, or automatically generated for a new session.</p>
</dd><dt><a href="Session.html#attribute-i-new_session"><code>new_session</code></a>
<dd>
<p>if true, force creation of a new session. If not set, a new session is only created if none currently exists. If false, a new session is never created, and if none currently exists and the <code>session_id</code> option is not set, an <a href="../ArgumentError.html"><code>ArgumentError</code></a> is raised.</p>
</dd><dt>database_manager
<dd>
<p>the name of the class providing storage facilities for session state persistence. Built-in support is provided for <code>FileStore</code> (the default), <code>MemoryStore</code>, and <code>PStore</code> (from cgi/session/pstore.rb). See the documentation for these classes for more details.</p>
</dd></dl>
<p>The following options are also recognised, but only apply if the session id is stored in a cookie.</p>
<dl class="rdoc-list note-list"><dt>session_expires
<dd>
<p>the time the current session expires, as a <code>Time</code> object. If not set, the session will terminate when the user's browser is closed.</p>
</dd><dt>session_domain
<dd>
<p>the hostname domain for which this session is valid. If not set, defaults to the hostname of the server.</p>
</dd><dt>session_secure
<dd>
<p>if <code>true</code>, this session will only work over HTTPS.</p>
</dd><dt>session_path
<dd>
<p>the path for which this session applies. Defaults to the directory of the <a href="../CGI.html"><code>CGI</code></a> script.</p>
</dd></dl>
<p><code>option</code> is also passed on to the session storage class initializer; see the documentation for each session storage class for the options they support.</p>
<p>The retrieved or created session is automatically added to <code>request</code> as a cookie, and also to its <code>output_hidden</code> table, which is used to add hidden input elements to forms.</p>
<p><strong>WARNING</strong> the <code>output_hidden</code> fields are surrounded by a <fieldset> tag in HTML 4 generation, which is <em>not</em> invisible on many browsers; you may wish to disable the use of fieldsets with code similar to the following (see <a href="http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-list/37805">blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-list/37805</a>)</p>
<pre class="ruby"><span class="ruby-identifier">cgi</span> = <span class="ruby-constant">CGI</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"html4"</span>)
<span class="ruby-keyword">class</span> <span class="ruby-operator"><<</span> <span class="ruby-identifier">cgi</span>
<span class="ruby-identifier">undef_method</span> <span class="ruby-value">:fieldset</span>
<span class="ruby-keyword">end</span>
</pre>
<div class="method-source-code" id="new-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 248</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">initialize</span>(<span class="ruby-identifier">request</span>, <span class="ruby-identifier">option</span>={})
<span class="ruby-ivar">@new_session</span> = <span class="ruby-keyword">false</span>
<span class="ruby-identifier">session_key</span> = <span class="ruby-identifier">option</span>[<span class="ruby-string">'session_key'</span>] <span class="ruby-operator">||</span> <span class="ruby-string">'_session_id'</span>
<span class="ruby-identifier">session_id</span> = <span class="ruby-identifier">option</span>[<span class="ruby-string">'session_id'</span>]
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">session_id</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'new_session'</span>]
<span class="ruby-identifier">session_id</span> = <span class="ruby-identifier">create_new_id</span>
<span class="ruby-ivar">@new_session</span> = <span class="ruby-keyword">true</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">session_id</span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">request</span>.<span class="ruby-identifier">key?</span>(<span class="ruby-identifier">session_key</span>)
<span class="ruby-identifier">session_id</span> = <span class="ruby-identifier">request</span>[<span class="ruby-identifier">session_key</span>]
<span class="ruby-identifier">session_id</span> = <span class="ruby-identifier">session_id</span>.<span class="ruby-identifier">read</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">session_id</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value">:read</span>)
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">session_id</span>
<span class="ruby-identifier">session_id</span>, = <span class="ruby-identifier">request</span>.<span class="ruby-identifier">cookies</span>[<span class="ruby-identifier">session_key</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">session_id</span>
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">option</span>.<span class="ruby-identifier">fetch</span>(<span class="ruby-string">'new_session'</span>, <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-string">"session_key `%s' should be supplied"</span><span class="ruby-operator">%</span><span class="ruby-identifier">session_key</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">session_id</span> = <span class="ruby-identifier">create_new_id</span>
<span class="ruby-ivar">@new_session</span> = <span class="ruby-keyword">true</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-ivar">@session_id</span> = <span class="ruby-identifier">session_id</span>
<span class="ruby-identifier">dbman</span> = <span class="ruby-identifier">option</span>[<span class="ruby-string">'database_manager'</span>] <span class="ruby-operator">||</span> <span class="ruby-constant">FileStore</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-ivar">@dbman</span> = <span class="ruby-identifier">dbman</span><span class="ruby-operator">::</span><span class="ruby-identifier">new</span>(<span class="ruby-keyword">self</span>, <span class="ruby-identifier">option</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">NoSession</span>
<span class="ruby-keyword">unless</span> <span class="ruby-identifier">option</span>.<span class="ruby-identifier">fetch</span>(<span class="ruby-string">'new_session'</span>, <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">raise</span> <span class="ruby-constant">ArgumentError</span>, <span class="ruby-string">"invalid session_id `%s'"</span><span class="ruby-operator">%</span><span class="ruby-identifier">session_id</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">session_id</span> = <span class="ruby-ivar">@session_id</span> = <span class="ruby-identifier">create_new_id</span> <span class="ruby-keyword">unless</span> <span class="ruby-identifier">session_id</span>
<span class="ruby-ivar">@new_session</span>=<span class="ruby-keyword">true</span>
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">request</span>.<span class="ruby-identifier">instance_eval</span> <span class="ruby-keyword">do</span>
<span class="ruby-ivar">@output_hidden</span> = {<span class="ruby-identifier">session_key</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">session_id</span>} <span class="ruby-keyword">unless</span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'no_hidden'</span>]
<span class="ruby-ivar">@output_cookies</span> = [
<span class="ruby-constant">Cookie</span><span class="ruby-operator">::</span><span class="ruby-identifier">new</span>(<span class="ruby-string">"name"</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">session_key</span>,
<span class="ruby-string">"value"</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">session_id</span>,
<span class="ruby-string">"expires"</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'session_expires'</span>],
<span class="ruby-string">"domain"</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'session_domain'</span>],
<span class="ruby-string">"secure"</span> <span class="ruby-operator">=></span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'session_secure'</span>],
<span class="ruby-string">"path"</span> <span class="ruby-operator">=></span>
<span class="ruby-keyword">if</span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'session_path'</span>]
<span class="ruby-identifier">option</span>[<span class="ruby-string">'session_path'</span>]
<span class="ruby-keyword">elsif</span> <span class="ruby-constant">ENV</span>[<span class="ruby-string">"SCRIPT_NAME"</span>]
<span class="ruby-constant">File</span><span class="ruby-operator">::</span><span class="ruby-identifier">dirname</span>(<span class="ruby-constant">ENV</span>[<span class="ruby-string">"SCRIPT_NAME"</span>])
<span class="ruby-keyword">else</span>
<span class="ruby-string">""</span>
<span class="ruby-keyword">end</span>)
] <span class="ruby-keyword">unless</span> <span class="ruby-identifier">option</span>[<span class="ruby-string">'no_cookies'</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-ivar">@dbprot</span> = [<span class="ruby-ivar">@dbman</span>]
<span class="ruby-constant">ObjectSpace</span><span class="ruby-operator">::</span><span class="ruby-identifier">define_finalizer</span>(<span class="ruby-keyword">self</span>, <span class="ruby-constant">Session</span><span class="ruby-operator">::</span><span class="ruby-identifier">callback</span>(<span class="ruby-ivar">@dbprot</span>))
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-5B-5D" class="method-detail ">
<div class="method-heading">
<span class="method-name">[]</span><span
class="method-args">(key)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Retrieve the session data for key <code>key</code>.</p>
<div class="method-source-code" id="5B-5D-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 309</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">[]</span>(<span class="ruby-identifier">key</span>)
<span class="ruby-ivar">@data</span> <span class="ruby-operator">||=</span> <span class="ruby-ivar">@dbman</span>.<span class="ruby-identifier">restore</span>
<span class="ruby-ivar">@data</span>[<span class="ruby-identifier">key</span>]
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-5B-5D-3D" class="method-detail ">
<div class="method-heading">
<span class="method-name">[]=</span><span
class="method-args">(key, val)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p><a href="../Set.html"><code>Set</code></a> the session data for key <code>key</code>.</p>
<div class="method-source-code" id="5B-5D-3D-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 315</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">[]=</span>(<span class="ruby-identifier">key</span>, <span class="ruby-identifier">val</span>)
<span class="ruby-ivar">@write_lock</span> <span class="ruby-operator">||=</span> <span class="ruby-keyword">true</span>
<span class="ruby-ivar">@data</span> <span class="ruby-operator">||=</span> <span class="ruby-ivar">@dbman</span>.<span class="ruby-identifier">restore</span>
<span class="ruby-ivar">@data</span>[<span class="ruby-identifier">key</span>] = <span class="ruby-identifier">val</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-close" class="method-detail ">
<div class="method-heading">
<span class="method-name">close</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Store session data on the server and close the session storage. For some session storage types, this is a no-op.</p>
<div class="method-source-code" id="close-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 329</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">close</span>
<span class="ruby-ivar">@dbman</span>.<span class="ruby-identifier">close</span>
<span class="ruby-ivar">@dbprot</span>.<span class="ruby-identifier">clear</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-delete" class="method-detail ">
<div class="method-heading">
<span class="method-name">delete</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Delete the session from storage. Also closes the storage.</p>
<p>Note that the session's data is <em>not</em> automatically deleted upon the session expiring.</p>
<div class="method-source-code" id="delete-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 338</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">delete</span>
<span class="ruby-ivar">@dbman</span>.<span class="ruby-identifier">delete</span>
<span class="ruby-ivar">@dbprot</span>.<span class="ruby-identifier">clear</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-update" class="method-detail ">
<div class="method-heading">
<span class="method-name">update</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Store session data on the server. For some session storage types, this is a no-op.</p>
<div class="method-source-code" id="update-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 323</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">update</span>
<span class="ruby-ivar">@dbman</span>.<span class="ruby-identifier">update</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
<section id="private-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Private Instance Methods</h3>
</header>
<div id="method-i-create_new_id" class="method-detail ">
<div class="method-heading">
<span class="method-name">create_new_id</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Create a new session id.</p>
<p>The session id is a secure random number by <a href="../SecureRandom.html"><code>SecureRandom</code></a> if possible, otherwise an SHA512 hash based upon the time, a random number, and a constant string. This routine is used internally for automatically generated session ids.</p>
<div class="method-source-code" id="create_new_id-source">
<pre><span class="ruby-comment"># File lib/cgi/session.rb, line 171</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">create_new_id</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">'securerandom'</span>
<span class="ruby-keyword">begin</span>
<span class="ruby-comment"># by OpenSSL, or system provided entropy pool</span>
<span class="ruby-identifier">session_id</span> = <span class="ruby-constant">SecureRandom</span>.<span class="ruby-identifier">hex</span>(<span class="ruby-value">16</span>)
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">NotImplementedError</span>
<span class="ruby-comment"># never happens on modern systems</span>
<span class="ruby-identifier">require</span> <span class="ruby-string">'digest'</span>
<span class="ruby-identifier">d</span> = <span class="ruby-constant">Digest</span>(<span class="ruby-string">'SHA512'</span>).<span class="ruby-identifier">new</span>
<span class="ruby-identifier">now</span> = <span class="ruby-constant">Time</span><span class="ruby-operator">::</span><span class="ruby-identifier">now</span>
<span class="ruby-identifier">d</span>.<span class="ruby-identifier">update</span>(<span class="ruby-identifier">now</span>.<span class="ruby-identifier">to_s</span>)
<span class="ruby-identifier">d</span>.<span class="ruby-identifier">update</span>(<span class="ruby-constant">String</span>(<span class="ruby-identifier">now</span>.<span class="ruby-identifier">usec</span>))
<span class="ruby-identifier">d</span>.<span class="ruby-identifier">update</span>(<span class="ruby-constant">String</span>(<span class="ruby-identifier">rand</span>(<span class="ruby-value">0</span>)))
<span class="ruby-identifier">d</span>.<span class="ruby-identifier">update</span>(<span class="ruby-constant">String</span>(<span class="ruby-identifier">$$</span>))
<span class="ruby-identifier">d</span>.<span class="ruby-identifier">update</span>(<span class="ruby-string">'foobar'</span>)
<span class="ruby-identifier">session_id</span> = <span class="ruby-identifier">d</span>.<span class="ruby-identifier">hexdigest</span>[<span class="ruby-value">0</span>, <span class="ruby-value">32</span>]
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">session_id</span>
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>