xmltooling/io/GenericRequest.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/io/GenericRequest.h
  23  *
  24  * Interface to generic protocol requests that transport XML messages.
  25  */
  26
  27 #ifndef __xmltooling_genreq_h__
  28 #define __xmltooling_genreq_h__
  29
  30 #include <xmltooling/unicode.h>
  31
  32 #include <map>
  33 #include <string>
  34 #include <vector>
  35
  36 #ifndef XMLTOOLING_NO_XMLSEC
  37 # include <xsec/enc/XSECCryptoX509.hpp>
  38 #endif
  39
  40 namespace xmltooling {
  41
  42 #if defined (_MSC_VER)
  43     #pragma warning( push )
  44     #pragma warning( disable : 4251 )
  45 #endif
  46
  47     /**
  48      * Interface to generic protocol requests that transport XML messages.
  49      *
  50      * <p>This interface need not be threadsafe.
  51      */
  52     class XMLTOOL_API GenericRequest {
  53         MAKE_NONCOPYABLE(GenericRequest);
  54     protected:
  55         GenericRequest();
  56     public:
  57         virtual ~GenericRequest();
  58
  59         /**
  60          * Returns the URL scheme of the request (http, https, ftp, ldap, etc.)
  61          *
  62          * @return the URL scheme
  63          */
  64         virtual const char* getScheme() const=0;
  65
  66         /**
  67          * Returns true iff the request is over a confidential channel.
  68          *
  69          * @return confidential channel indicator
  70          */
  71         virtual bool isSecure() const=0;
  72
  73         /**
  74          * Returns hostname of service that received request.
  75          *
  76          * @return hostname of service
  77          */
  78         virtual const char* getHostname() const=0;
  79
  80         /**
  81          * Returns incoming port.
  82          *
  83          * @return  incoming port
  84          */
  85         virtual int getPort() const=0;
  86
  87         /**
  88          * Returns true iff the request port is the default port for the request protocol.
  89          *
  90          * @return  default port indicator
  91          */
  92         virtual bool isDefaultPort() const;
  93
  94         /**
  95          * Returns the MIME type of the request, if known.
  96          *
  97          * @return the MIME type, or an empty string
  98          */
  99         virtual std::string getContentType() const=0;
 100
 101         /**
 102          * Returns the length of the request body, if known.
 103          *
 104          * @return the content length, or -1 if unknown
 105          */
 106         virtual long getContentLength() const=0;
 107
 108         /**
 109          * Returns the raw request body.
 110          *
 111          * @return the request body, or nullptr
 112          */
 113         virtual const char* getRequestBody() const=0;
 114
 115         /**
 116          * Returns a decoded named parameter value from the request.
 117          * If a parameter has multiple values, only one will be returned.
 118          *
 119          * @param name  the name of the parameter to return
 120          * @return a single parameter value or nullptr
 121          */
 122         virtual const char* getParameter(const char* name) const=0;
 123
 124         /**
 125          * Returns all of the decoded values of a named parameter from the request.
 126          * All values found will be returned.
 127          *
 128          * @param name      the name of the parameter to return
 129          * @param values    a vector in which to return pointers to the decoded values
 130          * @return  the number of values returned
 131          */
 132         virtual std::vector<const char*>::size_type getParameters(
 133             const char* name, std::vector<const char*>& values
 134             ) const=0;
 135
 136         /**
 137          * Returns the transport-authenticated identity associated with the request,
 138          * if authentication is solely handled by the transport.
 139          *
 140          * @return the authenticated username or an empty string
 141          */
 142         virtual std::string getRemoteUser() const=0;
 143
 144         /**
 145          * Gets the authentication type associated with the request.
 146          *
 147          * @return  the authentication type or nullptr
 148          */
 149         virtual std::string getAuthType() const {
 150             return "";
 151         }
 152
 153         /**
 154          * Returns the IP address of the client.
 155          *
 156          * @return the client's IP address
 157          */
 158         virtual std::string getRemoteAddr() const=0;
 159
 160         /**
 161          * Returns the chain of certificates sent by the client.
 162          * They are not guaranteed to be valid according to any particular definition.
 163          *
 164          * @return the client's certificate chain
 165          */
 166         virtual const
 167 #ifndef XMLTOOLING_NO_XMLSEC
 168             std::vector<XSECCryptoX509*>&
 169 #else
 170             std::vector<std::string>&
 171 #endif
 172             getClientCertificates() const=0;
 173
 174         /**
 175          * Converts a relative URL into an absolute one based on the properties of the request.
 176          *
 177          * @param url   input URL to convert, will be modified in place
 178          */
 179         virtual void absolutize(std::string& url) const;
 180
 181         /**
 182          * Returns a language range to use in selecting language-specific
 183          * content for this request.
 184          * <p>The syntax is that of the HTTP 1.1 Accept-Language header, even
 185          * if the underlying request is not HTTP.
 186          *
 187          * @return an HTTP 1.1 syntax language range specifier
 188          */
 189         virtual std::string getLanguageRange() const {
 190             return "";
 191         }
 192
 193         /**
 194          * Initializes the language matching process; call this method to begin the
 195          * matching process by calling the matchLang method.
 196          * <p>The language matching process is not thread-safe and must be externally
 197          * syncronized.
 198          *
 199          * @return  true iff language matching is possible
 200          */
 201         bool startLangMatching() const;
 202
 203         /**
 204          * Continues the language matching process; additional calls to matchLang can
 205          * be done as long as this method returns true.
 206          * <p>The language matching process is not thread-safe and must be externally
 207          * syncronized.
 208          *
 209          * @return  true iff more ranges are available to match against
 210          */
 211         bool continueLangMatching() const;
 212
 213         /**
 214          * Matches a language tag against the currently active range.
 215          * <p>The language matching process is not thread-safe and must be externally
 216          * syncronized.
 217          *
 218          * @param tag   a language tag (e.g., an xml:lang value)
 219          * @return  true iff the tag matches the active range
 220          */
 221         bool matchLang(const XMLCh* tag) const;
 222
 223         /**
 224          * Establish default handling of language ranges.
 225          *
 226          * @param langFromClient    honor client's language preferences if any
 227          * @param defaultRange      priority list of space-delimited language tags to use by default
 228          */
 229         static void setLangDefaults(bool langFromClient, const XMLCh* defaultRange);
 230
 231     private:
 232         typedef std::multimap< float,std::vector<xstring> > langrange_t;
 233         mutable langrange_t m_langRange;
 234         mutable langrange_t::const_reverse_iterator m_langRangeIter;
 235         static langrange_t m_defaultRange;
 236         static bool m_langFromClient;
 237     };
 238
 239 #if defined (_MSC_VER)
 240     #pragma warning( pop )
 241 #endif
 242
 243 };
 244
 245 #endif /* __xmltooling_genreq_h__ */