cppcms::http::response Class Reference

this class represents all HTTP/CGI response related API, generation of output content and HTTP headers. More...

#include <cppcms/http_response.h>

Inheritance diagram for cppcms::http::response:

Public Types
enum	status_type {   continue_transfer = 100, switching_protocol = 101, ok = 200, created = 201,   accepted = 202, non_authoritative_information = 203, no_content = 204, reset_content = 205,   partial_content = 206, multiple_choices = 300, moved_permanently = 301, found = 302,   see_other = 303, not_modified = 304, use_proxy = 305, temporary_redirect = 307,   bad_request = 400, unauthorized = 401, payment_required = 402, forbidden = 403,   not_found = 404, method_not_allowed = 405, not_acceptable = 406, proxy_authentication_required = 407,   request_time_out = 408, conflict = 409, gone = 410, precondition_failed = 412,   request_entity_too_large = 413, request_uri_too_large = 414, unsupported_media_type = 415, requested_range_not_satisfiable = 416,   expectation_failed = 417, internal_server_error = 500, not_implemented = 501, bad_gateway = 502,   service_unavailable = 503, gateway_timeout = 504, http_version_not_supported = 505 }
enum	io_mode_type {   normal, nogzip, raw, asynchronous,   asynchronous_raw }

Public Member Functions
void	accept_ranges (std::string const &)
void	age (unsigned seconds)
void	allow (std::string const &)
void	cache_control (std::string const &)
void	content_encoding (std::string const &)
void	content_language (std::string const &)
void	content_length (unsigned long long len)
void	content_location (std::string const &)
void	content_md5 (std::string const &)
void	content_range (std::string const &)
void	content_type (std::string const &)
void	date (time_t)
void	etag (std::string const &)
void	expires (time_t t)
void	last_modified (time_t t)
void	location (std::string const &)
void	pragma (std::string const &)
void	proxy_authenticate (std::string const &)
void	retry_after (std::string const &)
void	retry_after (unsigned)
void	status (int code)
void	status (int code, std::string const &message)
void	trailer (std::string const &)
void	transfer_encoding (std::string const &)
void	vary (std::string const &)
void	via (std::string const &)
void	warning (std::string const &)
void	www_authenticate (std::string const &)
void	set_header (std::string const &name, std::string const &value)
std::string	get_header (std::string const &name)
void	erase_header (std::string const &h)
void	add_header (std::string const &name, std::string const &value)
void	set_content_header (std::string const &content_type)
void	set_html_header ()
void	set_xhtml_header ()
void	set_plain_text_header ()
void	set_redirect_header (std::string const &location, int status=found)
void	set_cookie (cookie const &)
void	make_error_response (int stat, std::string const &msg=std::string())
io_mode_type	io_mode ()
void	io_mode (io_mode_type)
std::ostream &	out ()
bool	some_output_was_written ()
void	finalize ()
void	setbuf (int buffer_size)
void	full_asynchronous_buffering (bool enable)
bool	full_asynchronous_buffering ()
bool	pending_blocked_output ()

Static Public Member Functions
static std::string	make_http_time (time_t)
static char const *	status_to_string (int status)

Friends
class	impl::cgi::connection
class	::cppcms::cache_interface

Detailed Description

this class represents all HTTP/CGI response related API, generation of output content and HTTP headers.

Member Enumeration Documentation

enum cppcms::http::response::io_mode_type

This enum represents different types of IO modes giving fine grained control over HTTP output.

These modes are set via io_mode member function

Enumerator
normal	Synchronous IO. Write the request, it is buffered and possible compressed using gzip.
nogzip	Same as normal but disable gzip compression.
raw	User has full control over the output, it is also fully responsible for generation of HTTP headers, no-session management given.
asynchronous	In this mode the data is buffered and never transferred unless it is requested by async_flush_output, or async_complete_response member functions of http::context explicitly.
asynchronous_raw	Same as asynchronous but the user is responsible for generation of its own HTTP headers.

enum cppcms::http::response::status_type

This type represent the enum of HTTP Status type as of RFC 2616 sec. 6.1.1

Member Function Documentation

void cppcms::http::response::accept_ranges

(

std::string const &

)

Set HTTP Header Accept-Ranges

void cppcms::http::response::add_header	(	std::string const &	name,
		std::string const &	value
	)

add header - independently of set_header/get_header/erase_header - allows to specify multiple headers of same type like Set-Cookie or WWW-Authenticate

New in CppCMS 1.2

void cppcms::http::response::age

(

unsigned

seconds

)

Set HTTP Header Age

void cppcms::http::response::allow

(

std::string const &

)

Set HTTP Header Allow

void cppcms::http::response::cache_control

(

std::string const &

)

Set HTTP Header Cache-Control

void cppcms::http::response::content_encoding

(

std::string const &

)

Set HTTP Header Content-Encoding.

Note: if you set this header manually, gzip compression will be automatically disabled.

void cppcms::http::response::content_language

(

std::string const &

)

Set HTTP Header Content-Language

void cppcms::http::response::content_length

(

unsigned long long

len

)

Set HTTP Header Content-Length

void cppcms::http::response::content_location

(

std::string const &

)

Set HTTP Header Content-Location

void cppcms::http::response::content_md5

(

std::string const &

)

Set HTTP Header Content-Md5

void cppcms::http::response::content_range

(

std::string const &

)

Set HTTP Header Content-Range

void cppcms::http::response::content_type

(

std::string const &

)

Set HTTP Header Content-Type

void cppcms::http::response::date

(

time_t

)

Set HTTP Header Date

void cppcms::http::response::erase_header

(

std::string const &

h

)

Erase specific header h

void cppcms::http::response::etag

