source: trunk/doc/src/qtnetwork.qdoc@ 357

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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 [email protected].
** $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 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 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

    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,