source: trunk/doc/src/porting/qt4-network.qdoc@ 769

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

/*!
    \page qt4-network.html
    \title The Network Module in Qt 4

    \contentspage {What's New in Qt 4}{Home}
    \previouspage The Qt 4 Database GUI Layer
    \nextpage The Qt 4 Style API

    The network module in Qt 4 provides some new features, such as
    support for internationalized domain names, better IPv6 support,
    and better performance. And since Qt 4 allows us to break binary
    compatibility with previous releases, we took this opportunity to
    improve the class names and API to make them more intuitive to
    use.

    \tableofcontents

    \section1 General Overview

    Compared to Qt 3, the network module in Qt 4 brings the following
    benefits:

    \list
    \o  The Qt 4 network classes have more intuitive names and APIs.
        For example, QServerSocket has been renamed QTcpServer.
    \o  The entire network module is \l{reentrant}, making it
        possible to use them simultaneously from multiple threads.
    \o  It is now possible to send and receive UDP datagrams and to
        use synchronous (i.e., blocking) sockets without having to
        use a low-level API (QSocketDevice in Qt 3).
    \o  QHostAddress and QHostInfo support internationalized domain names
        (RFC 3492).
    \o  QUrl is more lightweight and fully supports the latest URI
        specification draft.
    \o  UDP broadcasting is now supported.
    \endlist

    The Qt 4 network module provides fundamental classes for writing
    TCP and UDP applications, as well as higher-level classes that
    implement the client side of the HTTP and FTP protocols.

    Here's an overview of the TCP and UDP classes:

    \list
    \o  QTcpSocket encapsulates a TCP socket. It inherits from
        QIODevice, so you can use QTextStream and QDataStream to read
        or write data. It is useful for writing both clients and
        servers.
    \o  QTcpServer allows you to listen on a certain port on a
        server. It emits a
        \l{QTcpServer::newConnection()}{newConnection()} signal every
        time a client tries to connect to the server. Once the
        connection is established, you can talk to the client using
        QTcpSocket.
    \o  QUdpSocket is an API for sending and receiving UDP datagrams.
    \endlist

    QTcpSocket and QUdpSocket inherit most of their functionality
    from QAbstractSocket. You can also use QAbstractSocket directly
    as a wrapper around a native socket descriptor.

    By default, the socket classes work asynchronously (i.e., they
    are non-blocking), emitting signals to notify when data has
    arrived or when the peer has closed the connection. In
    multithreaded applications and in non-GUI applications, you also
    have the opportunity of using blocking (synchronous) functions on
    the socket, which often results in a more straightforward style
    of programming, with the networking logic concentrated in one or
    two functions instead of spread across multiple slots.

    QFtp and QNetworkAccessManager and its associated classes use
    QTcpSocket internally to implement the FTP and HTTP protocols. The
    classes work asynchronously and can schedule (i.e., queue)
    requests.

    The network module contains four helper classes: QHostAddress,
    QHostInfo, QUrl, and QUrlInfo. QHostAddress stores an IPv4 or IPv6
    address, QHostInfo resolves host names into addresses, QUrl stores a
    URL, and QUrlInfo stores information about a resource pointed to
    by a URL, such as the file size and modification date. (Because
    QUrl is used by QTextBrowser, it is part of the QtCore library and
    not of QtNetwork.)

    See the \l QtNetwork module overview for more information.

    \section1 Example Code

    All the code snippets presented here are quoted from
    self-contained, compilable examples located in Qt's \c
    examples/network directory.

    \section2 TCP Client

    The first example illustrates how to write a TCP client using
    QTcpSocket. The client talks to a fortune server that provides
    fortune to the user. Here's how to set up the socket:

    \snippet examples/network/fortuneclient/client.cpp 1
    \codeline
    \snippet examples/network/fortuneclient/client.cpp 2
    \snippet examples/network/fortuneclient/client.cpp 4

    When the user requests a new fortune, the client establishes a
    connection to the server:

    \snippet examples/network/fortuneclient/client.cpp 7

    When the server answers, the following code is executed to read
    the data from the socket:

    \snippet examples/network/fortuneclient/client.cpp 9