diff options
Diffstat (limited to 'src/network/doc/src/qt6-changes.qdoc')
| -rw-r--r-- | src/network/doc/src/qt6-changes.qdoc | 197 |
1 files changed, 168 insertions, 29 deletions
diff --git a/src/network/doc/src/qt6-changes.qdoc b/src/network/doc/src/qt6-changes.qdoc index 21c40dae68..3adce84760 100644 --- a/src/network/doc/src/qt6-changes.qdoc +++ b/src/network/doc/src/qt6-changes.qdoc @@ -1,34 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page network-changes-qt6.html - \title Porting to Qt 6 - Qt Network - \ingroup porting-guides-5-to-6 + \title Changes to Qt Network + \ingroup changes-qt-5-to-6 \brief Migrate Qt Network to Qt 6. Qt 6 is a result of the conscious effort to make the framework more @@ -41,6 +17,169 @@ In this topic we summarize those changes in Qt Network, and provide guidance to handle them. - \section1 ADD STUFF HERE + \section1 API changes + \section2 Ambiguous name overloads + + Several ambiguous overloaded functions are removed. The error() signal + is replaced by errorOccurred() in QAbstractSocket and its heirs + (QTcpSocket, QUdpSocket, QLocalSocket, and QSslSocket), and in QNetworkReply. + Code such as: + + \code + connect(socket, qOverload<QAbstractSocket::SocketError>(&QAbstractSocket::error), + this, &SomeClass::errorSlot); + \endcode + + must therefore be changed to: + + \code + connect(socket, &QAbstractSocket::errorOccurred, this, &SomeClass::errorSlot); + \endcode + + In QSslSocket, the function that returns a list of errors encountered + during the TLS handshake: + + \code + QList<QSslError> sslErrors() const; + \endcode + + is renamed to sslHandshakeErrors(): + + \code + const auto tlsErrors = socket.sslHandshakeErrors(); + \endcode + + \section2 Bearer management is removed + + The classes QNetworkConfiguration and QNetworkConfigurationManager are removed in Qt 6. + Consequently, the following member functions of QNetworkAccessManager are also removed: + + \code + void setConfiguration(const QNetworkConfiguration &config); + QNetworkConfiguration configuration() const; + QNetworkConfiguration activeConfiguration() const; + void setNetworkAccessible(NetworkAccessibility accessible); + NetworkAccessibility networkAccessible() const; + void networkSessionConnected(); + \endcode + + QNetworkInformation, initially introduced in Qt 6.1, aims to replace some + aspects of the bearer management API. It works by providing a unified API + which subscribes to changes to the network as notified by the operating + system. + + QNetworkInformation::reachability(), introduced in Qt 6.1, replaces the + QNetworkAccessManager::networkAccessible() function, while adding more + detailed information about the reachability of the network. See its + documentation for more details. + + In Qt 6.2 QNetworkInformation gained the ability to detect captive portals. + + In Qt 6.3 QNetworkInformation gained QNetworkInformation::transportMedium() + and QNetworkInformation::isMetered(). + + \section2 Deleted enumerators + + Several enumerators are removed in QtNetwork. This includes constants + for no longer supported protocols and functionality: + + \list + \li QSsl::SslV2; + \li QSsl::SslV3; + \li QSsl::TlsV1SslV3; + \li QNetworkRequest::SpdyAllowedAttribute; + \li QNetworkRequest::SpdyWasUsedAttribute; + \li QNetworkAccessManager::UnknownAccessibility; + \li QNetworkAccessManager::NotAccessible; + \li QNetworkAccessManager::Accessible + \endlist + + and enumerators whose names did not follow proper naming conventions: + + \list + \li QSsl::TlsV1 (QSsl::TlsV1_0 is the proper name); + \li QNetworkRequest::HTTP2AllowedAttribute (use QNetworkRequest::Http2AllowedAttribute); + \li QNetworkRequest::HTTP2WasUsedAttribute (use QNetworkRequest::Http2WasUsedAttribute). + \endlist + + QNetworkRequest::FollowRedirectsAttribute is removed in Qt 6, see + \l {Redirect policies}{the section about redirects handling} below. + + \section2 Configuring QSslSocket + + The following deprecated functions are removed in Qt 6: + + \code + QList<QSslCipher> ciphers() const; + void setCiphers(const QList<QSslCipher> &ciphers); + void setCiphers(const QString &ciphers); + static void setDefaultCiphers(const QList<QSslCipher> &ciphers); + static QList<QSslCipher> defaultCiphers(); + static QList<QSslCipher> supportedCiphers(); + QList<QSslCipher> ciphers() const; + void setCiphers(const QList<QSslCipher> &ciphers); + void setCiphers(const QString &ciphers); + static void setDefaultCiphers(const QList<QSslCipher> &ciphers); + static QList<QSslCipher> defaultCiphers(); + static QList<QSslCipher> supportedCiphers(); + bool addCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem, + QRegExp::PatternSyntax syntax = QRegExp::FixedString); + void addCaCertificate(const QSslCertificate &certificate); + void addCaCertificates(const QList<QSslCertificate> &certificates); + void setCaCertificates(const QList<QSslCertificate> &certificates); + QList<QSslCertificate> caCertificates() const; + static bool addDefaultCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem, + QRegExp::PatternSyntax syntax = QRegExp::FixedString); + static void addDefaultCaCertificate(const QSslCertificate &certificate); + static void addDefaultCaCertificates(const QList<QSslCertificate> &certificates); + static void setDefaultCaCertificates(const QList<QSslCertificate> &certificates); + static QList<QSslCertificate> defaultCaCertificates(); + static QList<QSslCertificate> systemCaCertificates(); + \endcode + + Use QSslConfiguration and its member functions to set these parameters, e.g.: + + \code + auto sslConfiguration = QSslConfiguration::defaultConfiguration(); + sslConfiguration.setCiphers("ECDHE-ECDSA-AES256-SHA384"); + // Set other parameters here ... + socket.setSslConfiguration(sslConfiguration); + \endcode + + \section1 Changes in QNetworkAccessManager's default behavior + + \section2 Redirect policies + + In Qt 6, the default redirect policy has changed from manual to + QNetworkRequest::NoLessSafeRedirectPolicy. If your application relies + on manual redirect handling (it connects its slot to the QNetworkReply::redirected + signal), you have to explicitly set this policy when creating a request: + + \code + request.setAttribute(QNetworkRequest::RedirectPolicyAttribute, QNetworkRequest::ManualRedirectPolicy); + \endcode + + \section2 HTTP/2 is enabled by default + + In Qt 6 QNetworkAccessManager enables HTTP/2 protocol by default. Depending on the + scheme ("https" or "http"), QNetworkAccessManager will use the Application Layer + Protocol Negotiation TLS extension or "protocol upgrade" HTTP header to negotiate HTTP/2. + If HTTP/2 cannot be negotiated, the access manager will fall back to using HTTP/1.1. + If your application can only use HTTP/1.1, you have to disable HTTP/2 manually + on a new request: + + \code + request.setAttribute(QNetworkRequest::Http2AllowedAttribute, false); + \endcode + + \section2 QNetworkAccessManager now guards against archive bombs + + Starting with Qt 6.2 QNetworkAccessManager will guard against compressed + files that decompress to files which are much larger than their compressed + form by erroring out the reply if the decompression ratio exceeds a certain + threshold. + This check is only applied to files larger than a certain size, which can be + customized (or disabled by passing -1) by calling + \l{QNetworkRequest::setDecompressedSafetyCheckThreshold()}. */ |