xmltooling/soap/SOAPTransport.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file xmltooling/soap/SOAPTransport.h
  19  *
  20  * Encapsulates a transport layer protocol for sending/receiving messages.
  21  */
  22
  23 #ifndef __xmltooling_soaptrans_h__
  24 #define __xmltooling_soaptrans_h__
  25
  26 #include <xmltooling/base.h>
  27
  28 #include <string>
  29 #include <iostream>
  30
  31 namespace xmltooling {
  32
  33     class XMLTOOL_API Credential;
  34     class XMLTOOL_API CredentialCriteria;
  35     class XMLTOOL_API CredentialResolver;
  36     class XMLTOOL_API X509TrustEngine;
  37
  38     /**
  39      * Encapsulates a transport layer protocol for sending/receiving messages.
  40      *
  41      * Most of the methods are const, meaning they don't affect the transport
  42      * layer until the data is sent.
  43      */
  44     class XMLTOOL_API SOAPTransport
  45     {
  46         MAKE_NONCOPYABLE(SOAPTransport);
  47     protected:
  48         SOAPTransport();
  49     public:
  50         virtual ~SOAPTransport();
  51
  52         /**
  53          * A simple structure to capture SOAP addressing information.
  54          */
  55         struct XMLTOOL_API Address {
  56             /**
  57              * Constructor.
  58              *
  59              * @param from      name of sender
  60              * @param to        name of recipient
  61              * @param endpoint  endpoint URL
  62              */
  63             Address(const char* from, const char* to, const char* endpoint) : m_from(from), m_to(to), m_endpoint(endpoint) {
  64             }
  65
  66             /** Name of sender. */
  67             const char* m_from;
  68
  69             /** Name of recipient. */
  70             const char* m_to;
  71
  72             /** Endpoint URL. */
  73             const char* m_endpoint;
  74         };
  75
  76         /**
  77          * Indicates whether transport provides confidentiality.
  78          *
  79          * @return  true iff transport layer provides confidentiality
  80          */
  81         virtual bool isConfidential() const=0;
  82
  83         /**
  84          * Sets the connection timeout.
  85          *
  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
  88          */
  89         virtual bool setConnectTimeout(long timeout)=0;
  90
  91         /**
  92          * Sets the request timeout.
  93          *
  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
  96          */
  97         virtual bool setTimeout(long timeout)=0;
  98
  99         /**
 100          * Common types of transport authentication that may be supported.
 101          */
 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
 108         };
 109
 110         /**
 111          * Sets a particular form of transport authentication and credentials.
 112          *
 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
 117          */
 118         virtual bool setAuth(transport_auth_t authType, const char* username=nullptr, const char* password=nullptr)=0;
 119
 120         /**
 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.
 124          *
 125          * @param verify    true iff the hostname should be verified against the server's certificate
 126          * @return  true iff the transport supports hostname verification
 127          */
 128         virtual bool setVerifyHost(bool verify)=0;
 129
 130 #ifndef XMLTOOLING_NO_XMLSEC
 131         /**
 132          * Supplies transport credentials.
 133          *
 134          * <p>The lifetime of the credential must be longer than the lifetime of this object.
 135          *
 136          * @param credential  a Credential instance, or nullptr
 137          * @return true iff the transport supports the use of the Credential
 138          */
 139         virtual bool setCredential(const Credential* credential=nullptr)=0;
 140
 141         /**
 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.
 144          *
 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
 151          */
 152         virtual bool setTrustEngine(
 153             const X509TrustEngine* trustEngine=nullptr,
 154             const CredentialResolver* credResolver=nullptr,
 155             CredentialCriteria* criteria=nullptr,
 156             bool mandatory=true
 157             )=0;
 158 #endif
 159
 160         /**
 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
 163          * of this object.
 164          *
 165          * @param cacheTag  optional pointer to string used for cache management
 166          */
 167         virtual bool setCacheTag(std::string* cacheTag=nullptr);
 168
 169         /**
 170          * Sets an implementation-specific transport provider option.
 171          *
 172          * <p>Requires knowledge of the underlying SOAPTransport implementation.
 173          * Without the proper knowledge and inputs, crashes may result.
 174          *
 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
 179          */
 180         virtual bool setProviderOption(const char* provider, const char* option, const char* value);
 181
 182         /**
 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.
 185          *
 186          * <p>If the stream is empty, a request may be issued with no body if the transport
 187          * supports that feature.
 188          *
 189          * @param in    input stream to send
 190          */
 191         virtual void send(std::istream& in)=0;
 192
 193         /**
 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.
 196          *
 197          * <p>If the parameter is omitted, a request may be issued with no body if the transport
 198          * supports that feature.
 199          *
 200          * @param in    input stream to send
 201          */
 202         virtual void send(std::istream* in=nullptr);
 203
 204         /**
 205          * Returns reference to response stream.  The resulting stream must be
 206          * checked directly to determine whether data is available.
 207          *
 208          * @return  reference to a stream containing the response, if any
 209          */
 210         virtual std::istream& receive()=0;
 211
 212         /**
 213          * Returns result of authenticating transport peer.
 214          *
 215          * @return true iff TrustEngine or other mechanism successfully authenticated the peer
 216          */
 217         virtual bool isAuthenticated() const=0;
 218
 219         /**
 220          * Returns the MIME type of the response, if any.
 221          *
 222          * @return  MIME type of response, or an empty string
 223          */
 224         virtual std::string getContentType() const=0;
 225
 226         /**
 227          * Returns the status code of the response.
 228          *
 229          * @return  transport status code, or 0 if unknown
 230          */
 231         virtual long getStatusCode() const;
 232     };
 233
 234 #ifndef XMLTOOLING_NO_XMLSEC
 235     /**
 236      * Registers SOAPTransport classes into the runtime.
 237      */
 238     void XMLTOOL_API registerSOAPTransports();
 239
 240     /**
 241      * Notifies transport infrastructure to initialize.
 242      */
 243     void XMLTOOL_API initSOAPTransports();
 244
 245     /**
 246      * Notifies transport infrastructure to shutdown.
 247      */
 248     void XMLTOOL_API termSOAPTransports();
 249 #endif
 250
 251 };
 252
 253 #endif /* __xmltooling_soaptrans_h__ */