xmltooling/soap/SOAPTransport.h

   1 /*
   2  *  Copyright 2001-2007 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 #include <iostream>
  28
  29 namespace xmltooling {
  30
  31     class XMLTOOL_API Credential;
  32     class XMLTOOL_API CredentialCriteria;
  33     class XMLTOOL_API CredentialResolver;
  34     class XMLTOOL_API X509TrustEngine;
  35
  36     /**
  37      * Encapsulates a transport layer protocol for sending/receiving messages.
  38      *
  39      * Most of the methods are const, meaning they don't affect the transport
  40      * layer until the data is sent.
  41      */
  42     class XMLTOOL_API SOAPTransport
  43     {
  44         MAKE_NONCOPYABLE(SOAPTransport);
  45     protected:
  46         SOAPTransport() {}
  47     public:
  48         virtual ~SOAPTransport() {}
  49
  50         /**
  51          * Indicates whether transport provides confidentiality.
  52          *
  53          * @return  true iff transport layer provides confidentiality
  54          */
  55         virtual bool isConfidential() const=0;
  56
  57         /**
  58          * Sets the connection timeout.
  59          *
  60          * @param timeout  time to wait for connection to server in seconds, or -1 for no timeout
  61          * @return  true iff the transport supports connection timeouts
  62          */
  63         virtual bool setConnectTimeout(long timeout)=0;
  64
  65         /**
  66          * Sets the request timeout.
  67          *
  68          * @param timeout  time to wait for a response in seconds, or -1 for no timeout
  69          * @return  true iff the transport supports request/response timeouts
  70          */
  71         virtual bool setTimeout(long timeout)=0;
  72
  73         /**
  74          * Common types of transport authentication that may be supported.
  75          */
  76         enum transport_auth_t {
  77             transport_auth_none = 0,
  78             transport_auth_basic = 1,
  79             transport_auth_digest = 2,
  80             transport_auth_ntlm = 3,
  81             transport_auth_gss = 4
  82         };
  83
  84         /**
  85          * Sets a particular form of transport authentication and credentials.
  86          *
  87          * @param authType  type of transport authentication to use
  88          * @param username  username for transport authentication
  89          * @param password  simple password/credential for transport authentication
  90          * @return  true iff the transport supports the indicated form of authentication
  91          */
  92         virtual bool setAuth(transport_auth_t authType, const char* username=NULL, const char* password=NULL)=0;
  93
  94         /**
  95          * Determines whether TLS/SSL connections include a check of the server's certificate
  96          * against the expected hostname or address. Defaults to true, and has no effect for
  97          * insecure protocols.
  98          *
  99          * @param verify    true iff the hostname should be verified against the server's certificate
 100          * @return  true iff the transport supports hostname verification
 101          */
 102         virtual bool setVerifyHost(bool verify)=0;
 103
 104 #ifndef XMLTOOLING_NO_XMLSEC
 105         /**
 106          * Supplies transport credentials.
 107          *
 108          * <p>The lifetime of the credential must be longer than the lifetime of this object.
 109          *
 110          * @param credential  a Credential instance, or NULL
 111          * @return true iff the transport supports the use of the Credential
 112          */
 113         virtual bool setCredential(const Credential* credential=NULL)=0;
 114
 115         /**
 116          * Provides an X509TrustEngine to the transport to authenticate the transport peer.
 117          * The lifetime of the engine must be longer than the lifetime of this object.
 118          *
 119          * @param trustEngine   an X509TrustEngine instance, or NULL
 120          * @param credResolver  a CredentialResolver to supply the peer's trusted credentials, or NULL
 121          * @param criteria      optional criteria for selecting peer credentials
 122          * @param mandatory     flag controls whether message is sent at all if the
 123          *                      transport isn't authenticated using the TrustEngine
 124          * @return true iff the transport supports the use of a TrustEngine
 125          */
 126         virtual bool setTrustEngine(
 127             const X509TrustEngine* trustEngine=NULL,
 128             const CredentialResolver* credResolver=NULL,
 129             CredentialCriteria* criteria=NULL,
 130             bool mandatory=true
 131             )=0;
 132 #endif
 133
 134         /**
 135          * Sets an implementation-specific transport provider option.
 136          *
 137          * <p>Requires knowledge of the underlying SOAPTransport implementation.
 138          * Without the proper knowledge and inputs, crashes may result.
 139          *
 140          * @param provider  name of the SOAPTransport class the caller believes is in use
 141          * @param option    implementation-specific string containing the option to set
 142          * @param value     implementation- and option-specific string to use
 143          * @return  true iff the transport supports the option and value supplied
 144          */
 145         virtual bool setProviderOption(const char* provider, const char* option, const char* value) {
 146             return false;
 147         }
 148
 149         /**
 150          * Sends a stream of data over the transport. The function may return without
 151          * having received any data, depending on the nature of the transport.
 152          *
 153          * @param in    input stream to send
 154          */
 155         virtual void send(std::istream& in)=0;
 156
 157         /**
 158          * Returns reference to response stream.  The resulting stream must be
 159          * checked directly to determine whether data is available.
 160          *
 161          * @return  reference to a stream containing the response, if any
 162          */
 163         virtual std::istream& receive()=0;
 164
 165         /**
 166          * Returns result of authenticating transport peer.
 167          *
 168          * @return true iff TrustEngine or other mechanism successfully authenticated the peer
 169          */
 170         virtual bool isSecure() const=0;
 171
 172         /**
 173          * Returns the MIME type of the response, if any.
 174          *
 175          * @return  MIME type of response, or an empty string
 176          */
 177         virtual std::string getContentType() const=0;
 178     };
 179
 180 #ifndef XMLTOOLING_NO_XMLSEC
 181     /**
 182      * Registers SOAPTransport classes into the runtime.
 183      */
 184     void XMLTOOL_API registerSOAPTransports();
 185
 186     /**
 187      * Notifies transport infrastructure to initialize.
 188      */
 189     void XMLTOOL_API initSOAPTransports();
 190
 191     /**
 192      * Notifies transport infrastructure to shutdown.
 193      */
 194     void XMLTOOL_API termSOAPTransports();
 195 #endif
 196
 197 };
 198
 199 #endif /* __xmltooling_soaptrans_h__ */