Wt: Wt::Http::Request Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | List of all members
Wt::Http::Request Class Reference
HTTP protocol (Wt::Http)

A resource request. More...

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

## Classes
class | ByteRange
| A single byte range. More...
class | ByteRangeSpecifier
| A byte range specifier. More...

## Public Types
typedef std::map< std::string, std::string > | CookieMap
| Cookie map type.

## Public Member Functions
const ParameterMap & | getParameterMap () const
| Returns the query parameters.
const UploadedFileMap & | uploadedFiles () const
| Returns uploaded file parameters.
const ParameterValues & | getParameterValues (const std::string &name) const
| Returns all values for a query parameter.
const std::string * | getParameter (const std::string &name) const
| Returns a query parameter value.
const UploadedFile * | getUploadedFile (const std::string &name) const
| Returns an uploaded file.
::int64_t | tooLarge () const
| Returns a non-zero value that exceeded the maximum allowed request.
ResponseContinuation * | continuation () const
| Returns a continuation object.
std::string | serverName () const
| Returns the (public) server name.
std::string | serverPort () const
| Returns the server port.
std::string | path () const
| Returns the request path.
std::string | pathInfo () const
| Returns the request path info.
std::string | queryString () const
| Returns the request query string.
std::string | urlScheme () const
| Returns the url scheme used.
std::istream & | in () const
| Returns the input stream for parsing the body.
std::string | contentType () const
| Returns the "Content Type" of the request body.
int | contentLength () const
| Returns the "Content Length" of the request body.
std::string | userAgent () const
| Returns the user agent.
std::string | clientAddress () const
| Returns the IP address of the client.
std::string | hostName () const
| Returns the host name used in the request.
const CookieMap & | cookies () const
| Returns the cookies.
const std::string * | getCookieValue (const std::string &cookieName) const
| Returns a cookie value.
std::string | headerValue (const std::string &field) const
| Returns a header value.
std::vector< Message::Header > | headers () const
| Returns all headers.
std::string | getCgiValue (const std::string &varName) const
| Returns a raw CGI environment variable.
std::string | method () const
| Returns the request method.
ByteRangeSpecifier | getRanges (::int64_t filesize) const
| Returns the requested ranges as in the HTTP Range header.
WSslInfo * | sslInfo () const
| Returns information on the SSL client certificate or `nullptr` if no authentication took place.
std::string | urlParam (const std::string &param) const
| Get the value for the given URL parameter.
const std::vector< std::pair< std::string, std::string > > & | urlParams () const
| Get all URL parameters.

## Detailed Description

A resource request.

The request provides information of parameters, including uploaded files, that were present in a request to a WResource.

See also
  WResource::handleRequest()

## Member Typedef Documentation

## ◆ CookieMap

std::map<std::string, std::string> Wt::Http::Request::CookieMap

Cookie map type.

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

See also
  cookies()

## Member Function Documentation

## ◆ clientAddress()

std::string Wt::Http::Request::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.

## ◆ contentLength()

int Wt::Http::Request::contentLength | ( |  | ) | const

Returns the "Content Length" of the request body.

See also
  in()

## ◆ contentType()

std::string Wt::Http::Request::contentType | ( |  | ) | const

Returns the "Content Type" of the request body.

See also
  in()

## ◆ continuation()

ResponseContinuation * Wt::Http::Request::continuation | ( |  | ) | const

Returns a continuation object.

Returns a non-zero continuation object if the request is a continuation request for an earlier response for which a continuation was created.

See also
  Response::createContinuation()

## ◆ cookies()

const CookieMap & Wt::Http::Request::cookies | ( |  | ) | const

Returns the cookies.

This returns all cookies set for this request.

Not all clients may support cookies or have cookies enabled.

See also
  getCookieValue()

## ◆ getCgiValue()

std::string Wt::Http::Request::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.

## ◆ getCookieValue()

const std::string * Wt::Http::Request::getCookieValue | ( | const std::string & | cookieName | ) | const

Returns a cookie value.

Returns `nullptr` if no value was set for the given cookie.

See also
  cookies()

## ◆ getParameter()

const std::string * Wt::Http::Request::getParameter | ( | const std::string & | name | ) | const

Returns a query parameter value.

Returns the first value defined for a parameter named `name` or `nullptr` if the paramter does not exist.

## ◆ getParameterMap()

const ParameterMap & Wt::Http::Request::getParameterMap | ( |  | ) | const

Returns the query parameters.

Returns parameters that were passed to the query, either inside the URL, or inside a POST request, excluding uploaded files.

See also
  uploadedFiles()

## ◆ getParameterValues()

