1. renamed url_escape/unescape to encode/decode

2. introduced a number of wrappers for accessing meta-variables mentioned in RFC3875
3. bumped library version info

3 files changed, 149 insertions, 12 deletions

diff --git a/include/kingate/cgi_gateway.h b/include/kingate/cgi_gateway.h
index f683580..a5c4056 100644
--- a/include/kingate/cgi_gateway.h
+++ b/include/kingate/cgi_gateway.h
@@ -1,164 +1,269 @@
 #ifndef __KINGATE_CGI_GATEWAY_H
 #define __KINGATE_CGI_GATEWAY_H
 
 #include <map>
 #include "kingate/cgi_interface.h"
 
+#ifndef __deprecated
+#if ( __GNUC__ == 3 && __GNUC_MINOR__ > 0 ) || __GNUC__ > 3
+#define __deprecated    __attribute__((deprecated))
+#else
+#define __deprecated
+#endif
+#endif
+
 /**
  * @file
  * @brief the cgi_gateway -- main interface to CGI.
  */
 
 namespace kingate {
     using namespace std;
 
     /**
      * The main class interfacing with the CGI environment.
      */
     class cgi_gateway {
         public:
             /**
              * The interface to CGI environment (e.g. fastcgi).
              */
             cgi_interface& iface;
             /**
              * The type describing map holding parameters parsed from query string or input.
              */
             typedef multimap<string,string> params_t;
             /**
              * The GET-passed parameters.
              */
             params_t get;
             /**
              * The POST-passed parameters.
              */
             params_t post;
             /**
              * Was the stdin content parsed?
              */
             bool b_parsed_content;
 
             /**
              * @param ci the interface to use.
              */
             cgi_gateway(cgi_interface& ci);
 
             /**
              * Check whether there is an 'environment' meta-variable with specific name
              * passed to CGI.
              * @param n variable name.
              * @return true if yes.
              * @see cgi_interface::has_meta()
              * @see get_meta()
              */
             bool has_meta(const string& n) const { return iface.has_meta(n); }
             /**
              * Retrieve the 'environment' meta-variable value.
              * @param n variable name.
              * @return variable contents.
              * @see exception_notfound
              * @see cgi_interface::get_meta()
              */
-            string get_meta(const string& n) const { return iface.get_meta(n); }
+            const string& get_meta(const string& n) const { return iface.get_meta(n); }
 
             /**
              * fetch reference to the 'stdin' stream.
              * @return the reference to the corresponding istream object.
              * @see cgi_interface::in()
              */
             istream& in() { return iface.in(); }
             /**
              * fetch reference to the 'stdout' stream.
              * @return the reference to the corresponding ostream object.
              * @see cgi_interface::out()
              */
             ostream& out() { return iface.out(); }
             /**
              * fetch reference to the 'stderr' stream.
              * @return the reference to the corresponding ostream object.
              * @see cgi_interface::err()
              */
             ostream& err() { return iface.err(); }
             /**
              * cast to the ostream -- fetches the reference to the 'stdout'
              * stream.
              * @see out()
              */
             operator ostream& (void) { return out(); }
 
             /**
              * Check to see whether the parameter was passed via GET.
              * @param n the parameter name.
              * @return true if yes.
              */
             bool has_GET(const string& n) const;
             /**
              * Retrieve the parameter passed via GET.
              * @param n the parameter name.
              * @return the parameter contents.
              * @see exception_notfound
              */
-            string get_GET(const string& n) const;
+            const string& get_GET(const string& n) const;
             /**
              * Check to see whether the parameter was passed via POST.
              * @param n the parameter name.
              * @return true if yes.
              */
             bool has_POST(const string& n) const;
             /**
              * Retrieve the POST-parameter.
              * @param n the parameter name.
              * @return the parameter contents.
              * @see exception_notfound
              */
-            string get_POST(const string& n) const;
+            const string& get_POST(const string& n) const;
             /**
              * Check to see whether the parameter was passed either via POST or
              * GET.
              * @param n the parameter name.
              * @return true if yes.
              */
             bool has_param(const string& n) const;
             /**
              * Retrieve the parameter passed either via POST or GET
              * (GET-parameter takes precedence).
              * @param n the parameter name.
              * @return true if yes.
              * @see exception_notfound.
              */
-            string get_param(const string& n) const;
+            const string& get_param(const string& n) const;
 
             /**
              * Retrieve the POST content-type (as passed via CONTENT_TYPE
              * environment variable).
              * @return the content type.
              */
-            const string& get_content_type() const;
+            const string& __deprecated get_content_type() const;
             /**
              * Retrieve the POST content length (as passed via the
              * CONTENT_LENGTH environment variable).
              * @return the content length.
              */
-            unsigned long get_content_length() const;
+            unsigned long __deprecated get_content_length() const;
 
             /**
              * Check to see whether the content from stdin stream was parsed.
              * @return true if yes.
              */
             bool is_content_parsed() const { return b_parsed_content; }
+
+            /**
+             * Retrieve the HTTP header value from the HTTP_ meta-variable.
+             * (see RFC3875)
+             * @param hn header field name.
+             * @return the HTTP header value.
+             */
+            const string& http_request_header(const string& hn) const;
+
+            /**
+             * Retrieve the AUTH_TYPE meta-variable (see RFC3875)
+             * @return authentication type.
+             */
+            const string& auth_type() const;
+            /**
+             * Retrieve the CONTENT_LENGTH meta-variable (see RFC3875)
+             * @return size of the request message body.
+             */
+            unsigned long cgi_gateway::content_length() const;
+            /**
+             * Retrieve the CONTENT_TYPE meta-variable (see RFC3875)
+             * @return media type of the request message body.
+             */
+            const string& content_type() const;
+            /**
+             * Retrieve the GATEWAY_INTERFACE meta-variable (see RFC3875)
+             * @return the gateway interface dialect.
+             */
+            const string& gateway_interface() const;
+            /**
+             * Retrieve the PATH_INFO meta-variable (see RFC3875)
+             * @return path to be interpreted by the script.
+             */
+            const string& path_info() const;
+            /**
+             * Retrieve the PATH_TRANSLATED meta-variable (see RFC3875)
+             * @return the translated path to the document.
+             */
+            const string& path_translated() const;
+            /**
+             * Retrieve the QUERY_STRING meta-variable (see RFC3875)
+             * @return the query string.
+             */
+            const string& query_string() const;
+            /**
+             * Retrieve the REMOTE_ADDR meta-variable (see RFC3875)
+             * @return the network address of the remote host.
+             */
+            const string& remote_addr() const;
+            /**
+             * Retrieve the REMOTE_HOST meta-variable (see RFC3875)
+             * @return the fully qualified domain name of the client if
+             * available. REMOTE_ADDR otherwise.
+             * @see remote_addr()
+             */
+            const string& remote_host() const;
+            /**
+             * Retrieve the REMOTE_IDENT meta-variable (see RFC3875)
+             * @return remote user identity (see RFC1413).
+             */
+            const string& remote_ident() const;
+            /**
+             * Retrieve the REMOTE_USER meta-variable (see RFC3875)
+             * @return the authenticated user name.
+             */
+            const string& remote_user() const;
+            /**
+             * Retrieve the REQUEST_METHOD meta-variable (see RFC3875)
+             * @return the http request method.
+             */
+            const string& request_method() const;
+            /**
+             * Retrieve the SCRIPT_NAME meta-variable (see RFC3875)
+             * @return the uri path identifying the script.
+             */
+            const string& script_name() const;
+            /**
+             * Retrieve the SERVER_NAME meta-variable (see RFC3875)
+             * @return the server name of the script.
+             */
+            const string& server_name() const;
+            /**
+             * Retrieve the SERVER_PORT meta-variable (see RFC3875)
+             * @return the port on which request was received.
+             */
+            unsigned int server_port() const;
+            /**
+             * Retrieve the SERVER_PROTOCOL meta-variable (see RFC3875)
+             * @return the protocol used for the request.
+             */
+            const string& server_protocol() const;
+            /**
+             * Retrieve the SERVER_SOFTWARE meta-variable (see RFC3875)
+             * @return the name and version of server software.
+             */
+            const string& server_software() const;
+
         private:
             /**
              * Parse the query string, putting the parameters into the map
              * specified.
              * @param q the query string.
              * @param p destination parameters map.
              */
             static void parse_query(string& q,params_t& p);
     };
 
 }
 
 #endif /* __KINGATE_CGI_GATEWAY_H */
 /*
  * vim:set ft=cpp:
  */
