shibsp/SPRequest.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file shibsp/SPRequest.h
  23  *
  24  * Interface to server request being processed.
  25  */
  26
  27 #ifndef __shibsp_req_h__
  28 #define __shibsp_req_h__
  29
  30 #include <shibsp/RequestMapper.h>
  31 #include <xmltooling/io/HTTPRequest.h>
  32 #include <xmltooling/io/HTTPResponse.h>
  33
  34 namespace shibsp {
  35
  36     class SHIBSP_API Application;
  37     class SHIBSP_API ServiceProvider;
  38     class SHIBSP_API Session;
  39
  40     /**
  41      * Interface to server request being processed
  42      *
  43      * <p>To supply information from the surrounding web server environment,
  44      * a shim must be supplied in the form of this interface to adapt the
  45      * library to different proprietary server APIs.
  46      *
  47      * <p>This interface need not be threadsafe.
  48      */
  49     class SHIBSP_API SPRequest : public virtual xmltooling::HTTPRequest, public virtual xmltooling::HTTPResponse
  50     {
  51     protected:
  52         SPRequest();
  53     public:
  54         virtual ~SPRequest();
  55
  56         /**
  57          * Returns the locked ServiceProvider processing the request.
  58          *
  59          * @return reference to ServiceProvider
  60          */
  61         virtual const ServiceProvider& getServiceProvider() const=0;
  62
  63         /**
  64          * Returns RequestMapper Settings associated with the request, guaranteed
  65          * to be valid for the request's duration.
  66          *
  67          * @return copy of settings
  68          */
  69         virtual RequestMapper::Settings getRequestSettings() const=0;
  70
  71         /**
  72          * Returns the Application governing the request.
  73          *
  74          * @return reference to Application
  75          */
  76         virtual const Application& getApplication() const=0;
  77
  78         /**
  79          * Returns a locked Session associated with the request.
  80          *
  81          * @param checkTimeout  true iff the last-used timestamp should be updated and any timeout policy enforced
  82          * @param ignoreAddress true iff all address checking should be ignored, regardless of policy
  83          * @param cache         true iff the request should hold the Session lock itself and unlock during cleanup
  84          * @return pointer to Session, or nullptr
  85          */
  86         virtual Session* getSession(bool checkTimeout=true, bool ignoreAddress=false, bool cache=true)=0;
  87
  88         /**
  89          * Returns the effective base Handler URL for a resource,
  90          * or the current request URL.
  91          *
  92          * @param resource  resource URL to compute handler for
  93          * @return  base location of handler
  94          */
  95         virtual const char* getHandlerURL(const char* resource=nullptr) const=0;
  96
  97         /**
  98          * Returns a non-spoofable request header value, if possible.
  99          * Platforms that support environment export can redirect header
 100          * lookups by overriding this method.
 101          *
 102          * @param name  the name of the secure header to return
 103          * @return the header's value, or an empty string
 104          */
 105         virtual std::string getSecureHeader(const char* name) const;
 106
 107         /**
 108          * Ensures no value exists for a request header.
 109          *
 110          * @param rawname  raw name of header to clear
 111          * @param cginame  CGI-equivalent name of header
 112          */
 113         virtual void clearHeader(const char* rawname, const char* cginame)=0;
 114
 115         /**
 116          * Sets a value for a request header.
 117          *
 118          * @param name  name of header to set
 119          * @param value value to set
 120          */
 121         virtual void setHeader(const char* name, const char* value)=0;
 122
 123         /**
 124          * Establish REMOTE_USER identity in request.
 125          *
 126          * @param user  REMOTE_USER value to set or nullptr to clear
 127          */
 128         virtual void setRemoteUser(const char* user)=0;
 129
 130         /**
 131          * Establish AUTH_TYPE for request.
 132          *
 133          * @param authtype  AUTH_TYPE value to set or nullptr to clear
 134          */
 135         virtual void setAuthType(const char* authtype);
 136
 137         /** Portable logging levels. */
 138         enum SPLogLevel {
 139           SPDebug,
 140           SPInfo,
 141           SPWarn,
 142           SPError,
 143           SPCrit
 144         };
 145
 146         /**
 147          * Log to native server environment.
 148          *
 149          * @param level logging level
 150          * @param msg   message to log
 151          */
 152         virtual void log(SPLogLevel level, const std::string& msg) const=0;
 153
 154         /**
 155          * Test logging level.
 156          *
 157          * @param level logging level
 158          * @return true iff logging level is enabled
 159          */
 160         virtual bool isPriorityEnabled(SPLogLevel level) const=0;
 161
 162         /**
 163          * Indicates that processing was declined, meaning no action is required during this phase of processing.
 164          *
 165          * @return  a status code to pass back to the server-specific layer
 166          */
 167         virtual long returnDecline()=0;
 168
 169         /**
 170          * Indicates that processing was completed.
 171          *
 172          * @return  a status code to pass back to the server-specific layer
 173          */
 174         virtual long returnOK()=0;
 175     };
 176 };
 177
 178 #endif /* __shibsp_req_h__ */