cgi.h

Go to the documentation of this file.

#ifndef DVCGI_CGI_H
#define DVCGI_CGI_H
// $Id: cgi.h,v 1.23 2005/07/06 09:17:31 dvermeir Exp $
#include <iostream>

#include <dvutil/props.h>
#include <dvutil/logstream.h>
#include <dvcgi/cgierror.h>
#include <dvcgi/httphead.h>

/** The Dv namespace is shared by all dvxyz packages. */
namespace Dv { 
/** Dv::Cgi is the namespace for this package. */
namespace Cgi {

/** @file 
 * The class Cgi serves as an I/O interface for a cgi
 * application. It is a thin wrapper around lower level (but reusable)
 * facilities.
 */


/** A wrapper class that represents the http interface to a cgi
 * program.  The constructor stores any form data and cookies in a
 * property list. Dv::Cgi::operator<<(ostream&,const Dv::Cgi::Cgi& )
 * outputs the header lines set in Cgi::header().
 *
 *  A typical usage could be:
 *
 *  @code
 *  try {
 *    Cgi cgi("myapplication.cgi");
 *    cgi.header().content_type("text/plain");
 *    cgi << cgi.props() << endl;
 *    }
 *  catch (std::exception& e) {
 *    cerr << e.what() << endl;
 *    }
 *  @endcode
 */
class Cgi: public std::ostream {
public:
  /** Constructor takes encoding type of response as parameter.
   * @param name of application, will be used as a prefix in
   *   output to cgi.log() [i.e. the http server log file]
   * @param reply_format default is "text/html"
   * @param debug flag to be passed to Dv::Cgi::HttpHeader
   *
   * The constructor does not throw any exception. This supports the
   * following template code.
   *  @code
   *   Cgi cgi("myapplication.cgi", "text/html", true);
   *   try {
   *     }
   *   catch (exception& e) {
   *     cgi.header().content_type("text/plain");
   *     cgi << e.what();
   *     }
   *  @encode
   *
   *  which ensure that there is always proper output to cout.
   *
   *  Even the following will work because the destructor will
   *  output something.
   *
   *  @code
   *  {
   *  Cgi cgi("myapplication.cgi");
   *  try {
   *    }
   *  catch (std::exception& e) {
   *    }
   *  } // Cgi::~Cgi() will output something.
   *  @endcode
  */
  Cgi(const std::string& name, const std::string& reply_format="text/html",
    bool debug=false) throw ();

  /** Destructor.  The destructor will output a header and some
   * standard error message, if nothing else was output yet.  */
  virtual ~Cgi();

  /** @return form data in Dv::Util::Props form */
  const Dv::Util::Props&  props() const { return formdata_; }
  /** @return value of form data variable 
   * @exception std::runtime_error if variable is not defined
   */
  const std::string& props(const std::string& name) const throw (std::runtime_error) {
    return props()[name].str(); 
    }
  /** @return form data in Dv::Util::Props form */
  Dv::Util::Props&  props() { return formdata_; }
  /** @return value of form data variable 
   * @exception std::runtime_error if variable is not defined
   */
  std::string& props(const std::string& name) throw (std::runtime_error) { return props()[name].str(); }
  /** @return cookies in Dv::Util::Props form */
  const Dv::Util::Props&  cookies() const { return cookies_; }
  /** @return value of cookie variable 
   * @exception std::runtime_error if variable is not defined
   */
  const std::string&  cookies(const std::string& name) const throw (std::runtime_error) {
    return (cookies()[name]).str() ; }
  /** @return environment (REQUEST_URI etc.) in Dv::Util::Props form */
  const Util::Props&  env() const { return env_; }
  /** @return value of environment variable (REQUEST_URI etc.)
   * @exception std::runtime_error if variable is not defined
   */
  const std::string&  env(const std::string& name) const throw (std::runtime_error) {
    return (env()[name]).str() ; }

  /** Easy access to HttpHeader
   * @return pointer to HTTP header object.
   * @deprecated Use cgi.header().f().g().
   * @sa Dv::Cgi::Cgi::header
   */
  HttpHeader* operator->() { return &header_; }
  /** Easy check for formdata.
   * @param key of value in formdata.
   * @return value associated with key or 0 if none found.
   */
  const std::string* operator()(const std::string& key) const { return props().find(key); }

