Wt::WEnvironment Class Reference

A class that captures information on the application environment. More...

#include <Wt/WEnvironment.h>

Inheritance diagram for Wt::WEnvironment:

Public Types
typedef std::map< std::string, std::string >	CookieMap
	Cookie map. More...

Public Member Functions
const Http::ParameterMap &	getParameterMap () const
	Parameters passed to the application. More...
const Http::ParameterValues &	getParameterValues (const std::string &name) const
	Returns values for a query parameter. More...
const std::string *	getParameter (const std::string &name) const
	Returns a single value for a query parameter. More...
const CookieMap &	cookies () const
	Returns the cookies from the environment. More...
const std::string *	getCookie (const std::string &cookieName) const
	Returns a cookie value. More...
const std::string	headerValue (const std::string &field) const
	Returns a header value. More...
bool	supportsCookies () const
	Returns whether the browser has enabled support for cookies. More...
bool	javaScript () const
	Returns whether the browser has enabled support for JavaScript. More...
bool	ajax () const
	Returns whether the browser has enabled support for AJAX. More...
bool	webGL () const
	Returns whether the browser has support for WebGL. More...
int	screenWidth () const
	Returns the horizontal resolution of the client's screen. More...
int	screenHeight () const
	Returns the vertical resolution of the client's screen. More...
double	dpiScale () const
	Returns the browser-side DPI scaling factor. More...
const WLocale &	locale () const
	Returns the preferred language indicated in the request header. More...
std::chrono::minutes	timeZoneOffset () const
	Returns the time zone offset as reported by the client. More...
std::string	timeZoneName () const
	Returns the time zone name as reported by the client. More...
const std::string &	hostName () const
	Returns the server host name that is used by the client. More...
const std::string &	urlScheme () const
	Returns the URL scheme used for the current request ("http" or "https").
const std::string &	userAgent () const
	Returns the user agent. More...
const std::string &	referer () const
	Returns the referer. More...
const std::string &	accept () const
	Returns the accept header. More...
bool	agentIsSpiderBot () const
	Returns if the user agent is a (known) indexing spider bot. More...
const std::string &	serverSignature () const
	Returns the web server signature. More...
const std::string &	serverSoftware () const
	Returns the web server software. More...
const std::string &	serverAdmin () const
	Returns the email address of the server admin. More...
const std::string &	clientAddress () const
	Returns the IP address of the client. More...
const std::string &	internalPath () const
	Returns the initial internal path. More...
const std::string &	deploymentPath () const
	Returns the deployment path. More...
void	libraryVersion (int &series, int &major, int &minor) const
	Returns the version of the Wt library, broken down. More...
std::string	getCgiValue (const std::string &varName) const
	Returns a raw CGI environment variable. More...
HtmlContentType	contentType () const
	The type of the content provided to the browser. More...
UserAgent	agent () const
	Returns the user agent type. More...
bool	agentIsIE () const
	Returns whether the user agent is Microsoft Internet Explorer. More...
bool	agentIsIElt (int version) const
	Returns whether the user agent is an older version of IE. More...
bool	agentIsIEMobile () const
	Returns whether the user agent is Internet Explorer Mobile. More...
bool	agentIsOpera () const
	Returns whether the user agent is Opera. More...
bool	agentIsWebKit () const
	Returns whether the user agent is WebKit-based. More...
bool	agentIsMobileWebKit () const
	Returns whether the user agent is Mobile WebKit-based. More...
bool	agentIsSafari () const
	Returns whether the user agent is Safari. More...
bool	agentIsChrome () const
	Returns whether the user agent is Chrome. More...
bool	agentIsGecko () const
	Returns whether the user agent is Gecko-based. More...
WServer *	server () const
	Returns the server. More...
WSslInfo *	sslInfo () const
	Returns information on the SSL client certificate or nullptr if no authentication took place. More...
bool	internalPathUsingFragments () const
	Returns whether internal paths are implemented using URI fragments. More...
bool	supportsCss3Animations () const
	Returns whether this agent supports CSS3 animations.
virtual bool	isTest () const
	Returns whether this is a mocked test environment.

Static Public Member Functions
static std::string	libraryVersion ()
	Returns the version of the Wt library. More...

Detailed Description

A class that captures information on the application environment.

The environment provides information on the client, and gives access to startup arguments.

