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/base.h>
  31
  32 #include <string>
  33 #include <vector>
  34
  35 #ifndef XMLTOOLING_NO_XMLSEC
  36 # include <xsec/enc/XSECCryptoX509.hpp>
  37 #endif
  38
  39 namespace xmltooling {
  40
  41     /**
  42      * Interface to generic protocol requests that transport XML messages.
  43      *
  44      * <p>This interface need not be threadsafe.
  45      */
  46     class XMLTOOL_API GenericRequest {
  47         MAKE_NONCOPYABLE(GenericRequest);
  48     protected:
  49         GenericRequest();
  50     public:
  51         virtual ~GenericRequest();
  52
  53         /**
  54          * Returns the URL scheme of the request (http, https, ftp, ldap, etc.)
  55          *
  56          * @return the URL scheme
  57          */
  58         virtual const char* getScheme() const=0;
  59
  60         /**
  61          * Returns true iff the request is over a confidential channel.
  62          *
  63          * @return confidential channel indicator
  64          */
  65         virtual bool isSecure() const=0;
  66
  67         /**
  68          * Returns hostname of service that received request.
  69          *
  70          * @return hostname of service
  71          */
  72         virtual const char* getHostname() const=0;
  73
  74         /**
  75          * Returns incoming port.
  76          *
  77          * @return  incoming port
  78          */
  79         virtual int getPort() const=0;
  80
  81         /**
  82          * Returns the MIME type of the request, if known.
  83          *
  84          * @return the MIME type, or an empty string
  85          */
  86         virtual std::string getContentType() const=0;
  87
  88         /**
  89          * Returns the length of the request body, if known.
  90          *
  91          * @return the content length, or -1 if unknown
  92          */
  93         virtual long getContentLength() const=0;
  94
  95         /**
  96          * Returns the raw request body.
  97          *
  98          * @return the request body, or nullptr
  99          */
 100         virtual const char* getRequestBody() const=0;
 101
 102         /**
 103          * Returns a decoded named parameter value from the request.
 104          * If a parameter has multiple values, only one will be returned.
 105          *
 106          * @param name  the name of the parameter to return
 107          * @return a single parameter value or nullptr
 108          */
 109         virtual const char* getParameter(const char* name) const=0;
 110
 111         /**
 112          * Returns all of the decoded values of a named parameter from the request.
 113          * All values found will be returned.
 114          *
 115          * @param name      the name of the parameter to return
 116          * @param values    a vector in which to return pointers to the decoded values
 117          * @return  the number of values returned
 118          */
 119         virtual std::vector<const char*>::size_type getParameters(
 120             const char* name, std::vector<const char*>& values
 121             ) const=0;
 122
 123         /**
 124          * Returns the transport-authenticated identity associated with the request,
 125          * if authentication is solely handled by the transport.
 126          *
 127          * @return the authenticated username or an empty string
 128          */
 129         virtual std::string getRemoteUser() const=0;
 130
 131         /**
 132          * Gets the authentication type associated with the request.
 133          *
 134          * @return  the authentication type or nullptr
 135          */
 136         virtual std::string getAuthType() const {
 137             return "";
 138         }
 139
 140         /**
 141          * Returns the IP address of the client.
 142          *
 143          * @return the client's IP address
 144          */
 145         virtual std::string getRemoteAddr() const=0;
 146
 147         /**
 148          * Returns the chain of certificates sent by the client.
 149          * They are not guaranteed to be valid according to any particular definition.
 150          *
 151          * @return the client's certificate chain
 152          */
 153         virtual const
 154 #ifndef XMLTOOLING_NO_XMLSEC
 155             std::vector<XSECCryptoX509*>&
 156 #else
 157             std::vector<std::string>&
 158 #endif
 159             getClientCertificates() const=0;
 160     };
 161 };
 162
 163 #endif /* __xmltooling_genreq_h__ */