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