Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
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,

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)


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

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

These modes are set via io_mode member function


Synchronous IO. Write the request, it is buffered and possible compressed using gzip.


Same as normal but disable gzip compression.


User has full control over the output, it is also fully responsible for generation of HTTP headers, no-session management given.


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.


Same as asynchronous but the user is responsible for generation of its own HTTP headers.

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  )

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.


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

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: