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=0; 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)=0; 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__ */ 179