Class Poco::Net::HTMLForm

Library: Net
Package: HTML
Header: Poco/Net/HTMLForm.h

Description

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.

Inheritance

Direct Base Classes: NameValueCollection

All Base Classes: NameValueCollection

Member Summary

Member Functions: addPart, boundary, calculateContentLength, getEncoding, getFieldLimit, getValueLengthLimit, load, prepareSubmit, read, readMultipart, readUrl, setEncoding, setFieldLimit, setValueLengthLimit, write, writeMultipart, writeUrl

Inherited Functions: add, begin, clear, empty, end, erase, find, get, has, operator =, operator [], secureClear, secureErase, set, size, swap

Enumerations

Options

OPT_USE_CONTENT_LENGTH = 0x01

Don't use Chunked Transfer-Encoding for multipart requests.

Constructors

HTMLForm

HTMLForm();

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

HTMLForm

explicit 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

explicit 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.

HTMLForm

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

Creates a HTMLForm from the given HTTP request.

Uploaded files are silently discarded.

HTMLForm

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.

Destructor

~HTMLForm

~HTMLForm();

Destroys the HTMLForm.

Member Functions

addPart

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"

boundary

const std::string & boundary() const;

Returns the MIME boundary used for writing multipart form data.

calculateContentLength

std::streamsize calculateContentLength();

Calculate the content length for the form. May be UNKNOWN_CONTENT_LENGTH if not possible to calculate

getEncoding

const std::string & getEncoding() const;

Returns the encoding used for posting the form.

getFieldLimit

int getFieldLimit() const;

Returns the maximum number of header fields allowed.

See setFieldLimit() for more information.

getValueLengthLimit

int getValueLengthLimit() const;

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

load

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.

load

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

Reads the form data from the given HTTP request.

Uploaded files are silently discarded.

load

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.

prepareSubmit

void prepareSubmit(
HTTPRequest & request,
int options = 0
);

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, unless the OPT_USE_CONTENT_LENGTH is given in options

Note: Not using chunked transfer encoding for multipart forms degrades performance, as the request content must be generated twice, first to determine its size, then to actually send it.

read

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.

read

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.

read

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.

setEncoding

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".

setFieldLimit

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.

class HTMLForm

Description

Inheritance

Member Summary

Enumerations

Constructors

Destructor

Member Functions

Variables