shibsp/SPRequest.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/SPRequest.h
  19  *
  20  * Interface to server request being processed
  21  */
  22
  23 #ifndef __shibsp_req_h__
  24 #define __shibsp_req_h__
  25
  26 #include <shibsp/RequestMapper.h>
  27 #include <xmltooling/io/HTTPRequest.h>
  28 #include <xmltooling/io/HTTPResponse.h>
  29
  30 namespace shibsp {
  31
  32     class SHIBSP_API Application;
  33     class SHIBSP_API ServiceProvider;
  34     class SHIBSP_API Session;
  35
  36     /**
  37      * Interface to server request being processed
  38      *
  39      * <p>To supply information from the surrounding web server environment,
  40      * a shim must be supplied in the form of this interface to adapt the
  41      * library to different proprietary server APIs.
  42      *
  43      * <p>This interface need not be threadsafe.
  44      */
  45     class SHIBSP_API SPRequest : public virtual xmltooling::HTTPRequest, public virtual xmltooling::HTTPResponse
  46     {
  47     protected:
  48         SPRequest() {}
  49     public:
  50         virtual ~SPRequest() {}
  51
  52         /**
  53          * Returns the locked ServiceProvider processing the request.
  54          *
  55          * @return reference to ServiceProvider
  56          */
  57         virtual const ServiceProvider& getServiceProvider() const=0;
  58
  59         /**
  60          * Returns RequestMapper Settings associated with the request, guaranteed
  61          * to be valid for the request's duration.
  62          *
  63          * @return copy of settings
  64          */
  65         virtual RequestMapper::Settings getRequestSettings() const=0;
  66
  67         /**
  68          * Returns the Application governing the request.
  69          *
  70          * @return reference to Application
  71          */
  72         virtual const Application& getApplication() const=0;
  73
  74         /**
  75          * Returns a locked Session associated with the request.
  76          *
  77          * @param checkTimeout  true iff the last-used timestamp should be updated and any timeout policy enforced
  78          * @param ignoreAddress true iff all address checking should be ignored, regardless of policy
  79          * @param cache         true iff the request should hold the Session lock itself and unlock during cleanup
  80          * @return pointer to Session, or NULL
  81          */
  82         virtual Session* getSession(bool checkTimeout=true, bool ignoreAddress=false, bool cache=true) const=0;
  83
  84         /**
  85          * Returns the effective base Handler URL for a resource,
  86          * or the current request URL.
  87          *
  88          * @param resource  resource URL to compute handler for
  89          * @return  base location of handler
  90          */
  91         virtual const char* getHandlerURL(const char* resource=NULL) const=0;
  92
  93         /**
  94          * Get a cookie value supplied by the client.
  95          *
  96          * @param name  name of cookie
  97          * @return  cookie value or NULL
  98          */
  99         virtual const char* getCookie(const char* name) const=0;
 100
 101         /**
 102          * Returns a non-spoofable request header value, if possible.
 103          * Platforms that support environment export can redirect header
 104          * lookups by overriding this method.
 105          *
 106          * @param name  the name of the secure header to return
 107          * @return the header's value, or an empty string
 108          */
 109         virtual std::string getSecureHeader(const char* name) const {
 110             return getHeader(name);
 111         }
 112
 113         /**
 114          * Ensures no value exists for a request header.
 115          *
 116          * @param rawname  raw name of header to clear
 117          * @param cginame  CGI-equivalent name of header
 118          */
 119         virtual void clearHeader(const char* rawname, const char* cginame)=0;
 120
 121         /**
 122          * Sets a value for a request header.
 123          *
 124          * @param name  name of header to set
 125          * @param value value to set
 126          */
 127         virtual void setHeader(const char* name, const char* value)=0;
 128
 129         /**
 130          * Establish REMOTE_USER identity in request.
 131          *
 132          * @param user  REMOTE_USER value to set or NULL to clear
 133          */
 134         virtual void setRemoteUser(const char* user)=0;
 135
 136         /** Portable logging levels. */
 137         enum SPLogLevel {
 138           SPDebug,
 139           SPInfo,
 140           SPWarn,
 141           SPError,
 142           SPCrit
 143         };
 144
 145         /**
 146          * Log to native server environment.
 147          *
 148          * @param level logging level
 149          * @param msg   message to log
 150          */
 151         virtual void log(SPLogLevel level, const std::string& msg) const=0;
 152
 153         /**
 154          * Test logging level.
 155          *
 156          * @param level logging level
 157          * @return true iff logging level is enabled
 158          */
 159         virtual bool isPriorityEnabled(SPLogLevel level) const=0;
 160
 161         /**
 162          * Indicates that processing was declined, meaning no action is required during this phase of processing.
 163          *
 164          * @return  a status code to pass back to the server-specific layer
 165          */
 166         virtual long returnDecline()=0;
 167
 168         /**
 169          * Indicates that processing was completed.
 170          *
 171          * @return  a status code to pass back to the server-specific layer
 172          */
 173         virtual long returnOK()=0;
 174     };
 175 };
 176
 177 #endif /* __shibsp_req_h__ */