const ParameterValues & Wt::Http::Request::getParameterValues | ( | const std::string & | name | ) | const

Returns all values for a query parameter.

Returns all values defined for a parameter named `name`. A single parameter may have multiple values, e.g. in the query string '?param=value1&param=value2'.

Returns an empty list if the query parameter does not exist.

## ◆ getRanges()

ByteRangeSpecifier Wt::Http::Request::getRanges | ( | ::int64_t | filesize | ) | const

Returns the requested ranges as in the HTTP Range header.

The filesize is used to adapt the ranges to the actual file size as per rules of RFC 2616. If the file size is unknown, pass -1.

You should check if the ranges are satisfiable using ByteRangeSpecifier::isSatisfiable().

## ◆ getUploadedFile()

const UploadedFile * Wt::Http::Request::getUploadedFile | ( | const std::string & | name | ) | const

Returns an uploaded file.

Returns the file uploaded for a parameter named `name` or `nullptr` if the parameter does not contain does not exist or was not associated with a file input field.

## ◆ headers()

std::vector< Message::Header > Wt::Http::Request::headers | ( |  | ) | const

Returns all headers.

Note
  Use headerValue() if you need to know the value of certain known headers. This method is not written to be efficient, but can be useful for debugging.

## ◆ headerValue()

std::string Wt::Http::Request::headerValue | ( | const std::string & | field | ) | const

Returns a header value.

Returns an empty string if the header was not present.

## ◆ hostName()

std::string Wt::Http::Request::hostName | ( |  | ) | const

Returns the host name used in the request.

This returns the value of the Host header, or if behind a trusted reverse proxy, the value of the X-Forwarded-Host header if it is present.

## ◆ in()

std::istream & Wt::Http::Request::in | ( |  | ) | const

Returns the input stream for parsing the body.

If the request was a POST with as contentType() "application/x-www-form-urlencoded" or "multipart/form-data", the input stream will already have been consumed by Wt's CGI parser, and made available as parameters in the request.

## ◆ method()

std::string Wt::Http::Request::method | ( |  | ) | const

Returns the request method.

Returns the HTTP request method ("GET", "POST", or other).

## ◆ path()

std::string Wt::Http::Request::path | ( |  | ) | const

Returns the request path.

Returns the path at which this request was received (excluding internal path information): it is the path at which the application or resource is deployed.

See also
  pathInfo()

## ◆ pathInfo()

std::string Wt::Http::Request::pathInfo | ( |  | ) | const

Returns the request path info.

Returns additional path information internal to the path().

See also
  pathInfo()

## ◆ serverName()

std::string Wt::Http::Request::serverName | ( |  | ) | const

Returns the (public) server name.

Returns the public server name. This is the server name that is advertised to outside, which is determined in a OS specific way.

See also
  serverPort()

## ◆ serverPort()

std::string Wt::Http::Request::serverPort | ( |  | ) | const

Returns the server port.

Returns the server port number through which this request was received.

See also
  serverName()

## ◆ sslInfo()

WSslInfo * Wt::Http::Request::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().

Session-bound resources will probably not use this method, but rely on the validation done at the start of the session (see sslInfo() in WEnvironment). Static resources on the other hand don't have an associated session, so using this method you can perform client authentication verification.

The object returned is owned by Request and will be deleted when the Request object is destroyed.

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
  WEnvironment::sslInfo()

## ◆ tooLarge()

::int64_t Wt::Http::Request::tooLarge | ( |  | ) | const

Returns a non-zero value that exceeded the maximum allowed request.

See also
  WApplication::requestTooLarge

## ◆ uploadedFiles()

const UploadedFileMap & Wt::Http::Request::uploadedFiles | ( |  | ) | const

Returns uploaded file parameters.

See also
  getParameterMap()

## ◆ urlParam()

std::string Wt::Http::Request::urlParam | ( | const std::string & | param | ) | const

Get the value for the given URL parameter.

Example:

If a static resource is deployed at /tags/${tag}, then, if a request is made for /tags/Wt, urlParam("tag") will return "Wt".

If the given parameter is not available, an empty string is returned.

## ◆ urlParams()

const std::vector< std::pair< std::string, std::string > > & Wt::Http::Request::urlParams | ( |  | ) | const

Get all URL parameters.

See also
  urlParam()

## ◆ urlScheme()

std::string Wt::Http::Request::urlScheme | ( |  | ) | const

Returns the url scheme used.

This is either `"http"` or `"https"`

If we're behind a trusted reverse proxy, the value of X-Forwarded-Proto will be used if it is present.

## ◆ userAgent()

std::string Wt::Http::Request::userAgent | ( |  | ) | const

Returns the user agent.

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