shibsp/handler/LogoutHandler.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibsp/handler/LogoutHandler.h
  19  *
  20  * Base class for logout-related handlers.
  21  */
  22
  23 #ifndef __shibsp_logout_h__
  24 #define __shibsp_logout_h__
  25
  26 #include <shibsp/SPRequest.h>
  27 #include <shibsp/handler/RemotedHandler.h>
  28
  29 namespace shibsp {
  30
  31     /**
  32      * Base class for logout-related handlers.
  33      */
  34     class SHIBSP_API LogoutHandler : public RemotedHandler
  35     {
  36     public:
  37         virtual ~LogoutHandler() {}
  38
  39         /**
  40          * The base method will iteratively attempt front-channel notification
  41          * of logout of the current session, and after the final round trip will
  42          * perform back-channel notification. Nothing will be done unless the
  43          * handler detects that it is the "top" level logout handler.
  44          * If the method returns false, then the specialized class should perform
  45          * its work assuming that the notifications are completed.
  46          *
  47          * Note that the current session is NOT removed from the cache.
  48          *
  49          * @param request   SP request context
  50          * @param isHandler true iff executing in the context of a direct handler invocation
  51          * @return  a pair containing a "request completed" indicator and a server-specific response code
  52          */
  53         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  54
  55         /**
  56          * A remoted procedure that will perform any necessary back-channel
  57          * notifications. The input structure must contain an "application_id" member,
  58          * and a "sessions" list containing the session keys, along with an integer
  59          * member called "notify" with a value of 1.
  60          *
  61          * @param in    incoming DDF message
  62          * @param out   stream to write outgoing DDF message to
  63          */
  64         void receive(DDF& in, std::ostream& out);
  65
  66     protected:
  67         LogoutHandler() : m_initiator(true) {}
  68
  69         /** Flag indicating whether the subclass is acting as a LogoutInitiator. */
  70         bool m_initiator;
  71
  72         /**
  73          * Perform front-channel logout notifications for an Application.
  74          *
  75          * If no sessions are supplied directly, the request object's "sessions" query string
  76          * parameter will be used.
  77          *
  78          * @param application   the Application to notify
  79          * @param request       last request from browser
  80          * @param response      response to use for next notification
  81          * @param params        map of query string parameters to preserve across notifications, optionally with initial values
  82          * @return  indicator of a completed response along with the status code to return from the handler
  83          */
  84         std::pair<bool,long> notifyFrontChannel(
  85             const Application& application,
  86             const xmltooling::HTTPRequest& request,
  87             xmltooling::HTTPResponse& response,
  88             const std::map<std::string,std::string>* params=NULL
  89             ) const;
  90
  91         /**
  92          * Sends a response template to the user agent informing it of the results of a logout attempt.
  93          *
  94          * @param application   the Application to use in determining the logout template
  95          * @param response      the HTTP response to use
  96          * @param local         true iff the logout operation was local to the SP, false iff global
  97          * @param status        optional logoutStatus key value to add to template
  98          */
  99         std::pair<bool,long> sendLogoutPage(
 100             const Application& application, xmltooling::HTTPResponse& response, bool local=true, const char* status=NULL
 101             ) const;
 102
 103         /**
 104          * Perform back-channel logout notifications for an Application.
 105          *
 106          * @param application   the Application to notify
 107          * @param sessions      array of session keys being logged out
 108          * @return  true iff all notifications succeeded
 109          */
 110         bool notifyBackChannel(const Application& application, const std::vector<std::string>& sessions) const;
 111     };
 112
 113 };
 114
 115 #endif /* __shibsp_logout_h__ */