web::http::http_request Class Reference

Represents an HTTP request. More...

#include <http_msg.h>

Public Member Functions
	http_request ()
	Constructs a new HTTP request with the 'GET' method. More...
	http_request (http::method mtd)
	Constructs a new HTTP request with the given request method. More...
	~http_request ()
	Destructor frees any held resources. More...
const http::method &	method () const
	Get the method (GET/PUT/POST/DELETE) of the request message. More...
void	set_method (const http::method &method) const
	Get the method (GET/PUT/POST/DELETE) of the request message. More...
const uri &	request_uri () const
	Get the underling URI of the request message. More...
void	set_request_uri (const uri &uri)
	Set the underling URI of the request message. More...
uri	relative_uri () const
	Gets a reference the URI path, query, and fragment part of this request message. This will be appended to the base URI specified at construction of the http_client. More...
uri	absolute_uri () const
	Get an absolute URI with scheme, host, port, path, query, and fragment part of the request message. More...
http_headers &	headers ()
	Gets a reference to the headers of the response message. More...
const http_headers &	headers () const
	Gets a const reference to the headers of the response message. More...
pplx::task< utility::string_t >	extract_string (bool ignore_content_type=false)
	Extract the body of the request message as a string value, checking that the content type is a MIME text type. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out. More...
pplx::task< utf8string >	extract_utf8string (bool ignore_content_type=false)
	Extract the body of the request message as a UTF-8 string value, checking that the content type is a MIME text type. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out. More...
pplx::task< utf16string >	extract_utf16string (bool ignore_content_type=false)
	Extract the body of the request message as a UTF-16 string value, checking that the content type is a MIME text type. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out. More...
pplx::task< json::value >	extract_json (bool ignore_content_type=false) const
	Extracts the body of the request message into a json value, checking that the content type is application/json. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out. More...
pplx::task< std::vector< unsigned char > >	extract_vector () const
	Extract the body of the response message into a vector of bytes. Extracting a vector can be done on More...
void	set_body (utf8string &&body_text, const utf8string &content_type=utf8string("text/plain; charset=utf-8"))
	Sets the body of the message to a textual string and set the "Content-Type" header. Assumes the character encoding of the string is UTF-8. More...
void	set_body (const utf8string &body_text, const utf8string &content_type=utf8string("text/plain; charset=utf-8"))
	Sets the body of the message to a textual string and set the "Content-Type" header. Assumes the character encoding of the string is UTF-8. More...
void	set_body (const utf16string &body_text, utf16string content_type=::utility::conversions::to_utf16string("text/plain"))
	Sets the body of the message to a textual string and set the "Content-Type" header. Assumes the character encoding of the string is UTF-16 will perform conversion to UTF-8. More...
void	set_body (const json::value &body_data)
	Sets the body of the message to contain json value. If the 'Content-Type' header hasn't already been set it will be set to 'application/json'. More...
void	set_body (std::vector< unsigned char > &&body_data)
	Sets the body of the message to the contents of a byte vector. If the 'Content-Type' header hasn't already been set it will be set to 'application/octet-stream'. More...
void	set_body (const std::vector< unsigned char > &body_data)
	Sets the body of the message to the contents of a byte vector. If the 'Content-Type' header hasn't already been set it will be set to 'application/octet-stream'. More...
void	set_body (const concurrency::streams::istream &stream, const utility::string_t &content_type=_XPLATSTR("application/octet-stream"))
	Defines a stream that will be relied on to provide the body of the HTTP message when it is sent. More...
void	set_body (const concurrency::streams::istream &stream, utility::size64_t content_length, const utility::string_t &content_type=_XPLATSTR("application/octet-stream"))
	Defines a stream that will be relied on to provide the body of the HTTP message when it is sent. More...
concurrency::streams::istream	body () const
	Produces a stream which the caller may use to retrieve data from an incoming request. More...
void	set_response_stream (const concurrency::streams::ostream &stream)
	Defines a stream that will be relied on to hold the body of the HTTP response message that results from the request. More...
