FormWriter
FormWriter
#include <icy/http/form.h>class FormWriterDefined in src/http/include/icy/http/form.h:42
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.
List of all members
| Name | Kind | Owner |
|---|---|---|
FormPart | friend | Declared here |
FilePart | friend | Declared here |
StringPart | friend | Declared here |
emitter | variable | Declared here |
~FormWriter | function | Declared here |
addPart | function | Declared here |
start | function | Declared here |
stop | function | Declared here |
complete | function | Declared here |
cancelled | function | Declared here |
prepareSubmit | function | Declared here |
calculateMultipartContentLength | function | Declared here |
writeUrl | function | Declared here |
writeMultipartChunk | function | Declared here |
writeAsync | function | Declared here |
setEncoding | function | Declared here |
encoding | function | Declared here |
setBoundary | function | Declared here |
boundary | function | Declared here |
connection | function | Declared here |
ENCODING_URL | variable | Declared here |
ENCODING_MULTIPART_FORM | variable | Declared here |
ENCODING_MULTIPART_RELATED | variable | Declared here |
create | function | Declared here |
_stream | variable | Declared here |
_runner | variable | Declared here |
_encoding | variable | Declared here |
_boundary | variable | Declared here |
_parts | variable | Declared here |
_filesLength | variable | Declared here |
_writeState | variable | Declared here |
_initial | variable | Declared here |
_complete | variable | Declared here |
FormWriter | function | Declared here |
FormWriter | function | Declared here |
operator= | function | Declared here |
FormWriter | function | Declared here |
operator= | function | Declared here |
writePartHeader | function | Declared here |
writeEnd | function | Declared here |
updateProgress | function | Declared here |
NVCollection | function | Inherited from NVCollection |
NVCollection | function | Inherited from NVCollection |
NVCollection | function | Inherited from NVCollection |
~NVCollection | function | Inherited from NVCollection |
operator= | function | Inherited from NVCollection |
operator= | function | Inherited from NVCollection |
operator[] | function | Inherited from NVCollection |
set | function | Inherited from NVCollection |
add | function | Inherited from NVCollection |
add | function | Inherited from NVCollection |
get | function | Inherited from NVCollection |
get | function | Inherited from NVCollection |
has | function | Inherited from NVCollection |
find | function | Inherited from NVCollection |
begin | function | Inherited from NVCollection |
end | function | Inherited from NVCollection |
empty | function | Inherited from NVCollection |
size | function | Inherited from NVCollection |
erase | function | Inherited from NVCollection |
clear | function | Inherited from NVCollection |
Map | typedef | Inherited from NVCollection |
Iterator | typedef | Inherited from NVCollection |
ConstIterator | typedef | Inherited from NVCollection |
_map | variable | Inherited from NVCollection |
PacketStreamAdapter | function | Inherited from PacketStreamAdapter |
~PacketStreamAdapter | function | Inherited from PacketStreamAdapter |
emit | function | Inherited from PacketStreamAdapter |
emit | function | Inherited from PacketStreamAdapter |
emit | function | Inherited from PacketStreamAdapter |
emit | function | Inherited from PacketStreamAdapter |
emit | function | Inherited from PacketStreamAdapter |
getEmitter | function | Inherited from PacketStreamAdapter |
retention | function | Inherited from PacketStreamAdapter |
onStreamStateChange | function | Inherited from PacketStreamAdapter |
_emitter | variable | Inherited from PacketStreamAdapter |
PacketStreamAdapter | function | Inherited from PacketStreamAdapter |
operator= | function | Inherited from PacketStreamAdapter |
PacketStreamAdapter | function | Inherited from PacketStreamAdapter |
operator= | function | Inherited from PacketStreamAdapter |
start | function | Inherited from Startable |
stop | function | Inherited from Startable |
Inherited from NVCollection
| Kind | Name | Description |
|---|---|---|
function | NVCollection inline | |
function | NVCollection inline | |
function | NVCollection inline noexcept | |
function | ~NVCollection virtual inline | |
function | operator= | Assigns the name-value pairs of another NVCollection to this one. |
function | operator= noexcept | |
function | operator[] const | Returns the value of the (first) name-value pair with the given name. |
function | set | Sets the value of the (first) name-value pair with the given name. |
function | add | Adds a new name-value pair with the given name and value. |
function | add | Adds a new name-value pair using move semantics. |
function | get const | Returns the value of the first name-value pair with the given name. |
function | get const | Returns the value of the first name-value pair with the given name. If no value with the given name has been found, the defaultValue is returned. |
function | has const | Returns true if there is at least one name-value pair with the given name. |
function | find const | Returns an iterator pointing to the first name-value pair with the given name. |
function | begin const | Returns an iterator pointing to the begin of the name-value pair collection. |
function | end const | Returns an iterator pointing to the end of the name-value pair collection. |
function | empty const | Returns true iff the header does not have any content. |
function | size const | Returns the number of name-value pairs in the collection. |
function | erase | Removes all name-value pairs with the given name. |
function | clear | Removes all name-value pairs and their values. |
typedef | Map | |
typedef | Iterator | |
typedef | ConstIterator | |
variable | _map |
Inherited from PacketStreamAdapter
| Kind | Name | Description |
|---|---|---|
function | PacketStreamAdapter | Construct the adapter, binding it to the given packet signal. |
function | ~PacketStreamAdapter virtual inline | |
function | emit virtual | Emit a mutable raw buffer as a packet. |
function | emit virtual | Emit a read-only raw buffer as a packet (data is copied internally). |
function | emit virtual | Emit a string as a packet (data is copied internally). |
function | emit virtual | Emit a flag-only packet carrying no payload data. |
function | emit virtual | Emit an existing packet directly onto the outgoing signal. |
function | getEmitter | Returns a reference to the outgoing packet signal. |
function | retention virtual const | Returns how this adapter treats incoming packet lifetime. Most adapters are synchronous and therefore only borrow the packet for the current call chain. Queue-style adapters override this to advertise that they clone before deferred use. Callers may treat the first adapter reporting Cloned or Retained as the explicit ownership boundary in the stream graph. |
function | onStreamStateChange virtual inline | Called by the PacketStream to notify when the internal Stream state changes. On receiving the Stopped state, it is the responsibility of the adapter to have ceased all outgoing packet transmission, especially in multi-thread scenarios. |
variable | _emitter | |
function | PacketStreamAdapter | NonCopyable and NonMovable. |
function | operator= | Deleted assignment operator. |
function | PacketStreamAdapter | Deleted constructor. |
function | operator= | Deleted assignment operator. |
Inherited from Startable
| Kind | Name | Description |
|---|---|---|
function | start virtual | Starts the object (e.g. begins processing or listening). |
function | stop virtual | Stops the object (e.g. halts processing or closes resources). |
Friends
| Name | Description |
|---|---|
FormPart | |
FilePart | |
StringPart |
FormPart
friend class FormPartDefined in src/http/include/icy/http/form.h:152
FilePart
friend class FilePartDefined in src/http/include/icy/http/form.h:153
StringPart
friend class StringPartDefined in src/http/include/icy/http/form.h:154
Public Attributes
| Return | Name | Description |
|---|---|---|
PacketSignal | emitter | The outgoing packet emitter. |
emitter
PacketSignal emitterDefined in src/http/include/icy/http/form.h:122
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()Defined in src/http/include/icy/http/form.h:57
Destroys the FormWriter.
addPart
void addPart(const std::string & name, FormPart * part)Defined in src/http/include/icy/http/form.h:65
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
nameForm field name for this part.partPart to add. Ownership is transferred.
start
virtual
virtual void start()Defined in src/http/include/icy/http/form.h:68
Starts the sending thread.
Reimplements
stop
virtual
virtual void stop()Defined in src/http/include/icy/http/form.h:71
Stops the sending thread.
Reimplements
complete
const
bool complete() constDefined in src/http/include/icy/http/form.h:74
Returns true if the request is complete.
cancelled
const
bool cancelled() constDefined in src/http/include/icy/http/form.h:77
Returns true if the request is cancelled.
prepareSubmit
void prepareSubmit()Defined in src/http/include/icy/http/form.h:80
Prepares the outgoing HTTP request object for submitting the form.
calculateMultipartContentLength
uint64_t calculateMultipartContentLength()Defined in src/http/include/icy/http/form.h:85
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)Defined in src/http/include/icy/http/form.h:90
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
ostrOutput stream to write to.
writeMultipartChunk
void writeMultipartChunk()Defined in src/http/include/icy/http/form.h:95
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()Defined in src/http/include/icy/http/form.h:99
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)Defined in src/http/include/icy/http/form.h:104
Sets the MIME encoding used for submitting the form. Must be set before prepareSubmit() is called.
Parameters
encodingMIME type: ENCODING_URL or ENCODING_MULTIPART_FORM.
encoding
const
const std::string & encoding() constDefined in src/http/include/icy/http/form.h:107
Returns the encoding used for posting the form.
setBoundary
void setBoundary(const std::string & boundary)Defined in src/http/include/icy/http/form.h:113
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
boundaryBoundary string (without leading "--").
boundary
const
const std::string & boundary() constDefined in src/http/include/icy/http/form.h:116
Returns the MIME boundary used for writing multipart form data.
connection
ConnectionStream & connection()Defined in src/http/include/icy/http/form.h:119
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_URLDefined in src/http/include/icy/http/form.h:124
"application/x-www-form-urlencoded"
ENCODING_MULTIPART_FORM
static
const char * ENCODING_MULTIPART_FORMDefined in src/http/include/icy/http/form.h:125
"multipart/form-data"
ENCODING_MULTIPART_RELATED
static
const char * ENCODING_MULTIPART_RELATEDDefined in src/http/include/icy/http/form.h:126
"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 = FormWriter::ENCODING_URL)Defined in src/http/include/icy/http/form.h:54
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
connThe HTTP connection stream to write form data to.encodingMIME 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 & _streamDefined in src/http/include/icy/http/form.h:165
_runner
std::shared_ptr< Runner > _runnerDefined in src/http/include/icy/http/form.h:166
_encoding
std::string _encodingDefined in src/http/include/icy/http/form.h:167
_boundary
std::string _boundaryDefined in src/http/include/icy/http/form.h:168
_parts
PartQueue _partsDefined in src/http/include/icy/http/form.h:169
_filesLength
uint64_t _filesLengthDefined in src/http/include/icy/http/form.h:170
_writeState
int _writeStateDefined in src/http/include/icy/http/form.h:171
_initial
bool _initialDefined in src/http/include/icy/http/form.h:172
_complete
bool _completeDefined in src/http/include/icy/http/form.h:173
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 = FormWriter::ENCODING_URL)Defined in src/http/include/icy/http/form.h:130
Creates the FormWriter that uses the given encoding.
FormWriter
FormWriter(const FormWriter &) = deleteDefined in src/http/include/icy/http/form.h:133
Deleted constructor.
FormWriter
FormWriter(FormWriter &&) = deleteDefined in src/http/include/icy/http/form.h:135
Deleted constructor.
writePartHeader
void writePartHeader(const NVCollection & header, std::ostream & ostr)Defined in src/http/include/icy/http/form.h:140
Writes the message boundary std::string, followed by the message header to the output stream.
writeEnd
void writeEnd(std::ostream & ostr)Defined in src/http/include/icy/http/form.h:143
Writes the final boundary std::string to the output stream.
updateProgress
virtual
virtual void updateProgress(int nread)Defined in src/http/include/icy/http/form.h:150
Updates the upload progress via the associated ConnectionStream object.
