U:RDoc::NormalClass[iI"Session:ETI"CGI::Session;TI"Object;To:RDoc::Markup::Document:@parts[o;;[/S:RDoc::Markup::Heading:
leveli:	textI"
Overview;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[
I"GThis file provides the CGI::Session class, which provides session ;TI"Hsupport for CGI scripts.  A session is a sequence of HTTP requests ;TI"Hand responses linked together and associated with a single client. ;TI"7Information associated with the session is stored ;TI"Lon the server between requests.  A session id is passed between client ;TI"?and server with every request and response, transparently ;TI"Jto the user.  This adds state information to the otherwise stateless ;TI"$HTTP request/response protocol.;T@S;	;
i;I"Lifecycle;T@o;
;[
I"HA CGI::Session instance is created from a CGI object.  By default, ;TI"Kthis CGI::Session instance will start a new session if none currently ;TI"Iexists, or continue the current session for this client if one does ;TI"Fexist.  The +new_session+ option can be used to either always or ;TI">never create a new session.  See #new() for more details.;T@o;
;[	I";#delete() deletes a session from session storage.  It ;TI"Ldoes not however remove the session id from the client.  If the client ;TI"Imakes another request with the same id, the effect will be to start ;TI"-a new session with the old session's id.;T@S;	;
i;I")Setting and retrieving session data.;T@o;
;[	I"JThe Session class associates data with a session as key-value pairs. ;TI"IThis data can be set and retrieved by indexing the Session instance ;TI"Fusing '[]', much the same as hashes (although other hash methods ;TI"are not supported).;T@o;
;[I"CWhen session processing has been completed for a request, the ;TI"Csession should be closed using the close() method.  This will ;TI"Cstore the session's state to persistent storage.  If you want ;TI"@to store the session's state to persistent storage without ;TI"Ffinishing session processing for this request, call the update() ;TI"method.;T@S;	;
i;I"Storing session state;T@o;
;[I"JThe caller can specify what form of storage to use for the session's ;TI"Hdata with the +database_manager+ option to CGI::Session::new.  The ;TI"Lfollowing storage classes are provided as part of the standard library:;T@o:RDoc::Markup::List:
@type:	NOTE:@items[o:RDoc::Markup::ListItem:@label[I"CGI::Session::FileStore;T;[o;
;[I"5stores data as plain text in a flat file.  Only ;TI"2works with String data.  This is the default ;TI"storage type.;To;;[I"CGI::Session::MemoryStore;T;[o;
;[I"1stores data in an in-memory hash.  The data ;TI"3only persists for as long as the current Ruby ;TI"interpreter instance does.;To;;[I"CGI::Session::PStore;T;[o;
;[I"4stores data in Marshalled format.  Provided by ;TI"8cgi/session/pstore.rb.  Supports data of any type, ;TI"7and provides file-locking and transaction support.;T@o;
;[I"GCustom storage types can also be created by defining a class with ;TI"the following methods:;T@o:RDoc::Markup::Verbatim;[
I"new(session, options)
;TI".restore  # returns hash of session data.
;TI"update
;TI"close
;TI"delete
;T:@format0o;
;[I"JChanging storage type mid-session does not work.  Note in particular ;TI"Jthat by default the FileStore and PStore session data files have the ;TI"Lsame name.  If your application switches from one to the other without ;TI"2making sure that filenames will be different ;TI"Gand clients still have old sessions lying around in cookies, then ;TI"things will break nastily!;T@S;	;
i;I" Maintaining the session id.;T@o;
;[I"IMost session state is maintained on the server.  However, a session ;TI"Hid must be passed backwards and forwards between client and server ;TI"3to maintain a reference to this session state.;T@o;
;[I"IThe simplest way to do this is via cookies.  The CGI::Session class ;TI"Kprovides transparent support for session id communication via cookies ;TI"'if the client has cookies enabled.;T@o;
;[I"IIf the client has cookies disabled, the session id must be included ;TI"Kas a parameter of all requests sent by the client to the server.  The ;TI"MCGI::Session class in conjunction with the CGI class will transparently ;TI"Gadd the session id as a hidden input field to all forms generated ;TI"Jusing the CGI#form() HTML generation method.  No built-in support is ;TI"Kprovided for other mechanisms, such as URL re-writing.  The caller is ;TI"Cresponsible for extracting the session id from the session_id ;TI"Jattribute and manually encoding it in URLs and adding it as a hidden ;TI"Linput to HTML forms created by other mechanisms.  Also, session expiry ;TI""is not automatically handled.;T@S;	;
i;I"Examples of use;T@S;	;
i;I"Setting the user's name;T@o;;[I"require 'cgi'
;TI"require 'cgi/session'
;TI"Frequire 'cgi/session/pstore'     # provides CGI::Session::PStore
;TI"
;TI"cgi = CGI.new("html4")
;TI"
;TI"%session = CGI::Session.new(cgi,
;TI"C    'database_manager' => CGI::Session::PStore,  # use PStore
;TI"K    'session_key' => '_rb_sess_id',              # custom session key
;TI"J    'session_expires' => Time.now + 30 * 60,     # 30 minute timeout
;TI"F    'prefix' => 'pstore_sid_')                   # PStore option
;TI"=if cgi.has_key?('user_name') and cgi['user_name'] != ''
;TI"/    # coerce to String: cgi[] returns the
;TI"2    # string-like CGI::QueryExtension::Value
;TI"6    session['user_name'] = cgi['user_name'].to_s
;TI"!elsif !session['user_name']
;TI"(    session['user_name'] = "guest"
;TI"	end
;TI"session.close
;T;0S;	;
i;I""Creating a new session safely;T@o;;[I"require 'cgi'
;TI"require 'cgi/session'
;TI"
;TI"cgi = CGI.new("html4")
;TI"
;TI"<# We make sure to delete an old session if one exists,
;TI"># not just to free resources, but to prevent the session
;TI"1# from being maliciously hijacked later on.
;TI"begin
;TI"A    session = CGI::Session.new(cgi, 'new_session' => false)
;TI"    session.delete
;TI"/rescue ArgumentError  # if no old session
;TI"	end
;TI"<session = CGI::Session.new(cgi, 'new_session' => true)
;TI"session.close;T;0:
@fileI"lib/cgi/session.rb;T:0@omit_headings_from_table_of_contents_below0o;;[;I"lib/cgi/session/pstore.rb;T;0;0;0[[
I"new_session;TI"R;T:publicFI"lib/cgi/session.rb;T[
I"session_id;T@
�;F@
�[[[[I"
class;T[[;[[I"new;T@
�[:protected[[:private[[I"
instance;T[[;[
[I"[];T@
�[I"[]=;T@
�[I"
close;T@
�[I"delete;T@
�[I"update;T@
�[;[[;[[I"create_new_id;T@
�[[U:RDoc::Context::Section[i0o;;[;0;0[@
�@
�I"CGI;TcRDoc::NormalClass