(

std::string const &

)

Set HTTP Header Etag

void cppcms::http::response::expires

(

time_t

t

)

Set HTTP Header Expires, it is formatted as HTTP Date-Time from the POSIX time t

void cppcms::http::response::finalize

(

)

Finalize an output request. Generally this function is called automatically for synchronous application, however when working with asynchronous requests you should call this function before calling async_complete_response.

void cppcms::http::response::full_asynchronous_buffering

(

bool

enable

)

Sets full buffering mode for asynchronous applications

When set to true the output data is transferred only when async_flush_output or async_complete_response are called this is the default behavior.

When set to false, the data is sent upon flushing of the std::ostream provided by out(). If I/O operation blocks, the actual output is buffered, it is possible to test if blocking occurred by calling pending_blocked_output()

When the full buffering is disable, if an error occurs, the out() is set to fail state.

New in CppCMS 1.2

bool cppcms::http::response::full_asynchronous_buffering

(

)

Get current state of asynchronous buffering

New in CppCMS 1.2

std::string cppcms::http::response::get_header

(

std::string const &

name

)

Get output header value, returns empty string if it is not set

io_mode_type cppcms::http::response::io_mode

(

)

Get current io_mode, see a description for io_mode_type.

void cppcms::http::response::io_mode

(

io_mode_type

)

Set current io_mode, see a description for io_mode_type.

Note: you can't change it after requesting for output stream, i.e. calling out() member function.

void cppcms::http::response::last_modified

(

time_t

t

)

Set HTTP Header Last-Modified, it is formatted as HTTP Date-Time from the POSIX time t

void cppcms::http::response::location

(

std::string const &

)

Set HTTP Header Location

void cppcms::http::response::make_error_response	(	int	stat,
		std::string const &	msg = std::string()
	)

This creates a default HTTP response (including HTML body) with a status stat a message msg.

Note: if msg is empty default message for HTTP Status code stat is used.

static std::string cppcms::http::response::make_http_time ( time_t  )

static

Create an HTTP time string from POSIX time as of RFC 2616

std::ostream& cppcms::http::response::out

(

)

Request an output stream to write the body of HTTP response after writing headers.

Note:

• it triggers saving changes in the session, so further changes will have no effect.
• it triggers writing all headers to output stream, such that changing any header or adding cookies will have no effect.
• it is impossible to change an io_mode after calling this function.

bool cppcms::http::response::pending_blocked_output

(

)

Returns true of some of the output wasn't sent due to blocking upon flushing of std::stream &out() which is used together with full_asynchronous_buffering(false) mode.

Note: it does not look on to internal buffers thus it is user's responsibility to call

Once the condition occurs you can flush the output asynchronously using async_complete_response or async_flush_output

New in CppCMS 1.2

void cppcms::http::response::pragma

(

std::string const &

)

Set HTTP Header Pragma

void cppcms::http::response::proxy_authenticate

(

std::string const &

)

Set HTTP Header Proxy-Authenticate

void cppcms::http::response::retry_after

(

std::string const &

)

Set HTTP Header Retry-After

void cppcms::http::response::retry_after

(

unsigned

)

Set HTTP Header Retry-After

void cppcms::http::response::set_content_header

(

std::string const &

content_type

)

This function set HTTP Content-Type header, but unlike contet_type function it also adds current locale charset encoding (unless localization.disable_charset_in_content_type set to true in configuration)

void cppcms::http::response::set_cookie

(

cookie const &

)

Set HTTP Cookie

void cppcms::http::response::set_header	(	std::string const &	name,
		std::string const &	value
	)

Set Generic HTTP header "name: value"

void cppcms::http::response::set_html_header

(

)

Shortcut to set_content_header("text/html") - this is the default content-type header

void cppcms::http::response::set_plain_text_header

(

)

Shortcut to set_content_header("text/plain")

void cppcms::http::response::set_redirect_header	(	std::string const &	location,
		int	status = found
	)

Redirect to other location by setting HTTP Location header and a Status header with a status status

void cppcms::http::response::set_xhtml_header

(

)

Shortcut to set_content_header("text/xhtml")

void cppcms::http::response::setbuf

(

int

buffer_size

)

Defines the size of the output buffer for the output data.

Setting the to 0 makes the output non-buffered and prevents unnecessary copy of large objects in memory

The default is defined in configuration by service.output_buffer_size and service.async_output_buffer_size for synchronous and asynchronous applications accordingly, can be called before and after out() was called

Calling with negative value would reset it to the default

Note: when gzip compression active, buffering is still present at intermediate levels

New in CppCMS 1.2

bool cppcms::http::response::some_output_was_written

(

)

Check if out() member function was called, (so it is impossible to do some tasks like changing HTTP headers. See out description for more details

void cppcms::http::response::status

(

int

code

)

Set GCI Status Header, the message is created according to the code automatically

void cppcms::http::response::status	(	int	code,
		std::string const &	message
	)

Set HTTP Header Status with the status code code and a custom message

static char const* cppcms::http::response::status_to_string ( int  status )

static

Return a string that represents a message for HTTP status code status

void cppcms::http::response::trailer

(

std::string const &

)

Set HTTP Header Trailer

void cppcms::http::response::transfer_encoding

(

std::string const &

)

Set HTTP Header Transfer-Encoding, note

void cppcms::http::response::vary

(

std::string const &

)

Set HTTP Header Vary

void cppcms::http::response::via

(

std::string const &

)

Set HTTP Header Via

void cppcms::http::response::warning

(

std::string const &

)

Set HTTP Header Warning

void cppcms::http::response::www_authenticate

(

std::string const &

)

Set HTTP Header WWW-Authenticate

---

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

• cppcms/http_response.h