void	set_progress_handler (const progress_handler &handler)
	Defines a callback function that will be invoked for every chunk of data uploaded or downloaded as part of the request. More...
pplx::task< void >	reply (const http_response &response) const
	Asynchronously responses to this HTTP request. More...
pplx::task< void >	reply (http::status_code status) const
	Asynchronously responses to this HTTP request. More...
pplx::task< void >	reply (http::status_code status, const json::value &body_data) const
	Responds to this HTTP request. More...
pplx::task< void >	reply (http::status_code status, utf8string &&body_data, const utf8string &content_type="text/plain; charset=utf-8") const
pplx::task< void >	reply (http::status_code status, const utf8string &body_data, const utf8string &content_type="text/plain; charset=utf-8") const
	Responds to this HTTP request with a string. Assumes the character encoding of the string is UTF-8. More...
pplx::task< void >	reply (http::status_code status, const utf16string &body_data, const utf16string &content_type=::utility::conversions::to_utf16string("text/plain")) const
	Responds to this HTTP request with a string. Assumes the character encoding of the string is UTF-16 will perform conversion to UTF-8. More...
pplx::task< void >	reply (status_code status, const concurrency::streams::istream &body, const utility::string_t &content_type=_XPLATSTR("application/octet-stream")) const
	Responds to this HTTP request. More...
pplx::task< void >	reply (status_code status, const concurrency::streams::istream &body, utility::size64_t content_length, const utility::string_t &content_type=_XPLATSTR("application/octet-stream")) const
	Responds to this HTTP request. More...
pplx::task< http_request >	content_ready () const
	Signals the user (listener) when all the data for this request message has been received. More...
pplx::task< http_response >	get_response () const
	Gets a task representing the response that will eventually be sent. More...
utility::string_t	to_string () const
	Generates a string representation of the message, including the body when possible. Mainly this should be used for debugging purposes as it has to copy the message body and doesn't have excellent performance. More...
pplx::task< void >	_reply_if_not_already (status_code status)
	Sends a response if one has not already been sent. More...
http::details::_http_server_context *	_get_server_context () const
	Gets the server context associated with this HTTP message. More...
void	_set_server_context (std::unique_ptr< http::details::_http_server_context > server_context)
void	_set_listener_path (const utility::string_t &path)
const std::shared_ptr< http::details::_http_request > &	_get_impl () const
void	_set_cancellation_token (const pplx::cancellation_token &token)
const pplx::cancellation_token &	_cancellation_token () const
void	_set_base_uri (const http::uri &base_uri)

Static Public Member Functions
static http_request	_create_request (std::unique_ptr< http::details::_http_server_context > server_context)
	These are used for the initial creation of the HTTP request. More...

Friends
class	http::details::_http_request
class	http::client::http_client

Detailed Description

Represents an HTTP request.

Constructor & Destructor Documentation

web::http::http_request::http_request ( )

inline

Constructs a new HTTP request with the 'GET' method.

web::http::http_request::http_request ( http::method  mtd )

inline

Constructs a new HTTP request with the given request method.

Parameters

mtd	Request method.

web::http::http_request::~http_request ( )

inline

Destructor frees any held resources.

Member Function Documentation

static http_request web::http::http_request::_create_request ( std::unique_ptr< http::details::_http_server_context >  server_context )

inlinestatic

These are used for the initial creation of the HTTP request.

http::details::_http_server_context* web::http::http_request::_get_server_context ( ) const

inline

Gets the server context associated with this HTTP message.

pplx::task<void> web::http::http_request::_reply_if_not_already ( status_code  status )

inline

Sends a response if one has not already been sent.

uri web::http::http_request::absolute_uri ( ) const

inline

Get an absolute URI with scheme, host, port, path, query, and fragment part of the request message.

Absolute URI is only valid after this http_request object has been passed to http_client::request().

concurrency::streams::istream web::http::http_request::body ( ) const

inline

