/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
    \page network-changes-qt6.html
    \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
    efficient and easy to use.

    We try to maintain binary and source compatibility for all the public
    APIs in each release. But some changes were inevitable in an effort to
    make Qt a better framework.

    In this topic we summarize those changes in Qt Network, and provide
    guidance to handle them.

    \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()}.
*/
