HTTP module

FormWriter

FormWriter is an HTTP client connection adapter for writing HTML forms.

FormWriter

#include <icy/http/form.h>

Inherits: NVCollection, PacketStreamAdapter, Startable

FormWriter is an HTTP client connection adapter for writing HTML forms.

This class runs in its own thread so as not to block the event loop while uploading big files. Class members are not synchronized hence they should not be accessed while the form is sending, not that there would be any reason to do so.

Public Attributes

Return	Name	Description
`PacketSignal`	`emitter`	The outgoing packet emitter.

emitter

PacketSignal emitter

The outgoing packet emitter.

Public Methods

Return	Name	Description
	`~FormWriter` `virtual`	Destroys the FormWriter.
`void`	`addPart`	Adds a part or file attachment to the multipart form.
`void`	`start` `virtual`	Starts the sending thread.
`void`	`stop` `virtual`	Stops the sending thread.
`bool`	`complete` `const`	Returns true if the request is complete.
`bool`	`cancelled` `const`	Returns true if the request is cancelled.
`void`	`prepareSubmit`	Prepares the outgoing HTTP request object for submitting the form.
`uint64_t`	`calculateMultipartContentLength`	Processes the entire form body and computes its total byte length. Only meaningful for multipart/form-data when not using chunked encoding.
`void`	`writeUrl`	Writes the complete "application/x-www-form-urlencoded" encoded body to `ostr`. All key-value pairs from the NVCollection base are percent-encoded and joined with '&'.
`void`	`writeMultipartChunk`	Writes the next pending multipart chunk to the connection. Non-blocking; intended to be called repeatedly from the event loop until all parts have been sent.
`void`	`writeAsync`	Writes the next message chunk from the background runner thread. Called by the Runner; do not call directly.
`void`	`setEncoding`	Sets the MIME encoding used for submitting the form. Must be set before prepareSubmit() is called.
`const std::string &`	`encoding` `const`	Returns the encoding used for posting the form.
`void`	`setBoundary`	Sets the MIME boundary string used to delimit multipart form parts. If not set, a random boundary is generated by prepareSubmit(). Must be set before prepareSubmit() is called.
`const std::string &`	`boundary` `const`	Returns the MIME boundary used for writing multipart form data.
`ConnectionStream &`	`connection`	The associated HTTP client connection.

~FormWriter

virtual

virtual ~FormWriter()

Destroys the FormWriter.

addPart

void addPart(const std::string & name, FormPart * part)

Adds a part or file attachment to the multipart form.

The FormWriter takes ownership of part and deletes it when done. Parts are only sent when the encoding is "multipart/form-data".

Parameters

name Form field name for this part.
part Part to add. Ownership is transferred.

start

virtual

virtual void start()

Starts the sending thread.

stop

virtual

virtual void stop()

Stops the sending thread.

complete

const

bool complete() const

Returns true if the request is complete.

cancelled

const

bool cancelled() const

Returns true if the request is cancelled.

prepareSubmit

void prepareSubmit()

Prepares the outgoing HTTP request object for submitting the form.

calculateMultipartContentLength

uint64_t calculateMultipartContentLength()

Processes the entire form body and computes its total byte length. Only meaningful for multipart/form-data when not using chunked encoding.

Returns

Total content length in bytes.

writeUrl

void writeUrl(std::ostream & ostr)

Writes the complete "application/x-www-form-urlencoded" encoded body to ostr. All key-value pairs from the NVCollection base are percent-encoded and joined with '&'.

Parameters

ostr Output stream to write to.

writeMultipartChunk

void writeMultipartChunk()

Writes the next pending multipart chunk to the connection. Non-blocking; intended to be called repeatedly from the event loop until all parts have been sent.

writeAsync

void writeAsync()

Writes the next message chunk from the background runner thread. Called by the Runner; do not call directly.

setEncoding

void setEncoding(const std::string & encoding)

Sets the MIME encoding used for submitting the form. Must be set before prepareSubmit() is called.

Parameters

encoding MIME type: ENCODING_URL or ENCODING_MULTIPART_FORM.

encoding

const

const std::string & encoding() const

Returns the encoding used for posting the form.

setBoundary

void setBoundary(const std::string & boundary)

Sets the MIME boundary string used to delimit multipart form parts. If not set, a random boundary is generated by prepareSubmit(). Must be set before prepareSubmit() is called.

Parameters

boundary Boundary string (without leading "--").

boundary

const

const std::string & boundary() const

Returns the MIME boundary used for writing multipart form data.

connection

ConnectionStream & connection()

The associated HTTP client connection.

Public Static Attributes

Return	Name	Description
`const char *`	`ENCODING_URL` `static`	"application/x-www-form-urlencoded"
`const char *`	`ENCODING_MULTIPART_FORM` `static`	"multipart/form-data"
`const char *`	`ENCODING_MULTIPART_RELATED` `static`	"multipart/related" http://tools.ietf.org/html/rfc2387

ENCODING_URL

static

const char * ENCODING_URL

"application/x-www-form-urlencoded"

ENCODING_MULTIPART_FORM

static

const char * ENCODING_MULTIPART_FORM

"multipart/form-data"

static

const char * ENCODING_MULTIPART_RELATED

"multipart/related" http://tools.ietf.org/html/rfc2387

Public Static Methods

Return	Name	Description
`FormWriter *`	`create` `static`	Creates a FormWriter for the given connection and encoding.

create

static

static FormWriter * create(ConnectionStream & conn, const std::string & encoding)

Creates a FormWriter for the given connection and encoding.

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

Parameters

conn The HTTP connection stream to write form data to.
encoding MIME encoding type.

Returns

Heap-allocated FormWriter. The caller owns the returned pointer.

Protected Attributes

Return	Name	Description
`ConnectionStream &`	`_stream`
`std::shared_ptr< Runner >`	`_runner`
`std::string`	`_encoding`
`std::string`	`_boundary`
`PartQueue`	`_parts`
`uint64_t`	`_filesLength`
`int`	`_writeState`
`bool`	`_initial`
`bool`	`_complete`

_stream

ConnectionStream & _stream

_runner

std::shared_ptr< Runner > _runner

_encoding

std::string _encoding

_boundary

std::string _boundary

_parts

PartQueue _parts

_filesLength

uint64_t _filesLength

_writeState

int _writeState

_initial

bool _initial

_complete

bool _complete

Protected Methods

Return	Name	Description
	`FormWriter`	Creates the FormWriter that uses the given encoding.
	`FormWriter`	Deleted constructor.
	`FormWriter`	Deleted constructor.
`void`	`writePartHeader`	Writes the message boundary std::string, followed by the message header to the output stream.
`void`	`writeEnd`	Writes the final boundary std::string to the output stream.
`void`	`updateProgress` `virtual`	Updates the upload progress via the associated ConnectionStream object.

FormWriter

FormWriter(ConnectionStream & conn, std::shared_ptr< Runner > runner, const std::string & encoding)

Creates the FormWriter that uses the given encoding.

FormWriter

FormWriter(const FormWriter &) = delete

Deleted constructor.

FormWriter

FormWriter(FormWriter &&) = delete

Deleted constructor.

writePartHeader

void writePartHeader(const NVCollection & header, std::ostream & ostr)

Writes the message boundary std::string, followed by the message header to the output stream.

writeEnd

void writeEnd(std::ostream & ostr)

Writes the final boundary std::string to the output stream.

updateProgress

virtual

virtual void updateProgress(int nread)

Updates the upload progress via the associated ConnectionStream object.

Built with