diff --git a/include/kingate/exception.h b/include/kingate/exception.h
index 6ebb361..85d89ea 100644
--- a/include/kingate/exception.h
+++ b/include/kingate/exception.h
@@ -1,44 +1,53 @@
 #ifndef __KINGATE_EXCEPTION_H
 #define __KINGATE_EXCEPTION_H
 
 #include <stdexcept>
 #include <konforka/exception.h>
 
 /**
  * @file
  * @brief The kingate-specific exceptions.
  */
 
 /**
  * @brief the main kingate namespace.
  */
 namespace kingate {
     using namespace std;
 
     /**
      * The base for kingate-specific exception.
      */
     class exception : public konforka::exception {
         public:
             explicit exception(const string& w)
                 : konforka::exception(NOCODEPOINT,w) { }
             exception(const string& fi,const string& fu,int l,const string &w)
                 : konforka::exception(fi,fu,l,w) { }
     };
 
     /**
      * Thrown if the specified variable or parameter wasn't found.
      */
     class exception_notfound : public exception {
         public:
             explicit exception_notfound(const string& w)
                 : exception(w) { }
             exception_notfound(const string& fi,const string& fu,int l,const string& w)
                 : exception(fi,fu,l,w) { }
     };
+
+    /**
+     * Thrown in case of unexpected server behaviour.
+     */
+    class server_error : public exception {
+        public:
+            server_error(const string& fi,const string& fu,int l,const string& w)
+                : exception(fi,fu,l,w) { }
+    };
 }
 
 #endif /* __KINGATE_EXCEPTION_H */
 /*
  * vim:set ft=cpp:
  */
