QHttpHeaders Class

QHttpHeaders is a class for holding HTTP headers. More...

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

Public Types

enum class WellKnownHeader { AIM, Accept, AcceptAdditions, AcceptCH, AcceptDatetime, …, ProtocolQuery }

Public Functions

QHttpHeaders()
QHttpHeaders(const QHttpHeaders &other)
QHttpHeaders(QHttpHeaders &&other)
~QHttpHeaders()
bool append(QAnyStringView name, QAnyStringView value)
bool append(QHttpHeaders::WellKnownHeader name, QAnyStringView value)
void clear()
QByteArray combinedValue(QAnyStringView name) const
QByteArray combinedValue(QHttpHeaders::WellKnownHeader name) const
bool contains(QAnyStringView name) const
bool contains(QHttpHeaders::WellKnownHeader name) const
bool insert(qsizetype i, QAnyStringView name, QAnyStringView value)
bool insert(qsizetype i, QHttpHeaders::WellKnownHeader name, QAnyStringView value)
bool isEmpty() const
QLatin1StringView nameAt(qsizetype i) const
void removeAll(QAnyStringView name)
void removeAll(QHttpHeaders::WellKnownHeader name)
void removeAt(qsizetype i)
bool replace(qsizetype i, QAnyStringView name, QAnyStringView newValue)
bool replace(qsizetype i, QHttpHeaders::WellKnownHeader name, QAnyStringView newValue)
void reserve(qsizetype size)
qsizetype size() const
void swap(QHttpHeaders &other)
QList<std::pair<QByteArray, QByteArray>> toListOfPairs() const
QMultiHash<QByteArray, QByteArray> toMultiHash() const
QMultiMap<QByteArray, QByteArray> toMultiMap() const
QByteArrayView value(QAnyStringView name, QByteArrayView defaultValue = {}) const
QByteArrayView value(QHttpHeaders::WellKnownHeader name, QByteArrayView defaultValue = {}) const
QByteArrayView valueAt(qsizetype i) const
QList<QByteArray> values(QAnyStringView name) const
QList<QByteArray> values(QHttpHeaders::WellKnownHeader name) const
QHttpHeaders &operator=(const QHttpHeaders &other)
QHttpHeaders &operator=(QHttpHeaders &&other)

Static Public Members

QHttpHeaders fromListOfPairs(const QList<std::pair<QByteArray, QByteArray>> &headers)
QHttpHeaders fromMultiHash(const QMultiHash<QByteArray, QByteArray> &headers)
QHttpHeaders fromMultiMap(const QMultiMap<QByteArray, QByteArray> &headers)
QByteArrayView wellKnownHeaderName(QHttpHeaders::WellKnownHeader name)
QDebug operator<<(QDebug debug, const QHttpHeaders &headers)

Detailed Description

The class is an interface type for Qt networking APIs that use or consume such headers.

Allowed field name and value characters

An HTTP header consists of name and value. When setting these, QHttpHeaders validates name and value to only contain characters allowed by the HTTP RFCs. For detailed information see RFC 9110 Chapters 5.1 and 5.5.

In all, this means:

  • name must consist of visible ASCII characters, and must not be empty
  • value may consist of arbitrary bytes, as long as header and use case specific encoding rules are adhered to. value may be empty

The setters of this class automatically remove any leading or trailing whitespaces from value, as they must be ignored during the value processing.

Combining values

Most HTTP header values can be combined with a single comma ',' plus an optional whitespace, and the semantic meaning is preserved. As an example, these two should be semantically similar:

 // Values as separate header entries
 myheadername: myheadervalue1
 myheadername: myheadervalue2
 // Combined value
 myheadername: myheadervalue1, myheadervalue2

However, there is a notable exception to this rule: Set-Cookie. Due to this and the possibility of custom use cases, QHttpHeaders does not automatically combine the values.

Performance

Most QHttpHeaders functions provide both QHttpHeaders::WellKnownHeader and QAnyStringView overloads. From a memory-usage and computation point of view it is recommended to use the QHttpHeaders::WellKnownHeader overloads.

Member Type Documentation

enum class QHttpHeaders::WellKnownHeader

List of well known headers as per IANA registry.

