2 * Copyright 2001-2010 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file shibsp/SPRequest.h
20 * Interface to server request being processed.
23 #ifndef __shibsp_req_h__
24 #define __shibsp_req_h__
26 #include <shibsp/RequestMapper.h>
27 #include <xmltooling/io/HTTPRequest.h>
28 #include <xmltooling/io/HTTPResponse.h>
32 class SHIBSP_API Application;
33 class SHIBSP_API ServiceProvider;
34 class SHIBSP_API Session;
37 * Interface to server request being processed
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.
43 * <p>This interface need not be threadsafe.
45 class SHIBSP_API SPRequest : public virtual xmltooling::HTTPRequest, public virtual xmltooling::HTTPResponse
53 * Returns the locked ServiceProvider processing the request.
55 * @return reference to ServiceProvider
57 virtual const ServiceProvider& getServiceProvider() const=0;
60 * Returns RequestMapper Settings associated with the request, guaranteed
61 * to be valid for the request's duration.
63 * @return copy of settings
65 virtual RequestMapper::Settings getRequestSettings() const=0;
68 * Returns the Application governing the request.
70 * @return reference to Application
72 virtual const Application& getApplication() const=0;
75 * Returns a locked Session associated with the request.
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 nullptr
82 virtual Session* getSession(bool checkTimeout=true, bool ignoreAddress=false, bool cache=true)=0;
85 * Returns the effective base Handler URL for a resource,
86 * or the current request URL.
88 * @param resource resource URL to compute handler for
89 * @return base location of handler
91 virtual const char* getHandlerURL(const char* resource=nullptr) const=0;
94 * Returns a non-spoofable request header value, if possible.
95 * Platforms that support environment export can redirect header
96 * lookups by overriding this method.
98 * @param name the name of the secure header to return
99 * @return the header's value, or an empty string
101 virtual std::string getSecureHeader(const char* name) const;
104 * Ensures no value exists for a request header.
106 * @param rawname raw name of header to clear
107 * @param cginame CGI-equivalent name of header
109 virtual void clearHeader(const char* rawname, const char* cginame)=0;
112 * Sets a value for a request header.
114 * @param name name of header to set
115 * @param value value to set
117 virtual void setHeader(const char* name, const char* value)=0;
120 * Establish REMOTE_USER identity in request.
122 * @param user REMOTE_USER value to set or nullptr to clear
124 virtual void setRemoteUser(const char* user)=0;
127 * Establish AUTH_TYPE for request.
129 * @param authtype AUTH_TYPE value to set or nullptr to clear
131 virtual void setAuthType(const char* authtype);
133 /** Portable logging levels. */
143 * Log to native server environment.
145 * @param level logging level
146 * @param msg message to log
148 virtual void log(SPLogLevel level, const std::string& msg) const=0;
151 * Test logging level.
153 * @param level logging level
154 * @return true iff logging level is enabled
156 virtual bool isPriorityEnabled(SPLogLevel level) const=0;
159 * Indicates that processing was declined, meaning no action is required during this phase of processing.
161 * @return a status code to pass back to the server-specific layer
163 virtual long returnDecline()=0;
166 * Indicates that processing was completed.
168 * @return a status code to pass back to the server-specific layer
170 virtual long returnOK()=0;
174 #endif /* __shibsp_req_h__ */