Produces a stream which the caller may use to retrieve data from an incoming request.

Returns

A readable, open asynchronous stream.

This cannot be used in conjunction with any other means of getting the body of the request. It is not necessary to wait until the message has been sent before starting to write to the stream, but it is advisable to do so, since it will allow the network I/O to start earlier and the work of sending data can be overlapped with the production of more data.

pplx::task<http_request> web::http::http_request::content_ready ( ) const

inline

Signals the user (listener) when all the data for this request message has been received.

Returns

A task which is completed when all of the response body has been received

pplx::task<json::value> web::http::http_request::extract_json ( bool  ignore_content_type = false ) const

inline

Extracts the body of the request message into a json value, checking that the content type is application/json. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out.

Parameters

ignore_content_type

If true, ignores the Content-Type header and assumes UTF-8.

Returns

JSON value from the body of this message.

pplx::task<utility::string_t> web::http::http_request::extract_string ( bool  ignore_content_type = false )

inline

Extract the body of the request message as a string value, checking that the content type is a MIME text type. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out.

Parameters

ignore_content_type

If true, ignores the Content-Type header and assumes UTF-8.

Returns

String containing body of the message.

pplx::task<utf16string> web::http::http_request::extract_utf16string ( bool  ignore_content_type = false )

inline

Extract the body of the request message as a UTF-16 string value, checking that the content type is a MIME text type. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out.

Parameters

ignore_content_type

If true, ignores the Content-Type header and assumes UTF-16.

Returns

String containing body of the message.

pplx::task<utf8string> web::http::http_request::extract_utf8string ( bool  ignore_content_type = false )

inline

Extract the body of the request message as a UTF-8 string value, checking that the content type is a MIME text type. A body can only be extracted once because in some cases an optimization is made where the data is 'moved' out.

Parameters

ignore_content_type

If true, ignores the Content-Type header and assumes UTF-8.

Returns

String containing body of the message.

pplx::task<std::vector<unsigned char> > web::http::http_request::extract_vector ( ) const

inline

Extract the body of the response message into a vector of bytes. Extracting a vector can be done on

Returns

The body of the message as a vector of bytes.

pplx::task<http_response> web::http::http_request::get_response ( ) const

inline

Gets a task representing the response that will eventually be sent.

Returns

A task that is completed once response is sent.

http_headers& web::http::http_request::headers ( )

inline

Gets a reference to the headers of the response message.

Returns

HTTP headers for this response.

Use the http_headers::add to fill in desired headers.

const http_headers& web::http::http_request::headers ( ) const

inline

Gets a const reference to the headers of the response message.

Returns

HTTP headers for this response.

Use the http_headers::add to fill in desired headers.

const http::method& web::http::http_request::method ( ) const

inline

Get the method (GET/PUT/POST/DELETE) of the request message.

Returns

Request method of this HTTP request.

uri web::http::http_request::relative_uri ( ) const

inline

Gets a reference the URI path, query, and fragment part of this request message. This will be appended to the base URI specified at construction of the http_client.

Returns

A string.

When the request is the one passed to a listener's handler, the relative URI is the request URI less the listener's path. In all other circumstances, request_uri() and relative_uri() will return the same value.

pplx::task<void> web::http::http_request::reply ( const http_response &  response ) const

inline

Asynchronously responses to this HTTP request.

Parameters

response

Response to send.

Returns

An asynchronous operation that is completed once response is sent.

pplx::task<void> web::http::http_request::reply ( http::status_code  status ) const

inline

Asynchronously responses to this HTTP request.

Parameters

status

Response status code.

Returns

An asynchronous operation that is completed once response is sent.

pplx::task<void> web::http::http_request::reply ( http::status_code  status, const json::value &  body_data  ) const

inline

Responds to this HTTP request.

Parameters

status	Response status code.
body_data	Json value to use in the response body.

Returns

An asynchronous operation that is completed once response is sent.

