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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file shibsp/SPRequest.h
24 * Interface to server request being processed.
27 #ifndef __shibsp_req_h__
28 #define __shibsp_req_h__
30 #include <shibsp/RequestMapper.h>
31 #include <xmltooling/io/HTTPRequest.h>
32 #include <xmltooling/io/HTTPResponse.h>
36 class SHIBSP_API Application;
37 class SHIBSP_API ServiceProvider;
38 class SHIBSP_API Session;
41 * Interface to server request being processed
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.
47 * <p>This interface need not be threadsafe.
49 class SHIBSP_API SPRequest : public virtual xmltooling::HTTPRequest, public virtual xmltooling::HTTPResponse
57 * Returns the locked ServiceProvider processing the request.
59 * @return reference to ServiceProvider
61 virtual const ServiceProvider& getServiceProvider() const=0;
64 * Returns RequestMapper Settings associated with the request, guaranteed
65 * to be valid for the request's duration.
67 * @return copy of settings
69 virtual RequestMapper::Settings getRequestSettings() const=0;
72 * Returns the Application governing the request.
74 * @return reference to Application
76 virtual const Application& getApplication() const=0;
79 * Returns a locked Session associated with the request.
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
86 virtual Session* getSession(bool checkTimeout=true, bool ignoreAddress=false, bool cache=true)=0;
89 * Returns the effective base Handler URL for a resource,
90 * or the current request URL.
92 * @param resource resource URL to compute handler for
93 * @return base location of handler
95 virtual const char* getHandlerURL(const char* resource=nullptr) const=0;
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.
102 * @param name the name of the secure header to return
103 * @return the header's value, or an empty string
105 virtual std::string getSecureHeader(const char* name) const;
108 * Ensures no value exists for a request header.
110 * @param rawname raw name of header to clear
111 * @param cginame CGI-equivalent name of header
113 virtual void clearHeader(const char* rawname, const char* cginame)=0;
116 * Sets a value for a request header.
118 * @param name name of header to set
119 * @param value value to set
121 virtual void setHeader(const char* name, const char* value)=0;
124 * Establish REMOTE_USER identity in request.
126 * @param user REMOTE_USER value to set or nullptr to clear
128 virtual void setRemoteUser(const char* user)=0;
131 * Establish AUTH_TYPE for request.
133 * @param authtype AUTH_TYPE value to set or nullptr to clear
135 virtual void setAuthType(const char* authtype);
137 /** Portable logging levels. */
147 * Log to native server environment.
149 * @param level logging level
150 * @param msg message to log
152 virtual void log(SPLogLevel level, const std::string& msg) const=0;
155 * Test logging level.
157 * @param level logging level
158 * @return true iff logging level is enabled
160 virtual bool isPriorityEnabled(SPLogLevel level) const=0;
163 * Indicates that processing was declined, meaning no action is required during this phase of processing.
165 * @return a status code to pass back to the server-specific layer
167 virtual long returnDecline()=0;
170 * Indicates that processing was completed.
172 * @return a status code to pass back to the server-specific layer
174 virtual long returnOK()=0;
178 #endif /* __shibsp_req_h__ */