sessionserver.h

Go to the documentation of this file.

#ifndef DVCGI_SESSIONSERVER_H
#define DVCGI_SESSIONSERVER_H
// $Id: sessionserver.h,v 1.15 2004/03/20 14:57:35 dvermeir Exp $

#include <iostream>

#include <dvutil/props.h>
#include <dvnet/usocket.h>
#include <dvnet/userversocket.h>
#include <dvcgi/httphead.h>
/** @file 
 *  Defines SessionServer that allows cgi programs to communicate
 *  with the browser using stream-like operations.
 */

namespace Dv {
namespace Cgi {
/** A class that packages the link to the hidden server. */
class SessionServer: public std::ostream {
public:
  /** Constructor.
   * A Dv::Cgi::SessionServer object must be used in a cgi
   * program.
   * @code
   * Dv::Cgi::SessionServer client("myprog",5*1000, "index.html", "http://tinf2.vub.ac.be/index.html");
   * @endcode
   * - If there is a cookie with the name/key "myprog", its
   * value will be interpreted as the name of a file
   * that corresponds to a unix socket on which a server
   * is listening. 
   * - If a server is listening on that socket, this constructor will simply
   * transfer the cgi formdata, cookies and environment to
   * the server, then copy any input from the server to
   * cout and exit the program.
   * - If no server is running, it will start the server by
   * forking a daemon and then behave as above.
   * The constructor will only return in de server daemon
   * process.
   *
   * The server communicates with its (cgi) clients using
   * a unix socket attached to a filename 
   *    <code>/tmp/program_name.xxx</code>
   * where <code>xxx</code> is generated to make the filename
   * unique.
   *
   * Application code is rather simple: the program communicates
   * with the client (a Dv::Cgi::SessionServer object) using
   * interactions of the form
   * @code
   * client << .. html .. << Dv::Cgi::eof;
   * // now client input is available, e.g. in client.props()
   * if ( client("number") ) {
   *   int number;
   *   client.props() >> "number" >> number;   
   *   ..
   *   }
   * @endcode
   *
   * Note that all C++ variables are persistent (since they
   * reside in the server process). E.g. it is easy to
   * write a login function like so:
   * @code
   * std::string
   * login(Dv::Cgi::SessionServer& client) {
   * while (client) {
   *   client << login_form << Dv::Cgi::eof;
   *   if ( client("name") ) {
   *     std::string uname = client.props("name");
   *     std::string uname = client.props("password");
   *     if (check_password_valid)
   *       return uname;
   *     }
   *   }
   * throw std::runtime_error("login timed out");
   * }
   * @endcode
   *
   * To exit the application use Dv::Cgi::SessionServer::disconnect .
   *
   * Silly example applications are available in the distribution: see
   * test-sessionserver.C and example-session.C .
   *
   * @param program_name used to generate the server unix server socket
   *   filename, also used as the name of the cookie whose value
   *   is the actual server filename.
   * @param delay (in milliseconds) is used by the client and the
   *   server to determine the allowable wait for response.
   * @param timeouturl is used to relocate any request that
   *   suffers from a timeout
   * @param errorurl is used to relocate any request that
   *   suffers from an unrecoverable error (except for timeout)
   * @param logdir directory where logfile will be created
   * @param sockdir directory where sockets will be created
   * @warning do not set a cookie with key/name program_name
   */
  SessionServer(const std::string& program_name, time_t delay,
    const std::string& timeouturl, const std::string& errorurl,
    const std::string& logdir="/tmp", const std::string& sockdir="/tmp");
  /** Destructor. */
  virtual ~SessionServer();

  /** Name of server application. */
  const std::string& name() const { return name_; }

  /** Get props object containing formdata from client. */
  const Util::Props& props() const { return props_; }
  /** Get props object containing formdata from client. */
  Dv::Util::Props&  props() { return props_; }

  /** Easy check for presence of a formdata item. */
  const std::string* operator()(const std::string& key) const { return props().find(key); }
  /** @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 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(); }

  /** Get Props object containing shell environment from client. */
  const Util::Props& env() const { return env_; }
  /** @return value of environment variable.
   * @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() ; }

  /** Get Props object containing cookies from client. */
  const 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::exception) {
    return (cookies()[name]).str() ; }

  /** Return url of current request.
   * @return value of REQUEST_URI in env()
   * @exception std::runtime_error if not available
   * @sa Dv::Cgi::SessionServer::env
   */
  std::string here() const throw (std::runtime_error);
  /** Return base url of current request.
   * @return value of here() without parameters, i.e.
   *   after removing the first '?' and anything following it.
   * @exception std::runtime_error if not available
   * @sa Dv::Cgi::SessionServer::here
   */
  std::string here_base() const throw (std::runtime_error);

  /** Get HttpHeader object containing output headers. */
  const HttpHeader& header() const { return header_; }
  /** Get HttpHeader object containing output headers. */
  HttpHeader& header() { return header_; }
  /** Get HttpHeader object containing output headers. 
   * @deprecated Use <code>session.header().f()</code> instead of 
   *   <code>session->f()</code>.
   */
  HttpHeader* operator->() { return &header_; }

  /** Get status of server. 
   * @retval true iff server is working
   * @retval false otherwise
   */
  operator bool() const { return status_; }

  /** Remove cookie, relocate to url, stop network server and connection.
   * @param url to relocate to
   */
  void  disconnect(const std::string& url);
  /** Stop server and network connection. */
  void  disconnect();
  /** Refresh: send header (if not already sent) and get input from client. */
  void  refresh();

  /** Log stream. 
   * This is a Dv::Util::logstream: each line is automatically prefixed by
   *  the date and the identification of the process.
   * @sa Dv::Cgi::SessionServer::name
   */
  std::ostream&  log() const { return *log_; }

private:
  SessionServer(const SessionServer& s);
  SessionServer& operator=(const SessionServer& s);

  /** Filter class that ensures that header_ is output before
   * anything else. */
  class Filter {
  public:
    Filter(SessionServer& ss);
    int get();
    int put(int c);
    int sync();
    int close() { return 0; }
    int count() const { return count_; }
    void clear() { count_ = 0; }
  private:
    unsigned int count_;
    SessionServer& server_;
  };
  friend class Filter;

  void  send_header();
  void  get_input();

  std::string  name_;
  time_t  delay_;
  std::string  timeouturl_;
  std::string  errorurl_;
  std::string  server_filename_;

  Dv::Net::userversocket* server_socket_;
  Dv::Net::usocket* client_socket_;
  bool  status_;

  Dv::Util::Props  props_;
  Dv::Util::Props  env_;
  Dv::Util::Props  cookies_;

  Dv::Cgi::HttpHeader  header_;

  std::ostream*  log_;
  Filter  filter_;
};

/** Convenience function, simply calls refresh on its argument.
 * 
 *  Example:
 *  @code
 *  Dv::Cgi::SessionServer s(..);
 *
 *  s.header().content_type("text/html").no_cache();
 *
 *  while (s) {
 *    Dv::Util::Props& input(s.props());
 *
 *    s << "<html>..</html>" << Dv::Cgi::eof;
 *    }
 *  @endcode
 * @sa operator<<(std::ostream& os, void (*f)(Dv::Cgi::SessionServer&)
 */
void    eof(SessionServer&);
}}

/** Overloading for SessionServer manipulation.
 * @warning Uses <code>dynamic_cast<SessionServer*>(os)</code> internally.
 * @sa Dv::Cgi::eof
 */
void operator<<(std::ostream& os,void (*f)(Dv::Cgi::SessionServer&));
#endif

---

dvcgi-0.5.14

[22 January, 2006]