class Poco::Net::HTMLForm

Overview

HTMLForm is a helper class for working with HTML forms, both on the client and on the server side. More…

#include <HTMLForm.h>

class HTMLForm: public Poco::Net::NameValueCollection
{
public:
    // structs

    struct Part;

    // fields

    static const std::string ENCODING_URL;
    static const std::string ENCODING_MULTIPART;
    static const int UNKNOWN_CONTENT_LENGTH;

    // construction

    HTMLForm();
    HTMLForm(const std::string& encoding);

    HTMLForm(
        const HTTPRequest& request,
        std::istream& requestBody,
        PartHandler& handler
        );

    HTMLForm(
        const HTTPRequest& request,
        std::istream& requestBody
        );

    HTMLForm(const HTTPRequest& request);

    // methods

    void
    setEncoding(const std::string& encoding);

    const std::string&
    getEncoding() const;

    void
    addPart(
        const std::string& name,
        PartSource* pSource
        );

    void
    load(
        const HTTPRequest& request,
        std::istream& requestBody,
        PartHandler& handler
        );

    void
    load(
        const HTTPRequest& request,
        std::istream& requestBody
        );

    void
    load(const HTTPRequest& request);

    void
    read(
        std::istream& istr,
        PartHandler& handler
        );

    void
    read(std::istream& istr);

    void
    read(const std::string& queryString);

    void
    prepareSubmit(HTTPRequest& request);

    std::streamsize
    calculateContentLength();

    void
    write(
        std::ostream& ostr,
        const std::string& boundary
        );

    void
    write(std::ostream& ostr);

    const std::string&
    boundary() const;

    int
    getFieldLimit() const;

    void
    setFieldLimit(int limit);

    void
    setValueLengthLimit(int limit);

    int
    getValueLengthLimit() const;

protected:
    // methods

    void
    readUrl(std::istream& istr);

    void
    readMultipart(
        std::istream& istr,
        PartHandler& handler
        );

    void
    writeUrl(std::ostream& ostr);

    void
    writeMultipart(std::ostream& ostr);
};

Inherited Members

public:
    // typedefs

    typedef Poco::ListMap<std::string, std::string> HeaderMap;
    typedef HeaderMap::Iterator Iterator;
    typedef HeaderMap::ConstIterator ConstIterator;

    // methods

    NameValueCollection&
    operator=(const NameValueCollection& nvc);

    void
    swap(NameValueCollection& nvc);

    const std::string&
    operator[](const std::string& name) const;

    void
    set(
        const std::string& name,
        const std::string& value
        );

    void
    add(
        const std::string& name,
        const std::string& value
        );

    const std::string&
    get(const std::string& name) const;

    const std::string&
    get(
        const std::string& name,
        const std::string& defaultValue
        ) const;

    bool
    has(const std::string& name) const;

    ConstIterator
    find(const std::string& name) const;

    ConstIterator
    begin() const;

    ConstIterator
    end() const;

    bool
    empty() const;

    std::size_t
    size() const;

    void
    erase(const std::string& name);

    void
    clear();

Detailed Documentation

HTMLForm is a helper class for working with HTML forms, both on the client and on the server side.

The maximum number of form fields can be restricted by calling setFieldLimit(). This is useful to defend against certain kinds of denial-of-service attacks. The limit is only enforced when parsing form data from a stream or string, not when adding form fields programmatically. The default limit is 100.

Fields

static const std::string ENCODING_URL

“application/x-www-form-urlencoded”

static const std::string ENCODING_MULTIPART

“multipart/form-data”

Construction

HTMLForm()

Creates an empty HTMLForm and sets the encoding to “application/x-www-form-urlencoded”.

HTMLForm(const std::string& encoding)

Creates an empty HTMLForm that uses the given encoding.

Encoding must be either “application/x-www-form-urlencoded” (which is the default) or “multipart/form-data”.

HTMLForm(
    const HTTPRequest& request,
    std::istream& requestBody,
    PartHandler& handler
    )

Creates a HTMLForm from the given HTTP request.

Uploaded files are passed to the given PartHandler.

HTMLForm(
    const HTTPRequest& request,
    std::istream& requestBody
    )

Creates a HTMLForm from the given HTTP request.

Uploaded files are silently discarded.

HTMLForm(const HTTPRequest& request)

Creates a HTMLForm from the given HTTP request.

The request must be a GET request and the form data must be in the query string (URL encoded).

For POST requests, you must use one of the constructors taking an additional input stream for the request body.

Methods

void
setEncoding(const std::string& encoding)

Sets the encoding used for posting the form.

Encoding must be either “application/x-www-form-urlencoded” (which is the default) or “multipart/form-data”.

const std::string&
getEncoding() const

Returns the encoding used for posting the form.

void
addPart(
    const std::string& name,
    PartSource* pSource
    )

Adds an part/attachment (file upload) to the form.

The form takes ownership of the PartSource and deletes it when it is no longer needed.

The part will only be sent if the encoding set for the form is “multipart/form-data”

void
load(
    const HTTPRequest& request,
    std::istream& requestBody,
    PartHandler& handler
    )

Reads the form data from the given HTTP request.

Uploaded files are passed to the given PartHandler.

void
load(
    const HTTPRequest& request,
    std::istream& requestBody
    )

Reads the form data from the given HTTP request.

Uploaded files are silently discarded.

void
load(const HTTPRequest& request)

Reads the form data from the given HTTP request.

The request must be a GET request and the form data must be in the query string (URL encoded).

For POST requests, you must use one of the overloads taking an additional input stream for the request body.

void
read(
    std::istream& istr,
    PartHandler& handler
    )

Reads the form data from the given input stream.

The form data read from the stream must be in the encoding specified for the form.

Note that read() does not clear the form before reading the new values.

void
read(std::istream& istr)

Reads the URL-encoded form data from the given input stream.

Note that read() does not clear the form before reading the new values.

void
read(const std::string& queryString)

Reads the form data from the given HTTP query string.

Note that read() does not clear the form before reading the new values.

void
prepareSubmit(HTTPRequest& request)

Fills out the request object for submitting the form.

If the request method is GET, the encoded form is appended to the request URI as query string. Otherwise (the method is POST), the form’s content type is set to the form’s encoding. The form’s parameters must be written to the request body separately, with a call to write. If the request’s HTTP version is HTTP/1.0:

- persistent connections are disabled
- the content transfer encoding is set to identity encoding

Otherwise, if the request’s HTTP version is HTTP/1.1:

- the request's persistent connection state is left unchanged
- the content transfer encoding is set to chunked

std::streamsize
calculateContentLength()

Calculate the content length for the form.

May be UNKNOWN_CONTENT_LENGTH if not possible to calculate

void
write(
    std::ostream& ostr,
    const std::string& boundary
    )

Writes the form data to the given output stream, using the specified encoding.

void
write(std::ostream& ostr)

Writes the form data to the given output stream, using the specified encoding.

const std::string&
boundary() const

Returns the MIME boundary used for writing multipart form data.

int
getFieldLimit() const

Returns the maximum number of header fields allowed.

See setFieldLimit() for more information.

void
setFieldLimit(int limit)

Sets the maximum number of header fields allowed.

This limit is used to defend certain kinds of denial-of-service attacks. Specify 0 for unlimited (not recommended).

The default limit is 100.

void
setValueLengthLimit(int limit)

Sets the maximum size for form field values stored as strings.

int
getValueLengthLimit() const

Returns the maximum size for form field values stored as strings.