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 the MIME type of the request, if known.
  89          *
  90          * @return the MIME type, or an empty string
  91          */
  92         virtual std::string getContentType() const=0;
  93
  94         /**
  95          * Returns the length of the request body, if known.
  96          *
  97          * @return the content length, or -1 if unknown
  98          */
  99         virtual long getContentLength() const=0;
 100
 101         /**
 102          * Returns the raw request body.
 103          *
 104          * @return the request body, or nullptr
 105          */
 106         virtual const char* getRequestBody() const=0;
 107
 108         /**
 109          * Returns a decoded named parameter value from the request.
 110          * If a parameter has multiple values, only one will be returned.
 111          *
 112          * @param name  the name of the parameter to return
 113          * @return a single parameter value or nullptr
 114          */
 115         virtual const char* getParameter(const char* name) const=0;
 116
 117         /**
 118          * Returns all of the decoded values of a named parameter from the request.
 119          * All values found will be returned.
 120          *
 121          * @param name      the name of the parameter to return
 122          * @param values    a vector in which to return pointers to the decoded values
 123          * @return  the number of values returned
 124          */
 125         virtual std::vector<const char*>::size_type getParameters(
 126             const char* name, std::vector<const char*>& values
 127             ) const=0;
 128
 129         /**
 130          * Returns the transport-authenticated identity associated with the request,
 131          * if authentication is solely handled by the transport.
 132          *
 133          * @return the authenticated username or an empty string
 134          */
 135         virtual std::string getRemoteUser() const=0;
 136
 137         /**
 138          * Gets the authentication type associated with the request.
 139          *
 140          * @return  the authentication type or nullptr
 141          */
 142         virtual std::string getAuthType() const {
 143             return "";
 144         }
 145
 146         /**
 147          * Returns the IP address of the client.
 148          *
 149          * @return the client's IP address
 150          */
 151         virtual std::string getRemoteAddr() const=0;
 152
 153         /**
 154          * Returns the chain of certificates sent by the client.
 155          * They are not guaranteed to be valid according to any particular definition.
 156          *
 157          * @return the client's certificate chain
 158          */
 159         virtual const
 160 #ifndef XMLTOOLING_NO_XMLSEC
 161             std::vector<XSECCryptoX509*>&
 162 #else
 163             std::vector<std::string>&
 164 #endif
 165             getClientCertificates() const=0;
 166
 167         /**
 168          * Returns a language range to use in selecting language-specific
 169          * content for this request.
 170          * <p>The syntax is that of the HTTP 1.1 Accept-Language header, even
 171          * if the underlying request is not HTTP.
 172          *
 173          * @return an HTTP 1.1 syntax language range specifier
 174          */
 175         virtual std::string getLanguageRange() const {
 176             return "";
 177         }
 178
 179         /**
 180          * Initializes the language matching process; call this method to begin the
 181          * matching process by calling the matchLang method.
 182          * <p>The language matching process is not thread-safe and must be externally
 183          * syncronized.
 184          *
 185          * @return  true iff language matching is possible
 186          */
 187         bool startLangMatching() const;
 188
 189         /**
 190          * Continues the language matching process; additional calls to matchLang can
 191          * be done as long as this method returns true.
 192          * <p>The language matching process is not thread-safe and must be externally
 193          * syncronized.
 194          *
 195          * @return  true iff more ranges are available to match against
 196          */
 197         bool continueLangMatching() const;
 198
 199         /**
 200          * Matches a language tag against the currently active range.
 201          * <p>The language matching process is not thread-safe and must be externally
 202          * syncronized.
 203          *
 204          * @param tag   a language tag (e.g., an xml:lang value)
 205          * @return  true iff the tag matches the active range
 206          */
 207         bool matchLang(const XMLCh* tag) const;
 208
 209         /**
 210          * Establish default handling of language ranges.
 211          *
 212          * @param langFromClient    honor client's language preferences if any
 213          * @param defaultRange      priority list of space-delimited language tags to use by default
 214          */
 215         static void setLangDefaults(bool langFromClient, const XMLCh* defaultRange);
 216
 217     private:
 218         typedef std::multimap< float,std::vector<xstring> > langrange_t;
 219         mutable langrange_t m_langRange;
 220         mutable langrange_t::const_reverse_iterator m_langRangeIter;
 221         static langrange_t m_defaultRange;
 222         static bool m_langFromClient;
 223     };
 224
 225 #if defined (_MSC_VER)
 226     #pragma warning( pop )
 227 #endif
 228
 229 };
 230
 231 #endif /* __xmltooling_genreq_h__ */