ConstantValue
QHttpHeaders::WellKnownHeader::AIM0
QHttpHeaders::WellKnownHeader::Accept1
QHttpHeaders::WellKnownHeader::AcceptAdditions2
QHttpHeaders::WellKnownHeader::AcceptCH3
QHttpHeaders::WellKnownHeader::AcceptDatetime4
QHttpHeaders::WellKnownHeader::AcceptEncoding5
QHttpHeaders::WellKnownHeader::AcceptFeatures6
QHttpHeaders::WellKnownHeader::AcceptLanguage7
QHttpHeaders::WellKnownHeader::AcceptPatch8
QHttpHeaders::WellKnownHeader::AcceptPost9
QHttpHeaders::WellKnownHeader::AcceptRanges10
QHttpHeaders::WellKnownHeader::AcceptSignature11
QHttpHeaders::WellKnownHeader::AccessControlAllowCredentials12
QHttpHeaders::WellKnownHeader::AccessControlAllowHeaders13
QHttpHeaders::WellKnownHeader::AccessControlAllowMethods14
QHttpHeaders::WellKnownHeader::AccessControlAllowOrigin15
QHttpHeaders::WellKnownHeader::AccessControlExposeHeaders16
QHttpHeaders::WellKnownHeader::AccessControlMaxAge17
QHttpHeaders::WellKnownHeader::AccessControlRequestHeaders18
QHttpHeaders::WellKnownHeader::AccessControlRequestMethod19
QHttpHeaders::WellKnownHeader::Age20
QHttpHeaders::WellKnownHeader::Allow21
QHttpHeaders::WellKnownHeader::ALPN22
QHttpHeaders::WellKnownHeader::AltSvc23
QHttpHeaders::WellKnownHeader::AltUsed24
QHttpHeaders::WellKnownHeader::Alternates25
QHttpHeaders::WellKnownHeader::ApplyToRedirectRef26
QHttpHeaders::WellKnownHeader::AuthenticationControl27
QHttpHeaders::WellKnownHeader::AuthenticationInfo28
QHttpHeaders::WellKnownHeader::Authorization29
QHttpHeaders::WellKnownHeader::CacheControl30
QHttpHeaders::WellKnownHeader::CacheStatus31
QHttpHeaders::WellKnownHeader::CalManagedID32
QHttpHeaders::WellKnownHeader::CalDAVTimezones33
QHttpHeaders::WellKnownHeader::CapsuleProtocol34
QHttpHeaders::WellKnownHeader::CDNCacheControl35
QHttpHeaders::WellKnownHeader::CDNLoop36
QHttpHeaders::WellKnownHeader::CertNotAfter37
QHttpHeaders::WellKnownHeader::CertNotBefore38
QHttpHeaders::WellKnownHeader::ClearSiteData39
QHttpHeaders::WellKnownHeader::ClientCert40
QHttpHeaders::WellKnownHeader::ClientCertChain41
QHttpHeaders::WellKnownHeader::Close42
QHttpHeaders::WellKnownHeader::Connection43
QHttpHeaders::WellKnownHeader::ContentDigest44
QHttpHeaders::WellKnownHeader::ContentDisposition45
QHttpHeaders::WellKnownHeader::ContentEncoding46
QHttpHeaders::WellKnownHeader::ContentID47
QHttpHeaders::WellKnownHeader::ContentLanguage48
QHttpHeaders::WellKnownHeader::ContentLength49
QHttpHeaders::WellKnownHeader::ContentLocation50
QHttpHeaders::WellKnownHeader::ContentRange51
QHttpHeaders::WellKnownHeader::ContentSecurityPolicy52
QHttpHeaders::WellKnownHeader::ContentSecurityPolicyReportOnly53
QHttpHeaders::WellKnownHeader::ContentType54
QHttpHeaders::WellKnownHeader::Cookie55
QHttpHeaders::WellKnownHeader::CrossOriginEmbedderPolicy56
QHttpHeaders::WellKnownHeader::CrossOriginEmbedderPolicyReportOnly57
QHttpHeaders::WellKnownHeader::CrossOriginOpenerPolicy58
QHttpHeaders::WellKnownHeader::CrossOriginOpenerPolicyReportOnly59
QHttpHeaders::WellKnownHeader::CrossOriginResourcePolicy60
QHttpHeaders::WellKnownHeader::DASL61
QHttpHeaders::WellKnownHeader::Date62
QHttpHeaders::WellKnownHeader::DAV63
QHttpHeaders::WellKnownHeader::DeltaBase64
QHttpHeaders::WellKnownHeader::Depth65
QHttpHeaders::WellKnownHeader::Destination66
QHttpHeaders::WellKnownHeader::DifferentialID67
QHttpHeaders::WellKnownHeader::DPoP68
QHttpHeaders::WellKnownHeader::DPoPNonce69
QHttpHeaders::WellKnownHeader::EarlyData70
QHttpHeaders::WellKnownHeader::ETag71
QHttpHeaders::WellKnownHeader::Expect72
QHttpHeaders::WellKnownHeader::ExpectCT73
QHttpHeaders::WellKnownHeader::Expires74
QHttpHeaders::WellKnownHeader::Forwarded75
QHttpHeaders::WellKnownHeader::From76
QHttpHeaders::WellKnownHeader::Hobareg77
QHttpHeaders::WellKnownHeader::Host78
QHttpHeaders::WellKnownHeader::If79
QHttpHeaders::WellKnownHeader::IfMatch80
QHttpHeaders::WellKnownHeader::IfModifiedSince81
QHttpHeaders::WellKnownHeader::IfNoneMatch82
QHttpHeaders::WellKnownHeader::IfRange83
QHttpHeaders::WellKnownHeader::IfScheduleTagMatch84
QHttpHeaders::WellKnownHeader::IfUnmodifiedSince85
QHttpHeaders::WellKnownHeader::IM86
QHttpHeaders::WellKnownHeader::IncludeReferredTokenBindingID87
QHttpHeaders::WellKnownHeader::KeepAlive88
QHttpHeaders::WellKnownHeader::Label89
QHttpHeaders::WellKnownHeader::LastEventID90
QHttpHeaders::WellKnownHeader::LastModified91
QHttpHeaders::WellKnownHeader::Link92
QHttpHeaders::WellKnownHeader::Location93
QHttpHeaders::WellKnownHeader::LockToken94
QHttpHeaders::WellKnownHeader::MaxForwards95
QHttpHeaders::WellKnownHeader::MementoDatetime96
QHttpHeaders::WellKnownHeader::Meter97
QHttpHeaders::WellKnownHeader::MIMEVersion98
QHttpHeaders::WellKnownHeader::Negotiate99
QHttpHeaders::WellKnownHeader::NEL100
QHttpHeaders::WellKnownHeader::ODataEntityId101
QHttpHeaders::WellKnownHeader::ODataIsolation102
QHttpHeaders::WellKnownHeader::ODataMaxVersion103
QHttpHeaders::WellKnownHeader::ODataVersion104
QHttpHeaders::WellKnownHeader::OptionalWWWAuthenticate105
QHttpHeaders::WellKnownHeader::OrderingType106
QHttpHeaders::WellKnownHeader::Origin107
QHttpHeaders::WellKnownHeader::OriginAgentCluster108
QHttpHeaders::WellKnownHeader::OSCORE109
QHttpHeaders::WellKnownHeader::OSLCCoreVersion110
QHttpHeaders::WellKnownHeader::Overwrite111
QHttpHeaders::WellKnownHeader::PingFrom112
QHttpHeaders::WellKnownHeader::PingTo113
QHttpHeaders::WellKnownHeader::Position114
QHttpHeaders::WellKnownHeader::Prefer115
QHttpHeaders::WellKnownHeader::PreferenceApplied116
QHttpHeaders::WellKnownHeader::Priority117
QHttpHeaders::WellKnownHeader::ProxyAuthenticate118
QHttpHeaders::WellKnownHeader::ProxyAuthenticationInfo119
QHttpHeaders::WellKnownHeader::ProxyAuthorization120
QHttpHeaders::WellKnownHeader::ProxyStatus121
QHttpHeaders::WellKnownHeader::PublicKeyPins122
QHttpHeaders::WellKnownHeader::PublicKeyPinsReportOnly123
QHttpHeaders::WellKnownHeader::Range124
QHttpHeaders::WellKnownHeader::RedirectRef125
QHttpHeaders::WellKnownHeader::Referer126
QHttpHeaders::WellKnownHeader::Refresh127
QHttpHeaders::WellKnownHeader::ReplayNonce128
QHttpHeaders::WellKnownHeader::ReprDigest129
QHttpHeaders::WellKnownHeader::RetryAfter130
QHttpHeaders::WellKnownHeader::ScheduleReply131
QHttpHeaders::WellKnownHeader::ScheduleTag132
QHttpHeaders::WellKnownHeader::SecPurpose133
QHttpHeaders::WellKnownHeader::SecTokenBinding134
QHttpHeaders::WellKnownHeader::SecWebSocketAccept135
QHttpHeaders::WellKnownHeader::SecWebSocketExtensions136
QHttpHeaders::WellKnownHeader::SecWebSocketKey137
QHttpHeaders::WellKnownHeader::SecWebSocketProtocol138
QHttpHeaders::WellKnownHeader::SecWebSocketVersion139
QHttpHeaders::WellKnownHeader::Server140
QHttpHeaders::WellKnownHeader::ServerTiming141
QHttpHeaders::WellKnownHeader::SetCookie142
QHttpHeaders::WellKnownHeader::Signature143
QHttpHeaders::WellKnownHeader::SignatureInput144
QHttpHeaders::WellKnownHeader::SLUG145
QHttpHeaders::WellKnownHeader::SoapAction146
QHttpHeaders::WellKnownHeader::StatusURI147
QHttpHeaders::WellKnownHeader::StrictTransportSecurity148
QHttpHeaders::WellKnownHeader::Sunset149
QHttpHeaders::WellKnownHeader::SurrogateCapability150
QHttpHeaders::WellKnownHeader::SurrogateControl151
QHttpHeaders::WellKnownHeader::TCN152
QHttpHeaders::WellKnownHeader::TE153
QHttpHeaders::WellKnownHeader::Timeout154
QHttpHeaders::WellKnownHeader::Topic155
QHttpHeaders::WellKnownHeader::Traceparent156
QHttpHeaders::WellKnownHeader::Tracestate157
QHttpHeaders::WellKnownHeader::Trailer158
QHttpHeaders::WellKnownHeader::TransferEncoding159
QHttpHeaders::WellKnownHeader::TTL160
QHttpHeaders::WellKnownHeader::Upgrade161
QHttpHeaders::WellKnownHeader::Urgency162
QHttpHeaders::WellKnownHeader::UserAgent163
QHttpHeaders::WellKnownHeader::VariantVary164
QHttpHeaders::WellKnownHeader::Vary165
QHttpHeaders::WellKnownHeader::Via166
QHttpHeaders::WellKnownHeader::WantContentDigest167
QHttpHeaders::WellKnownHeader::WantReprDigest168
QHttpHeaders::WellKnownHeader::WWWAuthenticate169
QHttpHeaders::WellKnownHeader::XContentTypeOptions170
QHttpHeaders::WellKnownHeader::XFrameOptions171
QHttpHeaders::WellKnownHeader::AcceptCharset172
QHttpHeaders::WellKnownHeader::CPEPInfo173
QHttpHeaders::WellKnownHeader::Pragma174
QHttpHeaders::WellKnownHeader::ProtocolInfo175
QHttpHeaders::WellKnownHeader::ProtocolQuery176

