libwt-dev 3.1.10-1ubuntu2 / usr / include / Wt / WEnvironment

// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WENVIRONMENT_H_
#define WENVIRONMENT_H_

#include <string>
#include <map>
#include <vector>

#include <Wt/WDllDefs.h>
#include <Wt/Http/Request>

namespace Wt {

class WAbstractServer;
class WebRequest;
class WebSession;

/*! \class WEnvironment Wt/WEnvironment Wt/WEnvironment
 *  \brief A class that captures information on the application environment.
 *
 * The environment provides information on the client, and gives access
 * to startup arguments.
 *
 * Usage example:
 * \if cpp
 * \code
 * const WEnvironment& env = WApplication::instance()->environment();
 *
 * // read an application startup argument 
 * // (passed as argument in the URL or POST'ed to the application).
 * if (!env.getParameterValues("login").empty()) {
 *   std::string login = env.getParameterValues("login")[0];
 *   ...
 * }
 *
 * // Check for JavaScript/AJAX availability before using AJAX-only
 * // widgets
 * Wt::WTextArea *textEdit;
 * if (!env.ajax())
 *   textEdit = new Wt::WTextEdit(); // provide an HTML text editor
 * else
 *   textEdit = new Wt::WTextArea(); // fall-back to a plain old text area.
 *
 * \endcode
 * \elseif java
 * \code
 * WEnvironment env = WApplication.instance().environment();
 *	 
 * // read an application startup argument 
 * // (passed as argument in the URL or POST'ed to the application).
 * if (!env.getParameterValues("login").isEmpty()) {
 * String login = env.getParameterValues("login").get(0);
 * //...
 * }
 *	 
 * // Check for JavaScript/AJAX availability before using JavaScript-only
 * // widgets
 *  WTextArea textEdit;
 * if (!env.isAjax())
 *   textEdit = new WTextEdit(); // provide an HTML text editor
 * else
 *   textEdit = new WTextArea(); // fall-back to a plain old text area.
 * \endcode
 * \endif
 */
class WT_API WEnvironment
{
public:
  /*! \brief An enumeration type for specific user agent.
   *
   * \sa agent()
   */
  enum UserAgent {
    Unknown = 0,                //!< Unknown user agent
    IEMobile = 1000,            //!< Internet Explorer Mobile, or Internet Explorer 5 or older
    IE6 = 1001,                 //!< Internet Explorer 6
    IE7 = 1002,                 //!< Internet Explorer 7
    IE8 = 1003,                 //!< Internet Explorer 8
    IE9 = 1004,                 //!< Internet Explorer 9 or later
    Opera = 3000,               //!< Opera
    Opera10 = 3010,             //!< Opera 10 or later
    WebKit = 4000,              //!< WebKit
    Safari = 4100,              //!< Safari 2 or older
    Safari3 = 4103,             //!< Safari 3
    Safari4 = 4104,             //!< Safari 4 or later
    Chrome0 = 4200,             //!< Chrome 0
    Chrome1 = 4201,             //!< Chrome 1
    Chrome2 = 4202,             //!< Chrome 2
    Chrome3 = 4203,             //!< Chrome 3
    Chrome4 = 4204,             //!< Chrome 4
    Chrome5 = 4205,             //!< Chrome 5 or later
    Arora = 4300,               //!< Arora
    MobileWebKit = 4400,        //!< Mobile WebKit
    MobileWebKitiPhone = 4450,  //!< Mobile WebKit iPhone/iPad
    MobileWebKitAndroid = 4500, //!< Mobile WebKit Android
    Konqueror = 5000,           //!< Konqueror
    Gecko = 6000,               //!< Gecko
    Firefox = 6100,             //!< Firefox 2 or older
    Firefox3_0 = 6101,          //!< Firefox 3.0
    Firefox3_1 = 6102,          //!< Firefox 3.1
    Firefox3_1b = 6103,         //!< Firefox 3.1b
    Firefox3_5 = 6104,          //!< Firefox 3.5
    Firefox3_6 = 6105,          //!< Firefox 3.6
    Firefox4_0 = 6106,          //!< Firefox 4.0
    Firefox5_0 = 6107,          //!< Firefox 5.0 or later
    BotAgent = 10000            //!< Bot user agent
  };

