path: root/doc/src/qtnetwork.qdoc

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** 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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \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 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 Full Framework Edition} and the
    \l{Open Source Versions of Qt}.

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