Member Function Documentation

[noexcept] QHttpHeaders::QHttpHeaders()

Creates a new QHttpHeaders object.

QHttpHeaders::QHttpHeaders(const QHttpHeaders &other)

Creates a copy of other.

[noexcept] QHttpHeaders::QHttpHeaders(QHttpHeaders &&other)

Move-constructs the object from other, which will be left empty.

[noexcept] QHttpHeaders::~QHttpHeaders()

Disposes of the headers object.

bool QHttpHeaders::append(QAnyStringView name, QAnyStringView value)

Appends a header entry with name and value and returns true if successful.

See also append(QHttpHeaders::WellKnownHeader, QAnyStringView) and Allowed field name and value characters.

bool QHttpHeaders::append(QHttpHeaders::WellKnownHeader name, QAnyStringView value)

This function overloads append(QAnyStringView, QAnyStringView).

void QHttpHeaders::clear()

Clears all header entries.

See also size().

QByteArray QHttpHeaders::combinedValue(QAnyStringView name) const

Returns the values of header name in a comma-combined string. Returns a null QByteArray if the header with name doesn't exist.

Note: Accessing the value(s) of 'Set-Cookie' header this way may not work as intended. It is a notable exception in the HTTP RFC in that its values cannot be combined this way. Prefer values() instead.