diff --git a/include/kingate/util.h b/include/kingate/util.h
index 4b0dca8..6024ccf 100644
--- a/include/kingate/util.h
+++ b/include/kingate/util.h
@@ -1,26 +1,49 @@
 #ifndef __KINGATE_UTIL_H
 #define __KINGATE_UTIL_H
 
 #include <string>
 
+#ifndef __deprecated
+#if ( __GNUC__ == 3 && __GNUC_MINOR__ > 0 ) || __GNUC__ > 3
+#define __deprecated    __attribute__((deprecated))
+#else
+#define __deprecated
+#endif
+#endif
+
 namespace kingate {
     using namespace std;
 
     /**
-     * Escape string for passing via URL.
-     * @param str string unescaped.
-     * @return the escaped string.
+     * Encode string for passing via URL.
+     * @param str string unencoded.
+     * @return the encoded string.
      */
-    string url_escape(const string& str);
+    string url_encode(const string& str);
     /**
      * Remove URL-encoding from the string.
      * @param str the URL-encoded string.
-     * @return the unescaped string.
+     * @return the decoded string.
+     */
+    string url_decode(const string& str);
+
+    /**
+     * deprecated alias to url_encode.
+     * @see url_encode
+     */
+    inline string __deprecated url_escape(const string& str) {
+        return url_encode(str);
+    }
+    /**
+     * deprecated alias to url_decode.
+     * @see url_decode
      */
-    string url_unescape(const string& str);
+    inline string __deprecated url_unescape(const string& str) {
+        return url_decode(str);
+    }
 }
 
 #endif /* __KINGATE_UTIL_H */
 /*
  * vim:set ft=cpp:
  */