/****************************************************************************
**
** Copyright (C) 2016 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$
**
****************************************************************************/

/*!
    \example fortuneclient
    \title Fortune Client Example
    \ingroup examples-network
    \brief Demonstrates how to create a client for a network service.

    This example uses QTcpSocket, and is intended to be run alongside the
    \l{fortuneserver}{Fortune Server} example or
    the \l{threadedfortuneserver}{Threaded Fortune Server} example.

    \image fortuneclient-example.png Screenshot of the Fortune Client example

    This example uses a simple QDataStream-based data transfer protocol to
    request a line of text from a fortune server (from the
    \l{fortuneserver}{Fortune Server} example). The client requests a
    fortune by simply connecting to the server. The server then responds with
    a QString which contains the fortune text.

    QTcpSocket supports two general approaches to network programming:

    \list

    \li \e{The asynchronous (non-blocking) approach.} Operations are scheduled
    and performed when control returns to Qt's event loop. When the operation
    is finished, QTcpSocket emits a signal. For example,
    QTcpSocket::connectToHost() returns immediately, and when the connection
    has been established, QTcpSocket emits
    \l{QTcpSocket::connected()}{connected()}.

    \li \e{The synchronous (blocking) approach.} In non-GUI and multithreaded
    applications, you can call the \c waitFor...() functions (e.g.,
    QTcpSocket::waitForConnected()) to suspend the calling thread until the
    operation has completed, instead of connecting to signals.

    \endlist

    In this example, we will demonstrate the asynchronous approach. The
    \l{blockingfortuneclient}{Blocking Fortune Client Example}
    illustrates the synchronous approach.

    Our class contains some data and a few private slots:

    \snippet fortuneclient/client.h 0

    Other than the widgets that make up the GUI, the data members include a
    QTcpSocket pointer, a QDataStream object that operates on the socket, and
    a copy of the fortune text currently displayed.

    The socket is initialized in the Client constructor. We'll pass the main
    widget as parent, so that we won't have to worry about deleting the
    socket:

    \snippet fortuneclient/client.cpp 0
    \dots
    \snippet fortuneclient/client.cpp 1

    The protocol is based on QDataStream, so we set the stream device to the
    newly created socket. We then explicitly set the protocol version of the
    stream to QDataStream::Qt_4_0 to ensure that we're using the same version
    as the fortune server, no matter which version of Qt the client and
    server use.

    The only QTcpSocket signals we need in this example are
    QTcpSocket::readyRead(), signifying that data has been received, and
    QTcpSocket::error(), which we will use to catch any connection errors:

    \dots
    \snippet fortuneclient/client.cpp 3
    \dots
    \snippet fortuneclient/client.cpp 5

    Clicking the \uicontrol{Get Fortune} button will invoke the \c
    requestNewFortune() slot:

    \snippet fortuneclient/client.cpp 6

    Because we allow the user to click \uicontrol{Get Fortune} before the
    previous connection finished closing, we start off by aborting the
    previous connection by calling QTcpSocket::abort(). (On an unconnected
    socket, this function does nothing.) We then proceed to connecting to the
    fortune server by calling QTcpSocket::connectToHost(), passing the
    hostname and port from the user interface as arguments.

    As a result of calling \l{QTcpSocket::connectToHost()}{connectToHost()},
    one of two things can happen:

    \list
    \li \e{The connection is established.} In this case, the server will send us a
    fortune. QTcpSocket will emit \l{QTcpSocket::readyRead()}{readyRead()}
    every time it receives a block of data.

    \li \e{An error occurs.} We need to inform the user if the connection
    failed or was broken. In this case, QTcpSocket will emit
    \l{QTcpSocket::error()}{error()}, and \c Client::displayError() will be
    called.
    \endlist

    Let's go through the \l{QTcpSocket::error()}{error()} case first:

    \snippet fortuneclient/client.cpp 13

    We pop up all errors in a dialog using
    QMessageBox::information(). QTcpSocket::RemoteHostClosedError is silently
    ignored, because the fortune server protocol ends with the server closing
    the connection.

    Now for the \l{QTcpSocket::readyRead()}{readyRead()} alternative. This
    signal is connected to \c Client::readFortune():

    \snippet fortuneclient/client.cpp 8

    Now, TCP is based on sending a stream of data, so we cannot expect to get
    the entire fortune in one go. Especially on a slow network, the data can
    be received in several small fragments. QTcpSocket buffers up all incoming
    data and emits \l{QTcpSocket::readyRead()}{readyRead()} for every new
    block that arrives, and it is our job to ensure that we have received all
    the data we need before we start parsing.

    For this purpose we use a QDataStream read transaction. It keeps reading
    stream data into an internal buffer and rolls it back in case of an
    incomplete read. We start by calling startTransaction() which also resets
    the stream status to indicate that new data was received on the socket.
    We proceed by using QDataStream's streaming operator to read the fortune
    from the socket into a QString. Once read, we complete the transaction by
    calling QDataStream::commitTransaction(). If we did not receive a full
    packet, this function restores the stream data to the initial position,
    after which we can wait for a new readyRead() signal.

    After a successful read transaction, we call QLabel::setText() to display
    the fortune.

    \sa {Fortune Server Example}, {Blocking Fortune Client Example}
*/