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     protected:
  37         LogoutHandler() {}
  38
  39     public:
  40         virtual ~LogoutHandler() {}
  41
  42         /**
  43          * The base method will iteratively attempt front-channel notification
  44          * of logout of the current session, and after the final round trip will
  45          * perform back-channel notification. Nothing will be done unless the
  46          * handler detects that it is the "top" level logout handler.
  47          * If the method returns false, then the specialized class should perform
  48          * its work assuming that the notifications are completed.
  49          *
  50          * Note that the current session is NOT removed from the cache.
  51          *
  52          * @param request   SP request context
  53          * @param isHandler true iff executing in the context of a direct handler invocation
  54          * @return  a pair containing a "request completed" indicator and a server-specific response code
  55          */
  56         std::pair<bool,long> run(SPRequest& request, bool isHandler=true) const;
  57
  58         /**
  59          * A remoted procedure that will perform any necessary back-channel
  60          * notifications. The input structure must contain an "application_id" member,
  61          * and a "sessions" list containing the session keys, along with an integer
  62          * member called "notify" with a value of 1.
  63          *
  64          * @param in    incoming DDF message
  65          * @param out   stream to write outgoing DDF message to
  66          */
  67         void receive(DDF& in, std::ostream& out);
  68
  69     protected:
  70         /**
  71          * Perform front-channel logout notifications for an Application.
  72          *
  73          * If no sessions are supplied directly, the request object's "sessions" query string
  74          * parameter will be used.
  75          *
  76          * @param application   the Application to notify
  77          * @param request       last request from browser
  78          * @param response      response to use for next notification
  79          * @param params        map of query string parameters to preserve across notifications, optionally with initial values
  80          * @param sessions      optional array of session keys being logged out
  81          * @return  indicator of a completed response along with the status code to return from the handler
  82          */
  83         std::pair<bool,long> notifyFrontChannel(
  84             const Application& application,
  85             const xmltooling::HTTPRequest& request,
  86             xmltooling::HTTPResponse& response,
  87             const std::map<std::string,std::string>* params=NULL,
  88             const std::vector<std::string>* sessions=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__ */