Usage example:

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
std::unique_ptr<Wt::WTextArea> textEdit;
if (!env.ajax())
  textEdit = std::make_unique<Wt::WTextEdit>(); // provide an HTML text editor
else
  textEdit = std::make_unique<Wt::WTextArea>(); // fall-back to a plain old text area.

Member Typedef Documentation

CookieMap

typedef std::map<std::string, std::string> Wt::WEnvironment::CookieMap

Cookie map.

A std::map which associates a cookie name with a cookie value.

See also

cookies()

Member Function Documentation

accept()

const std::string& Wt::WEnvironment::accept

(

)

const

Returns the accept header.

The accept header, as reported in the HTTP Accept field.

agent()

UserAgent Wt::WEnvironment::agent

(

)

const

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).

See also

agentIsIE(), agentIsOpera(), agentIsGecko(), agentIsChrome(), agentIsSafari(), agentIsWebKit()

agentIsChrome()

bool Wt::WEnvironment::agentIsChrome

(

)

const

Returns whether the user agent is Chrome.

See also

agent()

agentIsGecko()

bool Wt::WEnvironment::agentIsGecko

(

)

const

Returns whether the user agent is Gecko-based.

Gecko-based browsers include Firefox.

See also

agent()

agentIsIE()

bool Wt::WEnvironment::agentIsIE

(

)

const

Returns whether the user agent is Microsoft Internet Explorer.

See also

agent()

agentIsIElt()

bool Wt::WEnvironment::agentIsIElt

(

int

version

)

const

Returns whether the user agent is an older version of IE.

Returns whether the agent is an IE version older than the given version.

See also

agentIsIE()

agentIsIEMobile()

bool Wt::WEnvironment::agentIsIEMobile

(

)

const

Returns whether the user agent is Internet Explorer Mobile.

Returns also true when the agent is Internet Explorer 5 or older.

See also

agent()

agentIsMobileWebKit()

bool Wt::WEnvironment::agentIsMobileWebKit

(

)

const

Returns whether the user agent is Mobile WebKit-based.

Mobile Webkit-based browsers include the Android Mobile WebKit and the iPhone Mobile WebKit browsers.

See also

agent()

agentIsOpera()

bool Wt::WEnvironment::agentIsOpera

(

)

const

Returns whether the user agent is Opera.

See also

agent()

agentIsSafari()

bool Wt::WEnvironment::agentIsSafari

(

)

const

Returns whether the user agent is Safari.

See also

agent()

agentIsSpiderBot()

bool Wt::WEnvironment::agentIsSpiderBot

(

)

const

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 id and name attributes are omitted from DOM nodes. In this way, the generated page is always exactly the same.

agentIsWebKit()

bool Wt::WEnvironment::agentIsWebKit

(

)

const

Returns whether the user agent is WebKit-based.

Webkit-based browsers include Safari, Chrome, Arora and Konquerer browsers.

See also

agent()

ajax()

bool Wt::WEnvironment::ajax

(

)

const

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.

See also

javaScript()

clientAddress()

const std::string& Wt::WEnvironment::clientAddress

(

)

const

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.

contentType()

HtmlContentType Wt::WEnvironment::contentType

(

)

const

The type of the content provided to the browser.

This is here for backwards compatibility, but the implementation now alwasy returns HTML5.

cookies()

const CookieMap& Wt::WEnvironment::cookies

(

)

const

Returns the cookies from the environment.

This returns all cookies that were present in initial request for the application. Cookies set with WApplication::setCookie() are not taken into consideration.

Cookies allow you to persist information across sessions, but note that not all clients may support cookies or may some clients may be configured to block cookies.

See also

supportsCookies(), getCookie(), getCookieValue()

deploymentPath()

const std::string & Wt::WEnvironment::deploymentPath

(

)

const

Returns the deployment path.

This is the path at which the application is deployed.

See also

internalPath().

dpiScale()

double Wt::WEnvironment::dpiScale

(

)

const

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.

See also

WVmlImage

getCgiValue()

std::string Wt::WEnvironment::getCgiValue

(

const std::string &

varName

)

const

Returns a raw CGI environment variable.

Retrieves the value for the given CGI environment variable (like "SSL_CLIENT_S_DN_CN"), if it is defined, otherwise an empty string.

See also

serverSignature(), serverSoftware(), serverAdmin(),

getCookie()