  /** @return raw data as received from HTTP server */
  const std::string& data() const { return data_; }

  /** @return HTTP header. */
  HttpHeader& header() { return header_; }
  /** @return HTTP header (const version). */
  const HttpHeader& header() const { return header_; }

  /** @return name (constructor parameter) of the program.
   * @sa Dv::Cgi::Cgi::Cgi */
  const std::string& name() const { return name_; }

  /** @return log stream
   * This logstream is linked to cerr. The prefix is the name of the program.
   * @sa Dv::Cgi::Cgi::Cgi */
  std::ostream& log() { return log_; }

  /** @return this url.
   * The return value is the string obtained from the environment
   * variable REQUEST_URI.
   */
  const std::string&  here() const { return here_; }
  /** @return this url without arguments. 
   * The return value is obtained from the result of
   * Dv::Cgi::Cgi::here by removing everything after the first
   * occurrence of '?'.
   * @sa Dv::Cgi::Cgi::here
   */
  const std::string&  here_base() const {return here_base_; }
  /** @return client host dot address.
   * The return value is the value of the REMOTE_ADDR environment
   * variable. If the client host is the localhost, the real "dot
   * address" of this host is returned.
   */
  const std::string&  client_host() const { return client_host_; }
  /** @return client host name.
   * The return value is obtained from the result of
   * Dv::Cgi::Cgi::client_host by resolving the result.
   * @sa Dv::Cgi::Cgi::client_host
   */
  const std::string&  client_host_name() const { return client_host_name_; }
  /** @return dot address of this host.
   * The return value is the value of the SERVER_ADDR environment
   * variable. 
   */
  const std::string&  this_host() const { return this_host_; }
  /** @return name of this host.
   * The return value is obtained from the SERVER_NAME environment
   * variable or, if this variable is not available, resolving the result of
   * Dv::Cgi::Cgi::this_host.
   * @sa Dv::Cgi::Cgi::this_host
   */
  const std::string&  this_host_name() const { return this_host_name_; }

  /** Print props as url-arguments. 
   * Convert a property list of a string suitable for inclusion in 
   * a url. E.g. abc=123&key=blabla. Both keys and values will
   * be encoded using Dv::Cgi::www_encode.
   * @param props property list to be printed as url arguments
   * @return string suitable for appending to a url as arguments 
   * @sa Dv::Util::Props Dv::Cgi::www_encode
   */
  static std::string props_as_url_args(const Dv::Util::Props& props);

  /** Extend the base url of this Cgi object with formdata from props.
   * @param props property list to be printed as url arguments of here_base().
   * @return here_base() + "?" + props_as_url_args(props) 
   * @sa Dv::Cgi::Cgi::props_as_url_args Dv::Cgi::Cgi::here_base
   */
  std::string url(const Dv::Util::Props& props) const;

  /** Extend a url with arguments from props.
   * @param url url to be extended
   * @param props property list to be added to this url
   * @return url extended with arguments from props.
   * @warning the input url should not contain a fragment ('#') and
   *  probably should not end with '/'.
   * @sa Dv::Cgi::Cgi::props_as_url_args
   */
  static std::string url(const std::string& url, const Dv::Util::Props& props);

  /** Write debug info on output stream. */
  void debug(std::ostream& os) const;
private:

  /** Filter class which ensures that header_ is output before
   * anything else. */
  class Filter {
  public:
    Filter(Cgi&);
    int get();
    int put(int c);
    int sync();
    void close();
    int count() const { return count_; }
  private:
    unsigned int count_;
    Cgi& cgi_;
  };
  const std::string name_;
  Filter  filter_;
  Dv::Util::Props  cookies_;
  Dv::Util::Props  env_;
  Dv::Util::Props  formdata_;
  std::string  data_;
  Dv::Util::logstream  log_;
  /** url of this program */
  std::string  here_;
  /** base of url of this program: anything before '?' */
  std::string  here_base_;
  /** dot address of client host */
  std::string  client_host_;
  /** name of client host */
  std::string  client_host_name_;
  /** dot address of this host */
  std::string  this_host_;
  /** name of this host */
  std::string  this_host_name_;
  /** header to be sent before reply */
  Dv::Cgi::HttpHeader  header_;
};

}}
#endif

---

dvcgi-0.5.14

[22 January, 2006]