See also values(QAnyStringView).

QByteArray QHttpHeaders::combinedValue(QHttpHeaders::WellKnownHeader name) const

This function overloads combinedValue(QAnyStringView).

bool QHttpHeaders::contains(QAnyStringView name) const

Returns whether the headers contain header with name.

See also contains(QHttpHeaders::WellKnownHeader).

bool QHttpHeaders::contains(QHttpHeaders::WellKnownHeader name) const

This function overloads has(QAnyStringView).

[static] QHttpHeaders QHttpHeaders::fromListOfPairs(const QList<std::pair<QByteArray, QByteArray>> &headers)

Creates a new QHttpHeaders object that is populated with headers.

See also Allowed field name and value characters.

[static] QHttpHeaders QHttpHeaders::fromMultiHash(const QMultiHash<QByteArray, QByteArray> &headers)

Creates a new QHttpHeaders object that is populated with headers.

See also Allowed field name and value characters.

[static] QHttpHeaders QHttpHeaders::fromMultiMap(const QMultiMap<QByteArray, QByteArray> &headers)

Creates a new QHttpHeaders object that is populated with headers.

See also Allowed field name and value characters.

bool QHttpHeaders::insert(qsizetype i, QAnyStringView name, QAnyStringView value)

Inserts a header entry at index i, with name and value. The index must be valid (see size()). Returns whether the insert succeeded.

