HTTP forms

x::http::form::parameters is a reference to reference-counted object that represents parameters for a submitted form. It is, essentially, a std::multimap<std::string, std::string>, and can be treated as such:

#include <x/http/form.H>

x::http::form::parameters params(x::http::form::parameters::create());

params-<insert(std::make_pair("password", "opensesame"));

The form.H header files also defines x::http::form::parametersptr, a nullable reference pointer; also x::http::form::const_parameters and x::http::form::const_parametersptr, the constant variations.

The following constructors are available in addition to the default constructor (forwarded by the reference create() method) that instantiates an empty form parameter map:

x::http::form::parameters::create("list", "alpha", "list", "beta",
                                  "option", "explicit");

An even-sized string list initializes the contents of the map.

x::http::form::parameters::create("list=alpha&list=beta&option=explicit")

A single string parameter initializes form parameters from an application/x-www-form-urlencoded-formatted string.

std::vector<char> buf;

x::http::form::parameters::create(buf);

A container passed as a parameter initializes form parameters from the sequence obtained by the container's begin() and end() methods.

Limiting form size

typedef std::istreambuf_iterator<char> iterator;

iterator beg_iter, end_iter;

// ...

x::http::form::parameters params;

params->decode_params(x::http::form::limited_iter<iterator>(beg_iter, 8192),
                      x::http::form::limited_iter<iterator>(end_iter));

The form parameter object's decode_params() method takes a beginning and an ending iterator. It adds additional parameters to the form that are from the application/x-www-form-urlencoded-formatted string that's defined by the beginning and the ending iterator. x::http::form::limited_iter is a convenient template class that enforces a maximum limit on the overall size of the form, in situations where it's not known in advance.

x::http::form::limited_iter's constructor for a beginning iterator takes the underlying iterator, and a byte count, then constructs a wrapper that iterates over the underlying iterator, but throws an exception after the specified number of bytes, 8192 in the above example. x::http::form::limited_iter's constructor for an ending iterator is generally a no-op.

Encoding an HTTP form

x::http::form::parameters params;

x::http::form::parameters::base::encode_iter b=params->begin(), e=params->end();

std::copy(b, e, std::ostreambuf_iterator<char>(std::cout);

The form's begin() and end() methods define an input sequence that encode the form using application/x-www-form-urlencoded encoding.