const std::string * Wt::WEnvironment::getCookie

(

const std::string &

cookieName

)

const

Returns a cookie value.

Returns 0 if no value was set for the given cookie.

See also

getCookie()

getParameter()

const std::string * Wt::WEnvironment::getParameter

(

const std::string &

name

)

const

Returns a single value for a query parameter.

Returns the first value for a parameter, or 0 if the parameter is not found.

Note

The parameter map will be updated when the page is refreshed (e.g. in non-Ajax sessions and when reload-is-new-session is false), so you will have to make a copy of the returned string if you want to preserve this parameter across different requests.

See also

getParameterValues()

getParameterMap()

const Http::ParameterMap& Wt::WEnvironment::getParameterMap

(

)

const

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.

Note

The parameter map will be updated when the page is refreshed (e.g. in non-Ajax sessions and when reload-is-new-session is false), so you will have to make a copy of values in the parameter map if you want to preserve them across different requests.

See also

getParameterValues()

getParameterValues()

const Http::ParameterValues & Wt::WEnvironment::getParameterValues

(

const std::string &

name

)

const

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 foo.wt started as http://.../foo.wt?hello=Hello&hello=World will result in both values "Hello" and "World" to be associated with the argument "hello".

Note

The parameter map will be updated when the page is refreshed (e.g. in non-Ajax sessions and when reload-is-new-session is false), so you will have to make a copy of these values to preserve it across different requests.

See also

getParameterMap()

headerValue()

const std::string Wt::WEnvironment::headerValue

(

const std::string &

field

)

const

Returns a header value.

Returns a header value, or an empty string if the header was present.

hostName()

const std::string& Wt::WEnvironment::hostName

(

)

const

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:

• www.mydomain.com
• localhost:8080

For HTTP 1.1 requests, this information is fetched from the HTTP Host header. If Wt is configured behind a reverse proxy, then the last entry in the HTTP X-Forwarded-Host header field is used instead (to infer the name of the reverse proxy instead).

For HTTP 1.0 requests, the HTTP Host header is not required. When not present, the server host name is inferred from the configured server name, which defaults to the DNS name.

internalPath()

const std::string& Wt::WEnvironment::internalPath

(

)

const

Returns the initial internal path.

This is the internal path with which the application was started.

For an application deployed at "/stuff/app.wt", the following URL indicates an internal path "/this/there":

http://www.mydomain.com/stuff/app.wt/this/there

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 9.1 Built-in httpd), making clean URLs impossible. Then, also the following URL is supported (assuming deployment at "/stuff/":

http://www.mydomain.com/stuff/?_=/this/there

See also

WApplication::setInternalPath(), deploymentPath()

internalPathUsingFragments()

bool Wt::WEnvironment::internalPathUsingFragments

(

)

const

Returns whether internal paths are implemented using URI fragments.

This may be the case for older non-HTML5 browsers which do not support HTML5 History APIs.

javaScript()

bool Wt::WEnvironment::javaScript

(

)

const

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.

See also

ajax()

libraryVersion() [1/2]

std::string Wt::WEnvironment::libraryVersion ( )

static

Returns the version of the Wt library.

Example: "1.99.2"

libraryVersion() [2/2]

void Wt::WEnvironment::libraryVersion	(	int &	series,
		int &	major,
		int &	minor
	)		const

Returns the version of the Wt library, broken down.

The version of the Wt library, broken down in its three numbers,

Example: series = 1, major = 99, minor = 2.

locale()

const WLocale& Wt::WEnvironment::locale

(

)

const

Returns the preferred language indicated in the request header.

The language is parsed from the HTTP Accept-Language 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.

See also

WApplication::setLocale()

referer()

const std::string& Wt::WEnvironment::referer

(

)

const

Returns the referer.

The referer, as reported in the HTTP Referer field.

screenHeight()

int Wt::WEnvironment::screenHeight

(

)

const

Returns the vertical resolution of the client's screen.

Returns -1 if screen height is not known.

See also

screenWidth()

screenWidth()

int Wt::WEnvironment::screenWidth

(

)

const

Returns the horizontal resolution of the client's screen.

Returns -1 if screen width is not known.

See also

screenHeight()

server()

WServer * Wt::WEnvironment::server

(

)

const

Returns the server.

This returns the server environment of this session.

serverAdmin()

const std::string& Wt::WEnvironment::serverAdmin

(

)

const

Returns the email address of the server admin.

The value of the CGI variable SERVER_ADMIN.

Example: "root@localhost"

serverSignature()

const std::string& Wt::WEnvironment::serverSignature

(

)

const

Returns the web server signature.

The value of the CGI variable SERVER_SIGNATURE.

Example: <address>Apache Server at localhost Port 80</address>.

serverSoftware()

const std::string& Wt::WEnvironment::serverSoftware

(

)

const

Returns the web server software.

The value of the CGI variable SERVER_SOFTWARE.

Example: "Apache"

sslInfo()

WSslInfo* Wt::WEnvironment::sslInfo

(

)

const

Returns information on the SSL client certificate or nullptr if no authentication took place.

This function will return nullptr if no verification took place, Wt was compiled without SSL support, or the web server was configured without client SSL certificates.

This method may return a pointer to a WSslInfo object, while the authentication may have failed. This depends on the configuration of the web server. It is therefore important to always check the verification result with WSslInfo::clientVerificationResult().

Remember that WEnvironment is 'const', thus the object returned by this function will represent the SSL information of the first request for this session. It will not be updated during the lifetime of the session.

The object returned is owned by WEnvironment and will be deleted when WEnvironment is destroyed (= at the end of the session).

Client certificates with wthttp behind a reverse proxy

If Wt is using the wthttp connector and is behind a reverse proxy, Wt can still obtain client certificate information if it is passed through the following headers:

Header	Description	Apache variable	nginx variable	Notes
X-SSL-Client-Verify	Verification state: NONE, SUCCESS, FAILED:reason, or GENEROUS. Only SUCCESS is treated as valid.	%{SSL_CLIENT_VERIFY}s	$ssl_client_verify	Always required
X-SSL-Client-S-DN	Subject DN	%{SSL_CLIENT_S_DN}s	$ssl_client_s_dn	Required if X-SSL-Client-Cert is not present
X-SSL-Client-I-DN	Issuer DN	%{SSL_CLIENT_I_DN}s	$ssl_client_i_dn	Required if X-SSL-Client-Cert is not present
X-SSL-Client-V-Start	Validity Start, formatted like: Oct 29 15:19:20 2019 GMT	%{SSL_CLIENT_V_START}s	$ssl_client_v_start	Required if X-SSL-Client-Cert is not present
X-SSL-Client-V-End	Validity End, formatted like: Oct 29 15:19:20 2019 GMT	%{SSL_CLIENT_V_END}s	$ssl_client_v_end	Required if X-SSL-Client-Cert is not present
X-SSL-Client-Cert	PEM encoded client certificate	%{SSL_CLIENT_CERT}s	$ssl_client_escaped_cert	Required if previous four headers are not present, needs Wt to be built with OpenSSL

Note that the X-SSL-Client-Cert header will significantly increase the size of all requests. If it is not provided, then WSslCertificate::toPem() and WSslCertificate::toDer() will return the empty string. The certificate chain is not passed through, so WSslInfo::clientPemCertificateChain() will be empty. HAProxy also has variables containing client certificate information, but they are in a different format that is not currently supported.

See also

Wt::Http::Request::sslInfo()

supportsCookies()

bool Wt::WEnvironment::supportsCookies

(

)

const

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.

See also

cookies(), getCookie()

timeZoneName()

std::string Wt::WEnvironment::timeZoneName

(

)

const

Returns the time zone name as reported by the client.

Note

This requires JavaScript support and is only supported by browsers that implement the JavaScript Internationalization API. No version of Internet Explorer supports this, but modern browsers do. If not supported, this will return the empty string.

timeZoneOffset()

std::chrono::minutes Wt::WEnvironment::timeZoneOffset

(

)

const

Returns the time zone offset as reported by the client.

This returns the time offset that the client has relative to UTC. A positive value thus means that the local time is ahead of UTC.

This requires JavaScript support.

See also

WLocalDateTime::timeZoneOffset()

userAgent()

const std::string& Wt::WEnvironment::userAgent

(

)

const

Returns the user agent.

The user agent, as reported in the HTTP User-Agent field.

See also

agent()

webGL()

bool Wt::WEnvironment::webGL

(

)

const

Returns whether the browser has support for WebGL.

Support for WebGL is required for client-side rendering of WGLWidget.