NAME

       Sympa::WWW::Session - Web session

SYNOPSIS

         use Sympa::WWW::Session;

         my $session = Sympa::WWW::Session->new($robot,
             {cookie => Sympa::WWW::Session::get_session_cookie($ENV{'HTTP_COOKIE'})}
         );
         $session->renew();
         $session->store();

   Confirmation
         $session->confirm_action($action, 'init');

         sub do_myaction {

             # Validate arguments...

             $param->{arg} = $arg;
             my $next_action = $session->confirm_action($action, $response,
                 $arg, $previous_action);
             return $next_action unless $next_action eq '1';

             # Process action...

         }

DESCRIPTION

       Sympa::WWW::Session provides web session for Sympa web interface.  HTTP cookie is required
       to determine users.  Session store is used to keep users' personal data.

   Methods
       new ( $robot, { [ cookie => $cookie ], ... } )
           Constructor.  Creates new instance and loads user data from session store.

           Parameters:

           $robot
               Context of the session.

           { cookie => $cookie }
               HTTP cookie.

           Returns:

           A new instance.

       as_hashref ( )
           Instance method.  Casts the instance to hashref.

           Parameters:

           None.

           Returns:

           A hashref including attributes of instance (see "Attributes").

       confirm_action ( $action, $response, [ arg => $arg, ] [ previous_action =>
       $previous_action ] )
           Instance method.  Check if action has been confirmed.

           Confirmation follows two steps:

           1.  The method is called with no (undefined) response.  The action, hash of argument
               and previous_action are stored into session store.  And then this method returns
               'confirm_action'.

           2.  The method is called with 'confirm' or other true value as response.  If action
               and hash of argument match with those in session store, and:

               •   If 'confirm' is given, returns 1.

               •   If other true value is given, returns previous action stored in session store
                   (previous_action given in argument is ignored).

               In both cases session store is cleared.

           Anytime when the action submitted by user is determined, This method may be called
           with response as 'init'.  In this case, if action doesn't match with that in session
           store, session store will be cleared.

           Parameters:

           $action
               Action to be checked.

           $response
               Response from user: 'init', false value (not yet checked), 'confirm' and others
               (cancelled).  This may typically be given by user using "response_action"
               parameter.

           arg => $arg
               Argument(s) of action.

           previous_action => $previous_action
               The action users will be redirected when action is confirmed.  This may typically
               given by user using "previous_action" parameter.

       is_anonymous ( )
           Instance method.  TBD.

       renew ( )
           Instance method.  Renews the session.  Updates internal session ID and HTTP cookie.

       store ( )
           Instance method.  Stores session into session store.

   Functions
       check_cookie_extern ( )
           Function.  Deprecated.

       decrypt_session_id ( )
           Function.  Deprecated.

       encrypt_session_id ( )
           Function.  Deprecated.

       list_sessions ( )
           Function.  TBD.

       purge_old_sessions ( )
           Function.  Deprecated.

       set_cookie ( $cookie_domain, $expires, [ $use_ssl ] )
           Instance method.  TBD.

       set_cookie_extern ( $cookie_domain, [ $use_ssl ] )
           Instance method.  Deprecated.

   Attributes
       TBD.

SEE ALSO

       Sympa::DatabaseManager.

HISTORY

       SympaSession appeared on Sympa 5.4a3.

       It was renamed to Sympa::Session on Sympa 6.2a.41, then Sympa::WWW::Session on Sympa
       6.2.26.

       "confirm_action" method was added on Sympa 6.2.17.