/****************************************************************************
**
** Copyright (C) 2005-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.
**
****************************************************************************/

/*!
    \module QtNetwork
    \title QtNetwork Module
    \contentspage Qt's Modules
    \previouspage QtGui
    \nextpage QtOpenGL
    \ingroup modules

    \brief The QtNetwork module offers classes that allow you to
    write TCP/IP clients and servers.

    The network module provides classes to make network programming
    easier and portable. It offers classes such as QHttp and QFtp that
    implement specific application-level protocols, lower-level classes
    such as QTcpSocket, QTcpServer and QUdpSocket that represent low
    level network concepts, and high level classes such as QNetworkRequest,
    QNetworkReply and QNetworkAccessManager to perform network operations using common protocols.

    The QtNetwork module is part of the \l{Qt Console Edition}, the
    \l{Qt Desktop Edition}, and the \l{Qt Open Source Edition}.

    Topics:

    \tableofcontents

    \section1 Configuring the Build Process

    Applications that use Qt's networking classes need to
    be configured to be built against the QtNetwork module.
    The following declaration in a \c qmake project file ensures that
    an application is compiled and linked appropriately:

    \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 0

    This line is necessary because only the QtCore and QtGui modules
    are used in the default build process.

    To include the definitions of the module's classes, use the
    following directive:

    \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 1

    \section1 High Level Network Operations

    The Network Access API is a collection of classes for performing
    common network operations. The API provides an abstraction layer
    over the specific operations and protocols used (for example,
    getting and posting data over HTTP), and only exposes classes,
    functions, and signals for general or high level concepts.

    Network requests are represented by the QNetworkRequest class,
    which also acts as a general container for information associated
    with a request, such as any header information and the encryption
    used. The URL specified when a request object is constructed
    determines the protocol used for a request.

    The coordination of network operations is performed by the
    QNetworkAccessManager class. Once a request has been created,
    this class is used to dispatch it and emit signals to report on
    its progress. The manager also coordinates the use of
    \l{QNetworkCookieJar}{cookies} to store data on the client,
    authentication requests, and the use of proxies.

    Replies to network requests are represented by the QNetworkReply
    class; these are created by QNetworkAccessManager when a request
    is dispatched. The signals provided by QNetworkReply can be used
    to monitor each reply individually, or developers may choose to
    use the manager's signals for this purpose instead and discard
    references to replies. Since QNetworkReply is a subclass of
    QIODevice, replies can be handled synchronously or asynchronously;
    i.e., as blocking or non-blocking operations.

    Each application or library can create one or more instances of
    QNetworkAccessManager to handle network communication.

    \section1 Writing HTTP and FTP Clients with QHttp and QFtp

    HTTP (Hypertext Transfer Protocol) is an application-level
    network protocol used mainly for downloading HTML and XML files,
    but it is also used as a high-level transport protocol for many
    other types of data, from images and movies to purchase orders
    and banking transactions. In contrast, FTP (File Transfer
    Protocol) is a protocol used almost exclusively for browsing
    remote directories and for transferring files.

    \image httpstack.png HTTP Client and Server

    HTTP is a simpler protocol than FTP in many ways. It uses only
    one network connection, while FTP uses two (one for sending
    commands, and one for transferring data). HTTP is a stateless
    protocol; requests and responses are always self-contained. The
    FTP protocol has a state and requires the client to send several
    commands before a file transfer takes place.

    In practice, HTTP clients often use separate connections for
    separate requests, whereas FTP clients establish one connection
    and keep it open throughout the session.

    The QHttp and QFtp classes provide client-side support for HTTP
    and FTP. Since the two protocols are used to solve the same
    problems, the QHttp and QFtp classes have many features in
    common:

    \list

    \o \e{Non-blocking behavior.} QHttp and QFtp are asynchronous.
    You can schedule a series of commands (also called "requests" for
    HTTP). The commands are executed later, when control returns to
    Qt's event loop.

    \o \e{Command IDs.} Each command has a unique ID number that you
    can use to follow the execution of the command. For example, QFtp
    emits the \l{QFtp::commandStarted()}{commandStarted()} and
    \l{QFtp::commandFinished()}{commandFinished()} signal with the
    command ID for each command that is executed. QHttp has a
    \l{QHttp::requestStarted()}{requestStarted()} and a
    \l{QHttp::requestFinished()}{requestFinished()} signal that work
    the same way.

    \o \e{Data transfer progress indicators.} QHttp and QFtp emit
    signals whenever data is transferred
    (QFtp::dataTransferProgress(), QHttp::dataReadProgress(), and
    QHttp::dataSendProgress()). You could connect these signals to
    QProgressBar::setProgress() or QProgressDialog::setProgress(),
    for example.

    \o \e{QIODevice support.} Both classes support convenient
    uploading from and downloading to \l{QIODevice}s, in addition to a
    QByteArray-based API.

    \endlist

    There are two main ways of using QHttp and QFtp. The most common
    approach is to keep track of the command IDs and follow the
    execution of every command by connecting to the appropriate
    signals. The other approach is to schedule all commands at once
    and only connect to the done() signal, which is emitted when all
    scheduled commands have been executed. The first approach
    requires more work, but it gives you more control over the
    execution of individual commands and allows you to initiate new
    commands based on the result of a previous command. It also
    enables you to provide detailed feedback to the user.

    The \l{network/http}{HTTP} and \l{network/ftp}{FTP} examples
    illustrate how to write an HTTP and an FTP client.

    Writing your own HTTP or FTP server is possible using the
    lower-level classes QTcpSocket and QTcpServer.

    \section1 Using TCP with QTcpSocket and QTcpServer

    TCP (Transmission Control Protocol) is a low-level network
    protocol used by most Internet protocols, including HTTP and FTP,
    for data transfer. It is a reliable, stream-oriented,
    connection-oriented transport protocol. It is particularly well
    suited to the continuous transmission of data.

    \image tcpstream.png A TCP Stream

    The QTcpSocket class provides an interface for TCP. You can use
    QTcpSocket to implement standard network protocols such as POP3,
    SMTP, and NNTP, as well as custom protocols.

    A TCP connection must be established to a remote host and port
    before any data transfer can begin. Once the connection has been
    established, the IP address and port of the peer are available
    through QTcpSocket::peerAddress() and QTcpSocket::peerPort(). At
    any time, the peer can close the connection, and data transfer
    will then stop immediately.

    QTcpSocket works asynchronously and emits signals to report status
    changes and errors, just like QHttp and QFtp. It relies on the
    event loop to detect incoming data and to automatically flush
    outgoing data. You can write data to the socket using
    QTcpSocket::write(), and read data using
    QTcpSocket::read(). QTcpSocket represents two independent streams
    of data: one for reading and one for writing.

    Since QTcpSocket inherits QIODevice, you can use it with
    QTextStream and QDataStream. When reading from a QTcpSocket, you
    must make sure that enough data is available by calling
    QTcpSocket::bytesAvailable() beforehand.

    If you need to handle incoming TCP connections (e.g., in a server
    application), use the QTcpServer class. Call QTcpServer::listen()
    to set up the server, and connect to the
    QTcpServer::newConnection() signal, which is emitted once for
    every client that connects. In your slot, call
    QTcpServer::nextPendingConnection() to accept the connection and
    use the returned QTcpSocket to communicate with the client.

    Although most of its functions work asynchronously, it's possible
    to use QTcpSocket synchronously (i.e., blocking). To get blocking
    behavior, call QTcpSocket's waitFor...() functions; these suspend
    the calling thread until a signal has been emitted. For example,
    after calling the non-blocking QTcpSocket::connectToHost()
    function, call QTcpSocket::waitForConnected() to block the thread
    until the \l{QTcpSocket::connected()}{connected()} signal has
    been emitted.

    Synchronous sockets often lead to code with a simpler flow of
    control. The main disadvantage of the waitFor...() approach is
    that events won't be processed while a waitFor...() function is
    blocking. If used in the GUI thread, this might freeze the
    application's user interface. For this reason, we recommend that
    you use synchronous sockets only in non-GUI threads. When used
    synchronously, QTcpSocket doesn't require an event loop.

    The \l{network/fortuneclient}{Fortune Client} and
    \l{network/fortuneserver}{Fortune Server} examples show how to use
    QTcpSocket and QTcpServer to write TCP client-server
    applications. See also \l{network/blockingfortuneclient}{Blocking
    Fortune Client} for an example on how to use a synchronous
    QTcpSocket in a separate thread (without using an event loop),
    and \l{network/threadedfortuneserver}{Threaded Fortune Server}
    for an example of a multithreaded TCP server with one thread per
    active client.

    \section1 Using UDP with QUdpSocket

    UDP (User Datagram Protocol) is a lightweight, unreliable,
    datagram-oriented, connectionless protocol. It can be used when
    reliability isn't important. For example, a server that reports
    the time of day could choose UDP. If a datagram with the time of
    day is lost, the client can simply make another request.

    \image udppackets.png UDP Packets

    The QUdpSocket class allows you to send and receive UDP
    datagrams. It inherits QAbstractSocket, and it therefore shares
    most of QTcpSocket's interface. The main difference is that
    QUdpSocket transfers data as datagrams instead of as a continuous
    stream of data. In short, a datagram is a data packet of limited
    size (normally smaller than 512 bytes), containing the IP address
    and port of the datagram's sender and receiver in addition to the
    data being transferred.

    QUdpSocket supports IPv4 broadcasting. Broadcasting is often used
    to implement network discovery protocols, such as finding which
    host on the network has the most free hard disk space. One host
    broadcasts a datagram to the network that all other hosts
    receive. Each host that receives a request then sends a reply
    back to the sender with its current amount of free disk space.
    The originator waits until it has received replies from all
    hosts, and can then choose the server with most free space to
    store data. To broadcast a datagram, simply send it to the
    special address QHostAddress::Broadcast (255.255.255.255), or
    to your local network's broadcast address.

    QUdpSocket::bind() prepares the socket for accepting incoming
    datagrams, much like QTcpServer::listen() for TCP servers.
    Whenever one or more datagrams arrive, QUdpSocket emits the
    \l{QUdpSocket::readyRead()}{readyRead()} signal. Call
    QUdpSocket::readDatagram() to read the datagram.

    The \l{network/broadcastsender}{Broadcast Sender} and
    \l{network/broadcastreceiver}{Broadcast Receiver} examples show
    how to write a UDP sender and a UDP receiver using Qt.

    \section1 Resolving Host Names using QHostInfo

    Before establishing a network connection, QTcpSocket and
    QUdpSocket perform a name lookup, translating the host name
    you're connecting to into an IP address. This operation is
    usually performed using the DNS (Domain Name Service) protocol.

    QHostInfo provides a static function that lets you perform such a
    lookup yourself. By calling QHostInfo::lookupHost() with a host
    name, a QObject pointer, and a slot signature, QHostInfo will
    perform the name lookup and invoke the given slot when the
    results are ready. The actual lookup is done in a separate
    thread, making use of the operating system's own methods for
    performing name lookups.

    QHostInfo also provides a static function called
    QHostInfo::fromName() that takes the host name as argument and
    returns the results. In this case, the name lookup is performed
    in the same thread as the caller. This overload is useful for
    non-GUI applications or for doing name lookups in a separate,
    non-GUI thread. (Calling this function in a GUI thread may cause
    your user interface to freeze while the function blocks as
    it performs the lookup.)
*/
