xmltooling/soap/SOAPTransport.h

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