See also append(), insert(qsizetype, QHttpHeaders::WellKnownHeader, QAnyStringView), size(), and Allowed field name and value characters.

bool QHttpHeaders::insert(qsizetype i, QHttpHeaders::WellKnownHeader name, QAnyStringView value)

This function overloads insert(qsizetype, QAnyStringView, QAnyStringView).

[noexcept] bool QHttpHeaders::isEmpty() const

Returns true if the headers have size 0; otherwise returns false.

See also size().

[noexcept] QLatin1StringView QHttpHeaders::nameAt(qsizetype i) const

Returns the header name at index i. The index i must be valid (see size()).

Header names are case-insensitive, and the returned names are lower-cased.

See also size() and valueAt().

void QHttpHeaders::removeAll(QAnyStringView name)

Removes the header name.

See also removeAt() and removeAll(QHttpHeaders::WellKnownHeader).

void QHttpHeaders::removeAll(QHttpHeaders::WellKnownHeader name)

This function overloads removeAll(QAnyStringView).

void QHttpHeaders::removeAt(qsizetype i)

Removes the header at index i. The index i must be valid (see size()).

See also removeAll(QHttpHeaders::WellKnownHeader), removeAll(QAnyStringView), and size().

bool QHttpHeaders::replace(qsizetype i, QAnyStringView name, QAnyStringView newValue)

Replaces the header entry at index i, with name and newValue. The index must be valid (see size()). Returns whether the replace succeeded.

See also append(), replace(qsizetype, QHttpHeaders::WellKnownHeader, QAnyStringView), size(), and Allowed field name and value characters.

bool QHttpHeaders::replace(qsizetype i, QHttpHeaders::WellKnownHeader name, QAnyStringView newValue)

This function overloads replace(qsizetype, QAnyStringView, QAnyStringView).

void QHttpHeaders::reserve(qsizetype size)

Attempts to allocate memory for at least size header entries.

If you know in advance how how many header entries there will be, you may call this function to prevent reallocations and memory fragmentation.

[noexcept] qsizetype QHttpHeaders::size() const

Returns the number of header entries.

[noexcept] void QHttpHeaders::swap(QHttpHeaders &other)

Swaps this QHttpHeaders with other. This function is very fast and never fails.

QList<std::pair<QByteArray, QByteArray>> QHttpHeaders::toListOfPairs() const

Returns the header entries as a list of (name, value) pairs. Header names are case-insensitive, and the returned names are lower-cased.

QMultiHash<QByteArray, QByteArray> QHttpHeaders::toMultiHash() const

Returns the header entries as a hash from name to value(s). Header names are case-insensitive, and the returned names are lower-cased.

QMultiMap<QByteArray, QByteArray> QHttpHeaders::toMultiMap() const

Returns the header entries as a map from name to value(s). Header names are case-insensitive, and the returned names are lower-cased.

[noexcept] QByteArrayView QHttpHeaders::value(QAnyStringView name, QByteArrayView defaultValue = {}) const

Returns the value of the (first) header name, or defaultValue if it doesn't exist.

See also value(QHttpHeaders::WellKnownHeader, QByteArrayView).

[noexcept] QByteArrayView QHttpHeaders::value(QHttpHeaders::WellKnownHeader name, QByteArrayView defaultValue = {}) const

This function overloads value(QAnyStringView, QByteArrayView).

[noexcept] QByteArrayView QHttpHeaders::valueAt(qsizetype i) const

Returns the header value at index i. The index i must be valid (see size()).

See also size(), value(), values(), combinedValue(), and nameAt().

QList<QByteArray> QHttpHeaders::values(QAnyStringView name) const

Returns the values of header name in a list. Returns an empty list if header with name doesn't exist.

See also values(QHttpHeaders::WellKnownHeader).

QList<QByteArray> QHttpHeaders::values(QHttpHeaders::WellKnownHeader name) const

This function overloads values(QAnyStringView).

[static noexcept] QByteArrayView QHttpHeaders::wellKnownHeaderName(QHttpHeaders::WellKnownHeader name)

Returns a header name corresponding to the provided name as a view.

QHttpHeaders &QHttpHeaders::operator=(const QHttpHeaders &other)

Assigns the contents of other and returns a reference to this object.

[noexcept] QHttpHeaders &QHttpHeaders::operator=(QHttpHeaders &&other)

Move-assigns other and returns a reference to this object.

other will be left empty.

Related Non-Members

QDebug operator<<(QDebug debug, const QHttpHeaders &headers)

Writes headers into debug stream.