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 CredentialResolver;
  32     class XMLTOOL_API KeyResolver;
  33     class XMLTOOL_API X509TrustEngine;
  34
  35     /**
  36      * Encapsulates a transport layer protocol for sending/receiving messages.
  37      *
  38      * Most of the methods are const, meaning they don't affect the transport
  39      * layer until the data is sent.
  40      */
  41     class XMLTOOL_API SOAPTransport
  42     {
  43         MAKE_NONCOPYABLE(SOAPTransport);
  44     protected:
  45         SOAPTransport() {}
  46     public:
  47         virtual ~SOAPTransport() {}
  48
  49         /**
  50          * Indicates whether transport provides confidentiality.
  51          *
  52          * @return  true iff transport layer provides confidentiality
  53          */
  54         virtual bool isConfidential() const=0;
  55
  56         /**
  57          * Sets the connection timeout.
  58          *
  59          * @param timeout  time to wait for connection to server in seconds, or -1 for no timeout
  60          * @return  true iff the transport supports connection timeouts
  61          */
  62         virtual bool setConnectTimeout(long timeout)=0;
  63
  64         /**
  65          * Sets the request timeout.
  66          *
  67          * @param timeout  time to wait for a response in seconds, or -1 for no timeout
  68          * @return  true iff the transport supports request/response timeouts
  69          */
  70         virtual bool setTimeout(long timeout)=0;
  71
  72         /**
  73          * Common types of transport authentication that may be supported.
  74          */
  75         enum transport_auth_t {
  76             transport_auth_none = 0,
  77             transport_auth_basic = 1,
  78             transport_auth_digest = 2,
  79             transport_auth_ntlm = 3,
  80             transport_auth_gss = 4
  81         };
  82
  83         /**
  84          * Sets a particular form of transport authentication and credentials.
  85          *
  86          * @param authType  type of transport authentication to use
  87          * @param username  username for transport authentication
  88          * @param password  simple password/credential for transport authentication
  89          * @return  true iff the transport supports the indicated form of authentication
  90          */
  91         virtual bool setAuth(transport_auth_t authType, const char* username=NULL, const char* password=NULL)=0;
  92
  93 #ifndef XMLTOOLING_NO_XMLSEC
  94         /**
  95          * Provides a CredentialResolver to the transport to supply transport credentials.
  96          * The lifetime of the resolver must be longer than the lifetime of this object.
  97          *
  98          * <p>The CredentialResolver <strong>MUST</strong> be locked by the caller.
  99          *
 100          * @param credResolver  a locked CredentialResolver instance, or NULL
 101          * @return true iff the transport supports the use of a CredentialResolver
 102          */
 103         virtual bool setCredentialResolver(const CredentialResolver* credResolver)=0;
 104
 105         /**
 106          * Provides a TrustEngine to the transport to authenticate the transport peer.
 107          * The lifetime of the engine must be longer than the lifetime of this object.
 108          *
 109          * @param trustEngine   a TrustEngine instance, or NULL
 110          * @param mandatory     flag controls whether message is sent at all if the
 111          *                      transport isn't authenticated using the TrustEngine
 112          * @param keyResolver   optional externally supplied KeyResolver, or NULL
 113          * @return true iff the transport supports the use of a TrustEngine
 114          */
 115         virtual bool setTrustEngine(
 116             const X509TrustEngine* trustEngine,
 117             bool mandatory=true,
 118             const KeyResolver* keyResolver=NULL
 119             )=0;
 120 #endif
 121
 122         /**
 123          * Sends a stream of data over the transport. The function may return without
 124          * having received any data, depending on the nature of the transport.
 125          *
 126          * @param in    input stream to send
 127          */
 128         virtual void send(std::istream& in)=0;
 129
 130         /**
 131          * Returns reference to response stream.  The resulting stream must be
 132          * checked directly to determine whether data is available.
 133          *
 134          * @return  reference to a stream containing the response, if any
 135          */
 136         virtual std::istream& receive()=0;
 137
 138         /**
 139          * Returns result of authenticating transport peer.
 140          *
 141          * @return true iff TrustEngine or other mechanism successfully authenticated the peer
 142          */
 143         virtual bool isSecure() const=0;
 144
 145         /**
 146          * Returns the MIME type of the response, if any.
 147          *
 148          * @return  MIME type of response, or an empty string
 149          */
 150         virtual std::string getContentType() const=0;
 151     };
 152
 153     /**
 154      * Registers SOAPTransport classes into the runtime.
 155      */
 156     void XMLTOOL_API registerSOAPTransports();
 157
 158     /**
 159      * Notifies transport infrastructure to initialize.
 160      */
 161     void XMLTOOL_API initSOAPTransports();
 162
 163     /**
 164      * Notifies transport infrastructure to shutdown.
 165      */
 166     void XMLTOOL_API termSOAPTransports();
 167
 168 };
 169
 170 #endif /* __xmltooling_soaptrans_h__ */