pplx::task<void> web::http::http_request::reply ( http::status_code  status, utf8string &&  body_data, const utf8string &  content_type = "text/plain; charset=utf-8"  ) const

inline

Responds to this HTTP request with a string. Assumes the character encoding of the string is UTF-8.

Parameters

status	Response status code.
body_data	UTF-8 string containing the text to use in the response body.
content_type	Content type of the body.

Returns

An asynchronous operation that is completed once response is sent.

sent to before the body data is destroyed or goes out of scope.

pplx::task<void> web::http::http_request::reply ( http::status_code  status, const utf8string &  body_data, const utf8string &  content_type = "text/plain; charset=utf-8"  ) const

inline

Responds to this HTTP request with a string. Assumes the character encoding of the string is UTF-8.

Parameters

status	Response status code.
body_data	UTF-8 string containing the text to use in the response body.
content_type	Content type of the body.

Returns

An asynchronous operation that is completed once response is sent.

sent to before the body data is destroyed or goes out of scope.

pplx::task<void> web::http::http_request::reply ( http::status_code  status, const utf16string &  body_data, const utf16string &  content_type = ::utility::conversions::to_utf16string("text/plain")  ) const

inline

Responds to this HTTP request with a string. Assumes the character encoding of the string is UTF-16 will perform conversion to UTF-8.

Parameters

status	Response status code.
body_data	UTF-16 string containing the text to use in the response body.
content_type	Content type of the body.

Returns

An asynchronous operation that is completed once response is sent.

sent to before the body data is destroyed or goes out of scope.

pplx::task<void> web::http::http_request::reply ( status_code  status, const concurrency::streams::istream &  body, const utility::string_t &  content_type = _XPLATSTR("application/octet-stream")  ) const

inline

Responds to this HTTP request.

Parameters

status	Response status code.
content_type	A string holding the MIME type of the message body.
body	An asynchronous stream representing the body data.

Returns

A task that is completed once a response from the request is received.

pplx::task<void> web::http::http_request::reply ( status_code  status, const concurrency::streams::istream &  body, utility::size64_t  content_length, const utility::string_t &  content_type = _XPLATSTR("application/octet-stream")  ) const

inline

Responds to this HTTP request.

Parameters

status	Response status code.
content_length	The size of the data to be sent in the body..
content_type	A string holding the MIME type of the message body.
body	An asynchronous stream representing the body data.

Returns

A task that is completed once a response from the request is received.

const uri& web::http::http_request::request_uri ( ) const

inline

Get the underling URI of the request message.

Returns

The uri of this message.

void web::http::http_request::set_body ( utf8string &&  body_text, const utf8string &  content_type = utf8string("text/plain; charset=utf-8")  )

inline

Sets the body of the message to a textual string and set the "Content-Type" header. Assumes the character encoding of the string is UTF-8.

Parameters

body_text	String containing body text.
content_type	MIME type to set the "Content-Type" header to. Default to "text/plain; charset=utf-8".

This will overwrite any previously set body data and "Content-Type" header.

void web::http::http_request::set_body ( const utf8string &  body_text, const utf8string &  content_type = utf8string("text/plain; charset=utf-8")  )

inline

Sets the body of the message to a textual string and set the "Content-Type" header. Assumes the character encoding of the string is UTF-8.

Parameters

body_text	String containing body text.
content_type	MIME type to set the "Content-Type" header to. Default to "text/plain; charset=utf-8".

This will overwrite any previously set body data and "Content-Type" header.

void web::http::http_request::set_body ( const utf16string &  body_text, utf16string  content_type = ::utility::conversions::to_utf16string("text/plain")  )

inline

Sets the body of the message to a textual string and set the "Content-Type" header. Assumes the character encoding of the string is UTF-16 will perform conversion to UTF-8.

Parameters

body_text	String containing body text.
content_type	MIME type to set the "Content-Type" header to. Default to "text/plain".

This will overwrite any previously set body data and "Content-Type" header.

void web::http::http_request::set_body ( const json::value &  body_data )

