QFormDataBuilder Class | Qt Network 6.8.3 (original) (raw)

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

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

Public Types

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

Public Functions

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

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.