QFormDataBuilder Class

The QFormDataBuilder class is a convenience class to simplify the construction of QHttpMultiPart objects. More...

Header:	`#include <QFormDataBuilder>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS Network)` `target_link_libraries(mytarget PRIVATE Qt6::Network)`
qmake:	`QT += network`
Since:	Qt 6.8

List of all members, including inherited members
QFormDataBuilder is part of Network Programming API and Implicitly Shared Classes.

Public Types

enum class	Option { Default, OmitRfc8187EncodedFilename, UseRfc7578PercentEncodedFilename, PreferLatin1EncodedFilename, StrictRfc7578 }
flags	Options

Public Functions

	QFormDataBuilder()
	QFormDataBuilder(QFormDataBuilder &&other)
	~QFormDataBuilder()
std::unique_ptr<QHttpMultiPart>	buildMultiPart(QFormDataBuilder::Options options = {})
QFormDataPartBuilder	part(QAnyStringView name)
QFormDataBuilder &	operator=(QFormDataBuilder &&other)

Detailed Description

The QFormDataBuilder class can be used to build a QHttpMultiPart object with the content type set to be FormDataType by default.

The snippet below demonstrates how to build a multipart message with QFormDataBuilder:

 QFormDataBuilder builder;
 QFile image(u"../../pic.png"_s); image.open(QFile::ReadOnly);
 QFile mask(u"../../mask.png"_s); mask.open(QFile::ReadOnly);

 builder.part("image"_L1).setBodyDevice(&image, "the actual image");
 builder.part("mask"_L1).setBodyDevice(&mask, "the mask image");
 builder.part("prompt"_L1).setBody("Lobster wearing a beret");
 builder.part("n"_L1).setBody("2");
 builder.part("size"_L1).setBody("512x512");

 std::unique_ptr<QHttpMultiPart> mp = builder.buildMultiPart();

See also QHttpPart, QHttpMultiPart, and QFormDataPartBuilder.

Member Type Documentation

enum class QFormDataBuilder::Option
flags QFormDataBuilder::Options

Options controlling buildMultiPart().

Several current RFCs disagree on how, exactly, to format multipart/form-data. Instead of hard-coding any one RFC, these options give you control over which RFC to follow.

Constant	Value	Description
`QFormDataBuilder::Option::Default`	`0x00`	The default values, designed to maximize interoperability in general. All options named below are off.
`QFormDataBuilder::Option::OmitRfc8187EncodedFilename`	`0x01`	When a body-part's file-name contains non-US-ASCII characters, RFC 6266 Section 4.3 suggests to use RFC 8187-style encoding (`filename=utf-8''...`). The more recent RFC 7578 Section 4.2, however, bans the use of that mechanism. Both RFCs are current as of this writing, so this option allows you to choose which one to follow. The default is to include the RFC 8187-encoded `filename` alongside the unencoded `filename`, as suggested by RFC 6266.
`QFormDataBuilder::Option::UseRfc7578PercentEncodedFilename`	`0x02`	When a body-part's file-name contains non-US-ASCII characters, RFC 7578 Section 4.2 suggests to use percent-encoding of the octets of the UTF-8-encoded file-name. It goes on to note that many implementations, however, do not percent-encode the UTF-8-encoded file-name, but just emit "raw" UTF-8 (with `"` and `\` escaped using `\`). This is the default of QFormDataBuilder, too.
`QFormDataBuilder::Option::PreferLatin1EncodedFilename`	`0x04`	RFC 5987 Section 3.2 required recipients to support ISO-8859-1 ("Latin-1") encoding. When a body-part's file-name contains non-US-ASCII characters that, however, fit into Latin-1, this option prefers to use ISO-8859-1 encoding over UTF-8. The more recent {https://datatracker.ietf.org/doc/html/rfc8187#appendix-A}{RFC 8187} no longer requires ISO-8859-1 support, so the default is to send all non-US-ASCII file-names in UTF-8 encoding instead.
`QFormDataBuilder::Option::StrictRfc7578`	`OmitRfc8187EncodedFilename \| UseRfc7578PercentEncodedFilename`	This option combines other options to select strict RFC 7578 compliance.

The Options type is a typedef for QFlags<Option>. It stores an OR combination of Option values.

Member Function Documentation

QFormDataBuilder::QFormDataBuilder()

Constructs an empty QFormDataBuilder object.

`[noexcept]` QFormDataBuilder::QFormDataBuilder(QFormDataBuilder &&other)

Move-constructs a QFormDataBuilder instance, making it point at the same object that other was pointing to.

`[noexcept]` QFormDataBuilder::~QFormDataBuilder()

Destroys the QFormDataBuilder object.

std::unique_ptr<QHttpMultiPart> QFormDataBuilder::buildMultiPart(QFormDataBuilder::Options options = {})

Constructs and returns a pointer to a QHttpMultipart object constructed according to options.

See also QHttpMultiPart.

QFormDataPartBuilder QFormDataBuilder::part(QAnyStringView name)

Returns a newly-constructed QFormDataPartBuilder object using name as the form-data's name parameter. The object is valid for as long as the associated QFormDataBuilder has not been destroyed.

Limiting name characters to US-ASCII is strongly recommended for interoperability reasons.

See also QFormDataPartBuilder and QHttpPart.

`[noexcept]` QFormDataBuilder &QFormDataBuilder::operator=(QFormDataBuilder &&other)

Move-assigns other to this QFormDataBuilder instance.

Contents