inline

Sets the body of the message to contain json value. If the 'Content-Type' header hasn't already been set it will be set to 'application/json'.

Parameters

body_data

json value.

This will overwrite any previously set body data.

void web::http::http_request::set_body ( std::vector< unsigned char > &&  body_data )

inline

Sets the body of the message to the contents of a byte vector. If the 'Content-Type' header hasn't already been set it will be set to 'application/octet-stream'.

Parameters

body_data

Vector containing body data.

This will overwrite any previously set body data.

void web::http::http_request::set_body ( const std::vector< unsigned char > &  body_data )

inline

Sets the body of the message to the contents of a byte vector. If the 'Content-Type' header hasn't already been set it will be set to 'application/octet-stream'.

Parameters

body_data

Vector containing body data.

This will overwrite any previously set body data.

void web::http::http_request::set_body ( const concurrency::streams::istream &  stream, const utility::string_t &  content_type = _XPLATSTR("application/octet-stream")  )

inline

Defines a stream that will be relied on to provide the body of the HTTP message when it is sent.

Parameters

stream	A readable, open asynchronous stream.
content_type	A string holding the MIME type of the message body.

This cannot be used in conjunction with any other means of setting the body of the request. The stream will not be read until the message is sent.

void web::http::http_request::set_body ( const concurrency::streams::istream &  stream, utility::size64_t  content_length, const utility::string_t &  content_type = _XPLATSTR("application/octet-stream")  )

inline

Defines a stream that will be relied on to provide the body of the HTTP message when it is sent.

Parameters

stream	A readable, open asynchronous stream.
content_length	The size of the data to be sent in the body.
content_type	A string holding the MIME type of the message body.

This cannot be used in conjunction with any other means of setting the body of the request. The stream will not be read until the message is sent.

void web::http::http_request::set_method ( const http::method &  method ) const

inline

Get the method (GET/PUT/POST/DELETE) of the request message.

Parameters

method

Request method of this HTTP request.

void web::http::http_request::set_progress_handler ( const progress_handler &  handler )

inline

Defines a callback function that will be invoked for every chunk of data uploaded or downloaded as part of the request.

Parameters

handler

A function representing the progress handler. It's parameters are: up: a message_direction::direction value indicating the direction of the message that is being reported. progress: the number of bytes that have been processed so far.

This function will be called at least once for upload and at least once for the download body, unless there is some exception generated. An HTTP message with an error code is not an exception. This means, that even if there is no body, the progress handler will be called.

Setting the chunk size on the http_client does not guarantee that the client will be using exactly that increment for uploading and downloading data.

The handler will be called only once for each combination of argument values, in order. Depending on how a service responds, some download values may come before all upload values have been reported.

The progress handler will be called on the thread processing the request. This means that the implementation of the handler must take care not to block the thread or do anything that takes significant amounts of time. In particular, do not do any kind of I/O from within the handler, do not update user interfaces, and to not acquire any locks. If such activities are necessary, it is the handler's responsibility to execute that work on a separate thread.

void web::http::http_request::set_request_uri ( const uri &  uri )

inline

Set the underling URI of the request message.

Parameters

uri	The uri for this message.

void web::http::http_request::set_response_stream ( const concurrency::streams::ostream &  stream )

inline

Defines a stream that will be relied on to hold the body of the HTTP response message that results from the request.

Parameters

stream

A writable, open asynchronous stream.

If this function is called, the body of the response should not be accessed in any other way.

utility::string_t web::http::http_request::to_string ( ) const

inline

Generates a string representation of the message, including the body when possible. Mainly this should be used for debugging purposes as it has to copy the message body and doesn't have excellent performance.

Returns

A string representation of this HTTP request.

Note this function is synchronous and doesn't wait for the entire message body to arrive. If the message body has arrived by the time this function is called and it is has a textual Content-Type it will be included. Otherwise just the headers will be present.

---

The documentation for this class was generated from the following file:

• include/cpprest/http_msg.h