  /*! \brief Enumeration for HTML content type.
   */
  enum ContentType {
    XHTML1, //!< XHTML1.x
    HTML4   //!< HTML4
  }; 

  /*! \brief Cookie map.
   *
   * A std::map which associates a cookie name with a cookie value.
   *
   * \sa cookies()
   */
  typedef std::map<std::string, std::string> CookieMap;

#ifdef WT_TARGET_JAVA
  /*! \brief Wt's JavaScript scope.
   */
  static std::string javaScriptWtScope() { return WT_CLASS; } 
#endif //WT_TARGET_JAVA

  /*! \brief Parameters passed to the application.
   *
   * Arguments passed to the application, either in the URL for a
   * http GET, or in both the URL and data submitted in a http POST.
   *
   * \sa getParameterValues()
   */
  const Http::ParameterMap& getParameterMap() const { return parameters_; }

  /*! \brief Returns values for a query parameter.
   *
   * Returns an empty list if the parameter was not defined.
   *
   * One or more values may be associated with a single argument.
   *
   * For example a %Wt application <tt>foo.wt</tt> started as
   * <tt>http://.../foo.wt?hello=Hello&hello=World</tt> will result in
   * both values <tt>"Hello"</tt> and <tt>"World"</tt> to be
   * associated with the argument <tt>"hello"</tt>.
   *
   * \sa getParameterMap()
   */
  const Http::ParameterValues& getParameterValues(const std::string& name)
    const;

  /*! \brief Returns a single value for a query parameter.
   *
   * Returns the first value for a parameter, or \c 0 if the parameter is
   * not found.
   *
   * \sa getParameterValues()
   */
  const std::string *getParameter(const std::string& name) const;

  /*! \brief Cookies set in the initial call to the application.
   *
   * Note that cookies set with WApplication::setCookie() are not made
   * available in the environment.
   *
   * Not all clients may support cookies or have cookies enabled.
   *
   * \sa supportsCookies(), getCookie()
   */
  const CookieMap& cookies() const { return cookies_; }

  /*! \brief Checks for existence and returns specified argument.
   *
   * \if cpp
   * Throws a <tt>std::runtime_error("Missing cookie: ...")</tt> when
   * the cookie is missing, or returns cookie value otherwise.
   * \elseif java
   * Throws a <tt>RuntimeException("Missing cookie: ...")</tt> when
   * the cookie is missing, or returns cookie value otherwise.
   * \endif
   */
  const std::string getCookie(const std::string& cookieNname) const;

  /*! \brief Returns a header value.
   *
   * Returns a header value, or an empty string if the header was 
   * present.
   *
   * \note Currently, the header name is case sensitive, although this should
   * not be the case according to RFC2616
   */
  const std::string headerValue(const std::string& field) const;

  /*! \brief Returns whether the browser has enabled support for cookies.
   *
   * When the user disables cookies during the visit of the page, this
   * value is not updated.
   *
   * \sa cookies(), getCookie()
   */
  bool supportsCookies() const { return doesCookies_; }

  /*! \brief Returns whether the browser has enabled support for JavaScript.
   *
   * This is the same as ajax(): %Wt only considers using JavaScript
   * when it has detected AJAX support.
   *
   * \sa ajax()
   */
  bool javaScript() const { return doesAjax_; }

  /*! \brief Returns whether the browser has enabled support for AJAX.
   *
   * Without support for JavaScript/AJAX, %Wt will still be able to
   * serve the application, but with one considerable limitation: only
   * the WTimer::timeout(), WInteractWidget::clicked(),
   * WApplication::internalPathChanged(), and WAbstractArea::clicked()
   * signals (and any derived signals) will generate events.
   *
   * Every event will cause the complete page to be rerendered.
   *
   * \sa javaScript()
   */
  bool ajax() const { return doesAjax_; }

