/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \group network

    \title Network Programming API

    \brief Classes for Network Programming

    \ingroup groups

*/

/*!

    \page network-programming.html

    \title Network Programming

    \brief An Introduction to Network Programming with Qt

    The QtNetwork module offers classes that allow you to write TCP/IP clients

    and servers. it offers classes such as 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.

    \tableofcontents

    \section1 Qt's Classes for Network Programming

    The following classes provide support for network programming in Qt.

    \annotatedlist network

    \section1 High Level Network Operations for HTTP and FTP

    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.

    Currently HTTP, FTP and local file URLs are supported for uploading

    and downloading.

    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 FTP Clients with QFtp

    FTP (File Transfer Protocol) is a protocol used almost exclusively

    for browsing remote directories and for transferring files.

    \image httpstack.png FTP Client and Server

    FTP uses two network connections, one for sending

    commands and one for transferring data. The

    FTP protocol has a state and requires the client to send several

    commands before a file transfer takes place.

    FTP clients establish a connection

    and keeps it open throughout the session. In each session, multiple

    transfers can occur.

    The QFtp class provides client-side support for FTP. 

    It has the following characteristics:

    \list

    \o \e{Non-blocking behavior.} QFtp is asynchronous.

    You can schedule a series of commands which 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. 

    \o \e{Data transfer progress indicators.} QFtp emits signals

    whenever data is transferred (QFtp::dataTransferProgress(),

    QNetworkReply::downloadProgress(), and

    QNetworkReply::uploadProgress()).  You could connect these signals

    to QProgressBar::setProgress() or QProgressDialog::setProgress(),

    for example.

    \o \e{QIODevice support.} The class supports convenient

    uploading from and downloading to \l{QIODevice}s, in addition to a

    QByteArray-based API.

    \endlist

    There are two main ways of using 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/ftp}{FTP} example

    illustrates how to write an FTP client.

    Writing your own FTP (or HTTP) 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 QNetworkAccessManager 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.)

    \section1 Support for Network Proxies

    Network communication with Qt can be performed through proxies,

    which direct or filter network traffic between local and remote

    connections.

    Individual proxies are represented by the QNetworkProxy class,

    which is used to describe and configure the connection to a proxy.

    Proxy types which operate on different levels of network communication

    are supported, with SOCKS 5 support allowing proxying of network

    traffic at a low level, and HTTP and FTP proxying working at the

    protocol level. See QNetworkProxy::ProxyType for more information.

    Proxying can be enabled on a per-socket basis or for all network

    communication in an application. A newly opened socket can be

    made to use a proxy by calling its QAbstractSocket::setProxy()

    function before it is connected. Application-wide proxying can

    be enabled for all subsequent socket connections through the use

    of the QNetworkProxy::setApplicationProxy() function.

    Proxy factories are used to create policies for proxy use.

    QNetworkProxyFactory supplies proxies based on queries for specific

    proxy types. The queries themselves are encoded in QNetworkProxyQuery

    objects which enable proxies to be selected based on key criteria,

    such as the purpose of the proxy (TCP, UDP, TCP server, URL request),

    local port, remote host and port, and the protocol in use (HTTP, FTP,

    etc.).

    QNetworkProxyFactory::proxyForQuery() is used to query the factory

    directly. An application-wide policy for proxying can be implemented

    by passing a factory to QNetworkProxyFactory::setApplicationProxyFactory()

    and a custom proxying policy can be created by subclassing

    QNetworkProxyFactory; see the class documentation for details.

*/