Class Poco::Net::HTMLForm
Author: Applied Informatics Software Engineering GmbH and Contributors
Date: 2009-11-24

# Poco::Net

# class 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.

## Inheritance

Direct Base Classes: NameValueCollection

All Base Classes: NameValueCollection

## Member Summary

Member Functions: addPart, boundary, getEncoding, load, prepareSubmit, read, readMultipart, readUrl, setEncoding, write, writeMultipart, writeUrl

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

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

### getEncoding

const std::string & getEncoding() const;

Returns the encoding used for posting the form.

### 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
);

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

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

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

### write

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

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

### write

void write(
std::ostream & ostr
);

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

### readMultipart

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

### readUrl

void readUrl(
std::istream & istr
);

### writeMultipart

void writeMultipart(
std::ostream & ostr
);

### writeUrl

void writeUrl(
std::ostream & ostr
);

## Variables

### ENCODING_MULTIPART

static const std::string ENCODING_MULTIPART;

"multipart/form-data"

### ENCODING_URL

static const std::string ENCODING_URL;

"application/x-www-form-urlencoded"