  /*! \brief Returns the browser-side DPI scaling factor
   *
   * Internet Explorer scales all graphics, fonts and other elements
   * on high-density screens to make them readable. This is controlled
   * by the DPI setting of the display. If all goes well, you do not
   * have to worry about this scaling factor. Unfortunately, not
   * all elements are scaled appropriately. The scaling factor is
   * supposed to be used only internally in %Wt and is in this interface
   * for informational purposes.
   *
   * \sa WVmlImage
   */
  double dpiScale() const { return dpiScale_; }

  /*! \brief Returns the preferred language indicated in the request
   *         header.
   *
   * The language is parsed from the HTTP <tt>Accept-Language</tt>
   * field, if present. If not, the locale is empty.
   *
   * If multiple languages are present, the one with the highest
   * "q"uality is assumed, and if a tie is present, the first one
   * is taken.
   *
   * \sa WApplication::setLocale()
   */
  const WT_LOCALE& locale() const { return locale_; }

  /*! \brief Returns the server host name that is used by the client.
   *
   * The hostname is the unresolved host name with optional port number,
   * which the browser used to connect to the application.
   *
   * Examples:
   *   - <tt>www.mydomain.com</tt>
   *   - <tt>localhost:8080</tt>
   *
   * For HTTP 1.1 requests, this information is fetched from the HTTP
   * <tt>Host</tt> header. If %Wt is configured behind a reverse
   * proxy, then the last entry in the HTTP <tt>X-Forwarded-Host</tt>
   * header field is used instead (to infer the name of the reverse
   * proxy instead).
   *
   * For HTTP 1.0 requests, the HTTP <tt>Host</tt> header is not
   * required. When not present, the server host name is inferred from
   * the configured server name, which defaults to the DNS name.
   */
  const std::string& hostName() const { return host_; }

  /*! \brief Returns the URL scheme used for the current request
   * (<tt>"http"</tt> or <tt>"https"</tt>).
   */
  const std::string& urlScheme() const { return urlScheme_; }

  /*! \brief Returns the user agent.
   *
   * The user agent, as reported in the HTTP <tt>User-Agent</tt> field.
   *
   * \sa agent()
   */
  const std::string& userAgent() const { return userAgent_; }

  /*! \brief Returns the referer.
   *
   * The referer, as reported in the HTTP <tt>Referer</tt> field.
   */
  const std::string& referer() const { return referer_; }

  /*! \brief Returns the accept header.
   *
   * The accept header, as reported in the HTTP <tt>Accept</tt> field.
   */
  const std::string& accept() const { return accept_; }

  /*! \brief Returns if the user agent is a (known) indexing spider bot.
   *
   * Note: currently the list of know bots is quite small. This method
   * is used internally to render the web application for optimal
   * indexing by bots:
   * - there is no detection for JavaScript, instead the application is
   *   directly served assuming no JavaScript support.
   * - session information is omitted from the Urls.
   * - no sessions are created (they are immediately stopped after the request
   *   has been handled).
   * - auto-generated <tt>id</tt> and <tt>name</tt> attributes are omitted
   *   from DOM nodes. In this way, the generated page is always exactly the
   *   same.
   */
  bool agentIsSpiderBot() const { return agent_ == BotAgent; }

  /*! \brief Returns the web server signature.
   *
   * The value of the CGI variable <tt>SERVER_SIGNATURE</tt>.
   *
   * Example: <tt>&lt;address&gt;Apache Server at localhost Port 80&lt;/address&gt;</tt>.
   */
  const std::string& serverSignature() const { return serverSignature_; }

  /*! \brief Returns the web server software.
   *
   * The value of the CGI variable <tt>SERVER_SOFTWARE</tt>.
   *
   * Example: <tt>"Apache"</tt>
   */
  const std::string& serverSoftware() const { return serverSoftware_; }

  /*! \brief Returns the email address of the server admin.
   *
   * The value of the CGI variable <tt>SERVER_ADMIN</tt>.
   *
   * Example: <tt>"root@localhost"</tt>
   */
  const std::string& serverAdmin() const { return serverAdmin_; }

