/****************************************************************************
**
** Copyright (C) 2004-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \example network/fortuneserver
    \title Fortune Server Example

    The Fortune Server example shows how to create a server for a simple
    network service. It is intended to be run alongside the
    \l{network/fortuneclient}{Fortune Client} example or the the
    \l{network/blockingfortuneclient}{Blocking Fortune Client} example.

    \image fortuneserver-example.png Screenshot of the Fortune Server example

    This example uses QTcpServer to accept incoming TCP connections, and a
    simple QDataStream based data transfer protocol to write a fortune to the
    connecting client (from the \l{network/fortuneclient}{Fortune Client}
    example), before closing the connection.

    \snippet examples/network/fortuneserver/server.h 0

    The server is implemented using a simple class with only one slot, for
    handling incoming connections.

    \snippet examples/network/fortuneserver/server.cpp 1

    In its constructor, our Server object calls QTcpServer::listen() to set up
    a QTcpServer to listen on all addresses, on an arbitrary port. In then
    displays the port QTcpServer picked in a label, so that user knows which
    port the fortune client should connect to.

    \snippet examples/network/fortuneserver/server.cpp 2

    Our server generates a list of random fortunes that is can send to
    connecting clients.

    \snippet examples/network/fortuneserver/server.cpp 3

    When a client connects to our server, QTcpServer will emit
    QTcpServer::newConnection(). In turn, this will invoke our
    sendFortune() slot:

    \snippet examples/network/fortuneserver/server.cpp 4

    The purpose of this slot is to select a random line from our list of
    fortunes, encode it into a QByteArray using QDataStream, and then write it
    to the connecting socket. This is a common way to transfer binary data
    using QTcpSocket. First we create a QByteArray and a QDataStream object,
    passing the bytearray to QDataStream's constructor. We then explicitly set
    the protocol version of QDataStream to QDataStream::Qt_4_0 to ensure that
    we can communicate with clients from future versions of Qt. (See
    QDataStream::setVersion().)

    \snippet examples/network/fortuneserver/server.cpp 6

    At the start of our QByteArray, we reserve space for a 16 bit integer that
    will contain the total size of the data block we are sending. We continue
    by streaming in a random fortune. Then we seek back to the beginning of
    the QByteArray, and overwrite the reserved 16 bit integer value with the
    total size of the array. By doing this, we provide a way for clients to
    verify how much data they can expect before reading the whole packet.

    \snippet examples/network/fortuneserver/server.cpp 7

    We then call QTcpServer::newPendingConnection(), which returns the
    QTcpSocket representing the server side of the connection. By connecting
    QTcpSocket::disconnected() to QObject::deleteLater(), we ensure that the
    socket will be deleted after disconnecting.

    \snippet examples/network/fortuneserver/server.cpp 8

    The encoded fortune is written using QTcpSocket::write(), and we finally
    call QTcpSocket::disconnectFromHost(), which will close the connection
    after QTcpSocket has finished writing the fortune to the network. Because
    QTcpSocket works asynchronously, the data will be written after this
    function returns, and control goes back to Qt's event loop. The socket
    will then close, which in turn will cause QObject::deleteLater() to delete
    it.

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