source: trunk/doc/src/network-programming/qtnetwork.qdoc@ 730

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([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.1, 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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