  /*! \brief Returns the IP address of the client.
   *
   * The (most likely) IP address of the client that is connected to
   * this session.
   *
   * This is taken to be the first public address that is given in the
   * Client-IP header, or in the X-Forwarded-For header (in case the
   * client is behind a proxy). If none of these headers is present,
   * the remote socket IP address is used. 
   */
  const std::string& clientAddress() const { return clientAddress_; }

#ifndef WT_DEPRECATED_3_0_0
  /*! \brief Returns the path info of the original request (<b>deprecated</b>)
   *
   * \deprecated Use internalPath() instead, which is consistent with the
   *             internal paths generated by %Wt.
   *
   * This is the equivalent of the CGI PATH_INFO environment variable.
   *
   * Assume for example that the application was deployed at
   * <tt>"stuff/app.wt"</tt>. When the user accesses the application
   * using the URL
   * <tt>"http://www.mydomain.com/stuff/app.wt"</tt>, this
   * method would return an empty string (<tt>""</tt>). When the user
   * accesses the site using
   * <tt>"http://www.mydomain.com/stuff/app.wt/this/there"</tt>, the
   * result would be <tt>"/this/there"</tt>.
   *
   * Together with getParameter(), this allows you to supply the
   * application with initial information.
   *
   * \sa getParameter(), internalPath()
   */
  const std::string& pathInfo() const { return pathInfo_; }
#endif // WT_DEPRECATED_3_0_0

  /*! \brief Returns the initial internal path.
   *
   * This is the internal path with which the application was started.
   *
   * For an application deployed at <tt>"/stuff/app.wt"</tt>, the following
   * two URLs are considered equivalent, and indicate an internal path 
   * <tt>"/this/there"</tt>:
   * \code
   * http://www.mydomain.com/stuff/app.wt/this/there
   * http://www.mydomain.com/stuff/app.wt/this/there
   * \endcode
   *
   * \if cpp
   * For the built-in httpd, when the application is deployed at a folder
   * (ending with '/'), only an exact matching path is routed to
   * the application (this can be changed since Wt 3.1.9, see
   * \ref wthttpd), making clean URLs impossible. Then, also the
   * following URL is supported (assuming deployment at <tt>"/stuff/"</tt>:
   * \code
   * http://www.mydomain.com/stuff/?_=/this/there
   * \endcode
   * \endif
   *
   * \sa WApplication::setInternalPath(), deploymentPath()
   */
  const std::string& internalPath() const { return internalPath_; }

  /*! \brief Returns the deployment path.
   *
   * This is the path at which the application is deployed.
   *
   * \sa internalPath().
   */
  const std::string& deploymentPath() const;

  /*! \brief Returns the version of the %Wt library.
   *
   * Example: <tt>"1.99.2"</tt>
   */
  static std::string libraryVersion();

  /*! \brief Returns the version of the %Wt library, broken down.
   *
   * The version of the %Wt library, broken down in its three numbers,
   *
   * Example: <i>series</i> = 1, <i>major</i> = 99, \p minor = 2.
   */
  void libraryVersion(int& series, int& major, int& minor) const;

  /*! \brief Returns the %Wt session id.
   *
   * Retrieves the session id for this session. This is an
   * auto-generated random alpha-numerical id, whose length is
   * determined by settings in the configuration file.
   */
  std::string sessionId() const;

  /*! \brief Returns a raw CGI environment variable.
   *
   * Retrieves the value for the given CGI environment variable (like
   * <tt>"SSL_CLIENT_S_DN_CN"</tt>), if it is defined, otherwise an
   * empty string.
   *
   * \sa serverSignature(), serverSoftware(), serverAdmin(),
   */
  std::string getCgiValue(const std::string& varName) const;

  /*! \brief The type of the content provided to the browser.
   *
   * This is determined by listening to the capabilities of the browser.
   * Xhtml1 is chosen only if the browser reports support for it, and it is
   * allowed in the configuration file (wt_config.xml).
   *
   * Note that %Wt makes also use of common non-standard techniques implemented
   * in every major browser.
   */
  ContentType contentType() const { return contentType_; }

