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 xmltooling/soap/SOAPTransport.h
24 * Encapsulates a transport layer protocol for sending/receiving messages.
27 #ifndef __xmltooling_soaptrans_h__
28 #define __xmltooling_soaptrans_h__
30 #include <xmltooling/base.h>
35 namespace xmltooling {
37 class XMLTOOL_API Credential;
38 class XMLTOOL_API CredentialCriteria;
39 class XMLTOOL_API CredentialResolver;
40 class XMLTOOL_API X509TrustEngine;
43 * Encapsulates a transport layer protocol for sending/receiving messages.
45 * Most of the methods are const, meaning they don't affect the transport
46 * layer until the data is sent.
48 class XMLTOOL_API SOAPTransport
50 MAKE_NONCOPYABLE(SOAPTransport);
54 virtual ~SOAPTransport();
57 * A simple structure to capture SOAP addressing information.
59 struct XMLTOOL_API Address {
63 * @param from name of sender
64 * @param to name of recipient
65 * @param endpoint endpoint URL
67 Address(const char* from, const char* to, const char* endpoint) : m_from(from), m_to(to), m_endpoint(endpoint) {
70 /** Name of sender. */
73 /** Name of recipient. */
77 const char* m_endpoint;
81 * Indicates whether transport provides confidentiality.
83 * @return true iff transport layer provides confidentiality
85 virtual bool isConfidential() const=0;
88 * Sets the connection timeout.
90 * @param timeout time to wait for connection to server in seconds, or -1 for no timeout
91 * @return true iff the transport supports connection timeouts
93 virtual bool setConnectTimeout(long timeout)=0;
96 * Sets the request timeout.
98 * @param timeout time to wait for a response in seconds, or -1 for no timeout
99 * @return true iff the transport supports request/response timeouts
101 virtual bool setTimeout(long timeout)=0;
104 * Common types of transport authentication that may be supported.
106 enum transport_auth_t {
107 transport_auth_none = 0,
108 transport_auth_basic = 1,
109 transport_auth_digest = 2,
110 transport_auth_ntlm = 3,
111 transport_auth_gss = 4
115 * Sets a particular form of transport authentication and credentials.
117 * @param authType type of transport authentication to use
118 * @param username username for transport authentication
119 * @param password simple password/credential for transport authentication
120 * @return true iff the transport supports the indicated form of authentication
122 virtual bool setAuth(transport_auth_t authType, const char* username=nullptr, const char* password=nullptr)=0;
125 * Determines whether TLS/SSL connections include a check of the server's certificate
126 * against the expected hostname or address. Defaults to true, and has no effect for
127 * insecure protocols.
129 * @param verify true iff the hostname should be verified against the server's certificate
130 * @return true iff the transport supports hostname verification
132 virtual bool setVerifyHost(bool verify)=0;
134 #ifndef XMLTOOLING_NO_XMLSEC
136 * Supplies transport credentials.
138 * <p>The lifetime of the credential must be longer than the lifetime of this object.
140 * @param credential a Credential instance, or nullptr
141 * @return true iff the transport supports the use of the Credential
143 virtual bool setCredential(const Credential* credential=nullptr)=0;
146 * Provides an X509TrustEngine to the transport to authenticate the transport peer.
147 * The lifetime of the engine must be longer than the lifetime of this object.
149 * @param trustEngine an X509TrustEngine instance, or nullptr
150 * @param credResolver a CredentialResolver to supply the peer's trusted credentials, or nullptr
151 * @param criteria optional criteria for selecting peer credentials
152 * @param mandatory flag controls whether message is sent at all if the
153 * transport isn't authenticated using the TrustEngine
154 * @return true iff the transport supports the use of a TrustEngine
156 virtual bool setTrustEngine(
157 const X509TrustEngine* trustEngine=nullptr,
158 const CredentialResolver* credResolver=nullptr,
159 CredentialCriteria* criteria=nullptr,
165 * Installs (or clears) a pointer to an object used for cache management of the
166 * content being accessed. The lifetime of the object must be longer than the lifetime
169 * @param cacheTag optional pointer to string used for cache management
171 virtual bool setCacheTag(std::string* cacheTag=nullptr);
174 * Sets an implementation-specific transport provider option.
176 * <p>Requires knowledge of the underlying SOAPTransport implementation.
177 * Without the proper knowledge and inputs, crashes may result.
179 * @param provider name of the SOAPTransport class the caller believes is in use
180 * @param option implementation-specific string containing the option to set
181 * @param value implementation- and option-specific string to use
182 * @return true iff the transport supports the option and value supplied
184 virtual bool setProviderOption(const char* provider, const char* option, const char* value);
187 * Sends a stream of data over the transport. The function may return without
188 * having received any data, depending on the nature of the transport.
190 * <p>If the stream is empty, a request may be issued with no body if the transport
191 * supports that feature.
193 * @param in input stream to send
195 virtual void send(std::istream& in)=0;
198 * Sends an optional stream of data over the transport. The function may return without
199 * having received any data, depending on the nature of the transport.
201 * <p>If the parameter is omitted, a request may be issued with no body if the transport
202 * supports that feature.
204 * @param in input stream to send
206 virtual void send(std::istream* in=nullptr);
209 * Returns reference to response stream. The resulting stream must be
210 * checked directly to determine whether data is available.
212 * @return reference to a stream containing the response, if any
214 virtual std::istream& receive()=0;
217 * Returns result of authenticating transport peer.
219 * @return true iff TrustEngine or other mechanism successfully authenticated the peer
221 virtual bool isAuthenticated() const=0;
224 * Returns the MIME type of the response, if any.
226 * @return MIME type of response, or an empty string
228 virtual std::string getContentType() const=0;
231 * Returns the status code of the response.
233 * @return transport status code, or 0 if unknown
235 virtual long getStatusCode() const;
239 * Registers SOAPTransport classes into the runtime.
241 void XMLTOOL_API registerSOAPTransports();
244 * Notifies transport infrastructure to initialize.
246 void XMLTOOL_API initSOAPTransports();
249 * Notifies transport infrastructure to shutdown.
251 void XMLTOOL_API termSOAPTransports();
255 #endif /* __xmltooling_soaptrans_h__ */