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" 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"[];F@¸[I"[]=;F@¸[I" close;F@¸[I" delete;F@¸[I" update;F@¸[;[[;[[I"create_new_id;F@¸[[U:RDoc::Context::Section[i0o;;[;0;0[@°@³I"CGI;TcRDoc::NormalClass