  /*! \brief Returns the user agent type.
   *
   * This returns an interpretation of the userAgent(). It should be
   * used only for user-agent specific work-arounds (as a last
   * resort).
   *
   * \sa agentIsIE(), agentIsOpera(), agentIsGecko(), agentIsChrome(),
   *     agentIsSafari(), agentIsWebKit()
   */
  UserAgent agent() const { return agent_; }

  /*! \brief Returns whether the user agent is Microsoft Internet Explorer.
   *
   * \sa agent()
   */
  bool agentIsIE() const {
    return agent_ >= IEMobile && agent_ < Opera;
  }

  /*! \brief Returns whether the user agent is an older version of IE
   *
   * Returns whether the agent is an IE version older than the given version.

   * \sa agentIsIE()
   */
  bool agentIsIElt(int version) const {
    if (agentIsIE())
      return agent_ < IEMobile + (version - 5);
    else
      return false;
  }

  /*! \brief Returns whether the user agent is Internet Explorer Mobile.
   *
   * Returns also \c true when the agent is Internet Explorer 5 or older.
   *
   * \sa agent()
   */
  bool agentIsIEMobile() const {
    return agent_ == IEMobile;
  }

  /*! \brief Returns whether the user agent is Opera.
   *
   * \sa agent()
   */
  bool agentIsOpera() const {
    return agent_ >= Opera && agent_ < Safari;
  }

  /*! \brief Returns whether the user agent is WebKit-based.
   *
   * Webkit-based browsers include Safari, Chrome, Arora and Konquerer
   * browsers.
   *
   * \sa agent()
   */
  bool agentIsWebKit() const {
    return agent_ >= WebKit && agent_ < Konqueror;
  }

   /*! \brief Returns whether the user agent is Mobile WebKit-based.
   *
   * Mobile Webkit-based browsers include the Android Mobile WebKit
   * and the iPhone Mobile WebKit browsers.
   *
   * \sa agent()
   */
  bool agentIsMobileWebKit() const {
    return agent_ >= MobileWebKit && agent_ < Konqueror;
  }

  /*! \brief Returns whether the user agent is Safari.
   *
   * \sa agent()
   */
  bool agentIsSafari() const {
    return agent_ >= Safari && agent_ < Chrome0;
  }

  /*! \brief Returns whether the user agent is Chrome.
   *
   * \sa agent()
   */
  bool agentIsChrome() const {
    return agent_ >= Chrome0 && agent_ < Konqueror;
  }
  
  /*! \brief Returns whether the user agent is Gecko-based.
   *
   * Gecko-based browsers include Firefox.
   *
   * \sa agent()
   */
  bool agentIsGecko() const {
    return agent_ >= Gecko && agent_ < BotAgent;
  }

#ifndef WT_TARGET_JAVA
  /** \brief Returns the server.
   */
  WAbstractServer *server() const;
#endif // WT_TARGET_JAVA

  bool hashInternalPaths() const { return hashInternalPaths_; }

  bool supportsCss3Animations() const;

protected:
  WebSession *session_;
  bool        doesAjax_;
  bool        doesCookies_;
  bool        hashInternalPaths_;
  UserAgent   agent_;
  double      dpiScale_;
  ContentType contentType_;

  Http::ParameterMap parameters_;
  CookieMap   cookies_;

  WT_LOCALE locale_;
  std::string host_;
  std::string userAgent_;
  std::string urlScheme_;
  std::string referer_;
  std::string accept_;
  std::string serverSignature_;
  std::string serverSoftware_;
  std::string serverAdmin_;
  std::string clientAddress_;
  std::string pathInfo_;
  std::string internalPath_;

  WEnvironment();
  void setUserAgent(const std::string& agent);
  void setInternalPath(const std::string& path);
 
private:
  WEnvironment(WebSession *session);

  void init(const WebRequest& request);

  std::string parsePreferredAcceptValue(const std::string& value);
  void        parseCookies(const std::string& value);
  bool        agentSupportsAjax() const;

  friend class WebController;
  friend class WebSession;
  friend class WApplication;
};

}

#endif // WENVIRONMENT_H_