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 xmltooling/soap/SOAPTransport.h
20 * Encapsulates a transport layer protocol for sending/receiving messages.
23 #ifndef __xmltooling_soaptrans_h__
24 #define __xmltooling_soaptrans_h__
26 #include <xmltooling/base.h>
31 namespace xmltooling {
33 class XMLTOOL_API Credential;
34 class XMLTOOL_API CredentialCriteria;
35 class XMLTOOL_API CredentialResolver;
36 class XMLTOOL_API X509TrustEngine;
39 * Encapsulates a transport layer protocol for sending/receiving messages.
41 * Most of the methods are const, meaning they don't affect the transport
42 * layer until the data is sent.
44 class XMLTOOL_API SOAPTransport
46 MAKE_NONCOPYABLE(SOAPTransport);
50 virtual ~SOAPTransport();
53 * A simple structure to capture SOAP addressing information.
55 struct XMLTOOL_API Address {
59 * @param from name of sender
60 * @param to name of recipient
61 * @param endpoint endpoint URL
63 Address(const char* from, const char* to, const char* endpoint) : m_from(from), m_to(to), m_endpoint(endpoint) {
66 /** Name of sender. */
69 /** Name of recipient. */
73 const char* m_endpoint;
77 * Indicates whether transport provides confidentiality.
79 * @return true iff transport layer provides confidentiality
81 virtual bool isConfidential() const=0;
84 * Sets the connection timeout.
86 * @param timeout time to wait for connection to server in seconds, or -1 for no timeout
87 * @return true iff the transport supports connection timeouts
89 virtual bool setConnectTimeout(long timeout)=0;
92 * Sets the request timeout.
94 * @param timeout time to wait for a response in seconds, or -1 for no timeout
95 * @return true iff the transport supports request/response timeouts
97 virtual bool setTimeout(long timeout)=0;
100 * Common types of transport authentication that may be supported.
102 enum transport_auth_t {
103 transport_auth_none = 0,
104 transport_auth_basic = 1,
105 transport_auth_digest = 2,
106 transport_auth_ntlm = 3,
107 transport_auth_gss = 4
111 * Sets a particular form of transport authentication and credentials.
113 * @param authType type of transport authentication to use
114 * @param username username for transport authentication
115 * @param password simple password/credential for transport authentication
116 * @return true iff the transport supports the indicated form of authentication
118 virtual bool setAuth(transport_auth_t authType, const char* username=nullptr, const char* password=nullptr)=0;
121 * Determines whether TLS/SSL connections include a check of the server's certificate
122 * against the expected hostname or address. Defaults to true, and has no effect for
123 * insecure protocols.
125 * @param verify true iff the hostname should be verified against the server's certificate
126 * @return true iff the transport supports hostname verification
128 virtual bool setVerifyHost(bool verify)=0;
130 #ifndef XMLTOOLING_NO_XMLSEC
132 * Supplies transport credentials.
134 * <p>The lifetime of the credential must be longer than the lifetime of this object.
136 * @param credential a Credential instance, or nullptr
137 * @return true iff the transport supports the use of the Credential
139 virtual bool setCredential(const Credential* credential=nullptr)=0;
142 * Provides an X509TrustEngine to the transport to authenticate the transport peer.
143 * The lifetime of the engine must be longer than the lifetime of this object.
145 * @param trustEngine an X509TrustEngine instance, or nullptr
146 * @param credResolver a CredentialResolver to supply the peer's trusted credentials, or nullptr
147 * @param criteria optional criteria for selecting peer credentials
148 * @param mandatory flag controls whether message is sent at all if the
149 * transport isn't authenticated using the TrustEngine
150 * @return true iff the transport supports the use of a TrustEngine
152 virtual bool setTrustEngine(
153 const X509TrustEngine* trustEngine=nullptr,
154 const CredentialResolver* credResolver=nullptr,
155 CredentialCriteria* criteria=nullptr,
161 * Installs (or clears) a pointer to an object used for cache management of the
162 * content being accessed. The lifetime of the object must be longer than the lifetime
165 * @param cacheTag optional pointer to string used for cache management
167 virtual bool setCacheTag(std::string* cacheTag=nullptr);
170 * Sets an implementation-specific transport provider option.
172 * <p>Requires knowledge of the underlying SOAPTransport implementation.
173 * Without the proper knowledge and inputs, crashes may result.
175 * @param provider name of the SOAPTransport class the caller believes is in use
176 * @param option implementation-specific string containing the option to set
177 * @param value implementation- and option-specific string to use
178 * @return true iff the transport supports the option and value supplied
180 virtual bool setProviderOption(const char* provider, const char* option, const char* value);
183 * Sends a stream of data over the transport. The function may return without
184 * having received any data, depending on the nature of the transport.
186 * <p>If the stream is empty, a request may be issued with no body if the transport
187 * supports that feature.
189 * @param in input stream to send
191 virtual void send(std::istream& in)=0;
194 * Sends an optional stream of data over the transport. The function may return without
195 * having received any data, depending on the nature of the transport.
197 * <p>If the parameter is omitted, a request may be issued with no body if the transport
198 * supports that feature.
200 * @param in input stream to send
202 virtual void send(std::istream* in=nullptr);
205 * Returns reference to response stream. The resulting stream must be
206 * checked directly to determine whether data is available.
208 * @return reference to a stream containing the response, if any
210 virtual std::istream& receive()=0;
213 * Returns result of authenticating transport peer.
215 * @return true iff TrustEngine or other mechanism successfully authenticated the peer
217 virtual bool isAuthenticated() const=0;
220 * Returns the MIME type of the response, if any.
222 * @return MIME type of response, or an empty string
224 virtual std::string getContentType() const=0;
227 * Returns the status code of the response.
229 * @return transport status code, or 0 if unknown
231 virtual long getStatusCode() const;
234 #ifndef XMLTOOLING_NO_XMLSEC
236 * Registers SOAPTransport classes into the runtime.
238 void XMLTOOL_API registerSOAPTransports();
241 * Notifies transport infrastructure to initialize.
243 void XMLTOOL_API initSOAPTransports();
246 * Notifies transport infrastructure to shutdown.
248 void XMLTOOL_API termSOAPTransports();
253 #endif /* __xmltooling_soaptrans_h__ */