C++ Rest SDK
The C++ REST SDK is a Microsoft project for cloud-based client-server communication in native code using a modern asynchronous C++ API design. This project aims to help C++ developers connect to and interact with services.
Public Member Functions | List of all members
web::http::http_response Class Reference

Represents an HTTP response. More...

#include <http_msg.h>

Public Member Functions

 http_response ()
 Constructs a response with an empty status code, no headers, and no body. More...
 
 http_response (http::status_code code)
 Constructs a response with given status code, no headers, and no body. More...
 
http::status_code status_code () const
 Gets the status code of the response message. More...
 
void set_status_code (http::status_code code) const
 Sets the status code of the response message. More...
 
const http::reason_phrase & reason_phrase () const
 Gets the reason phrase of the response message. If no reason phrase is set it will default to the standard one corresponding to the status code. More...
 
void set_reason_phrase (const http::reason_phrase &reason) const
 Sets the reason phrase of the response message. If no reason phrase is set it will default to the standard one corresponding to the status code. More...
 
http_headers & headers ()
 Gets the headers of the response message. More...
 
const http_headers & headers () const
 Gets a const reference to the headers of the response message. 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< utility::string_t > extract_string (bool ignore_content_type=false) const
 Extracts the body of the response 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) const
 Extracts the body of the response 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) const
 Extracts the body of the response 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 response 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
 Extracts the body of the response message into a vector of bytes. 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...
 
pplx::task< http::http_response > content_ready () const
 Signals the user (client) when all the data for this response message has been received. More...
 
std::shared_ptr< http::details::_http_response > _get_impl () const
 
http::details::_http_server_context * _get_server_context () const
 
void _set_server_context (std::unique_ptr< http::details::_http_server_context > server_context)
 

Detailed Description

Represents an HTTP response.

Constructor & Destructor Documentation

web::http::http_response::http_response ( )
inline

Constructs a response with an empty status code, no headers, and no body.

Returns
A new HTTP response.
web::http::http_response::http_response ( http::status_code  code)
inline

Constructs a response with given status code, no headers, and no body.

Parameters
codeHTTP status code to use in response.
Returns
A new HTTP response.

Member Function Documentation

concurrency::streams::istream web::http::http_response::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::http_response> web::http::http_response::content_ready ( ) const
inline

Signals the user (client) when all the data for this response 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_response::extract_json ( bool  ignore_content_type = false) const
inline

Extracts the body of the response 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_typeIf 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_response::extract_string ( bool  ignore_content_type = false) const
inline

Extracts the body of the response 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_typeIf true, ignores the Content-Type header and assumes UTF-8.
Returns
String containing body of the message.
pplx::task<utf16string> web::http::http_response::extract_utf16string ( bool  ignore_content_type = false) const
inline

Extracts the body of the response 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_typeIf true, ignores the Content-Type header and assumes UTF-16.
Returns
String containing body of the message.
pplx::task<utf8string> web::http::http_response::extract_utf8string ( bool  ignore_content_type = false) const
inline

Extracts the body of the response 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_typeIf 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_response::extract_vector ( ) const
inline

Extracts the body of the response message into a vector of bytes.

Returns
The body of the message as a vector of bytes.
http_headers& web::http::http_response::headers ( )
inline

Gets the headers of the response message.

Returns
HTTP headers for this response.

Use the

See also
http_headers::add Method

to fill in desired headers.

const http_headers& web::http::http_response::headers ( ) const
inline

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

Returns
HTTP headers for this response.
const http::reason_phrase& web::http::http_response::reason_phrase ( ) const
inline

Gets the reason phrase of the response message. If no reason phrase is set it will default to the standard one corresponding to the status code.

Returns
Reason phrase.
void web::http::http_response::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_textString containing body text.
content_typeMIME 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_response::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_textString containing body text.
content_typeMIME 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_response::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_textString containing body text.
content_typeMIME 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_response::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_textjson value.

This will overwrite any previously set body data.

void web::http::http_response::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_dataVector containing body data.

This will overwrite any previously set body data.

void web::http::http_response::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_dataVector containing body data.

This will overwrite any previously set body data.

void web::http::http_response::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
streamA readable, open asynchronous stream.
content_typeA 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_response::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
streamA readable, open asynchronous stream.
content_lengthThe size of the data to be sent in the body.
content_typeA 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_response::set_reason_phrase ( const http::reason_phrase &  reason) const
inline

Sets the reason phrase of the response message. If no reason phrase is set it will default to the standard one corresponding to the status code.

Parameters
reasonThe reason phrase to set.
void web::http::http_response::set_status_code ( http::status_code  code) const
inline

Sets the status code of the response message.

Parameters
codeStatus code to set.

This will overwrite any previously set status code.

http::status_code web::http::http_response::status_code ( ) const
inline

Gets the status code of the response message.

Returns
status code.
utility::string_t web::http::http_response::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:
Generated by   doxygen 1.8.10