doc/src/qt4-network.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \page qt4-network.html
  44     \title The Network Module in Qt 4
  45
  46     \contentspage {What's New in Qt 4}{Home}
  47     \previouspage The Qt 4 Database GUI Layer
  48     \nextpage The Qt 4 Style API
  49
  50     The network module in Qt 4 provides some new features, such as
  51     support for internationalized domain names, better IPv6 support,
  52     and better performance. And since Qt 4 allows us to break binary
  53     compatibility with previous releases, we took this opportunity to
  54     improve the class names and API to make them more intuitive to
  55     use.
  56
  57     \tableofcontents
  58
  59     \section1 General Overview
  60
  61     Compared to Qt 3, the network module in Qt 4 brings the following
  62     benefits:
  63
  64     \list
  65     \o  The Qt 4 network classes have more intuitive names and APIs.
  66         For example, QServerSocket has been renamed QTcpServer.
  67     \o  The entire network module is \l{reentrant}, making it
  68         possible to use them simultaneously from multiple threads.
  69     \o  It is now possible to send and receive UDP datagrams and to
  70         use synchronous (i.e., blocking) sockets without having to
  71         use a low-level API (QSocketDevice in Qt 3).
  72     \o  QHostAddress and QHostInfo support internationalized domain names
  73         (RFC 3492).
  74     \o  QUrl is more lightweight and fully supports the latest URI
  75         specification draft.
  76     \o  UDP broadcasting is now supported.
  77     \endlist
  78
  79     The Qt 4 network module provides fundamental classes for writing
  80     TCP and UDP applications, as well as higher-level classes that
  81     implement the client side of the HTTP and FTP protocols.
  82
  83     Here's an overview of the TCP and UDP classes:
  84
  85     \list
  86     \o  QTcpSocket encapsulates a TCP socket. It inherits from
  87         QIODevice, so you can use QTextStream and QDataStream to read
  88         or write data. It is useful for writing both clients and
  89         servers.
  90     \o  QTcpServer allows you to listen on a certain port on a
  91         server. It emits a
  92         \l{QTcpServer::newConnection()}{newConnection()} signal every
  93         time a client tries to connect to the server. Once the
  94         connection is established, you can talk to the client using
  95         QTcpSocket.
  96     \o  QUdpSocket is an API for sending and receiving UDP datagrams.
  97     \endlist
  98
  99     QTcpSocket and QUdpSocket inherit most of their functionality
 100     from QAbstractSocket. You can also use QAbstractSocket directly
 101     as a wrapper around a native socket descriptor.
 102
 103     By default, the socket classes work asynchronously (i.e., they
 104     are non-blocking), emitting signals to notify when data has
 105     arrived or when the peer has closed the connection. In
 106     multithreaded applications and in non-GUI applications, you also
 107     have the opportunity of using blocking (synchronous) functions on
 108     the socket, which often results in a more straightforward style
 109     of programming, with the networking logic concentrated in one or
 110     two functions instead of spread across multiple slots.
 111
 112     QFtp and QHttp use QTcpSocket internally to implement the FTP and
 113     HTTP protocols. Both classes work asynchronously and can schedule
 114     (i.e., queue) requests.
 115
 116     The network module contains four helper classes: QHostAddress,
 117     QHostInfo, QUrl, and QUrlInfo. QHostAddress stores an IPv4 or IPv6
 118     address, QHostInfo resolves host names into addresses, QUrl stores a
 119     URL, and QUrlInfo stores information about a resource pointed to
 120     by a URL, such as the file size and modification date. (Because
 121     QUrl is used by QTextBrowser, it is part of the QtCore library and
 122     not of QtNetwork.)
 123
 124     See the \l QtNetwork module overview for more information.
 125
 126     \section1 Example Code
 127
 128     All the code snippets presented here are quoted from
 129     self-contained, compilable examples located in Qt's \c
 130     examples/network directory.
 131
 132     \section2 TCP Client
 133
 134     The first example illustrates how to write a TCP client using
 135     QTcpSocket. The client talks to a fortune server that provides
 136     fortune to the user. Here's how to set up the socket:
 137
 138     \snippet examples/network/fortuneclient/client.cpp 1
 139     \codeline
 140     \snippet examples/network/fortuneclient/client.cpp 2
 141     \snippet examples/network/fortuneclient/client.cpp 4
 142
 143     When the user requests a new fortune, the client establishes a
 144     connection to the server:
 145
 146     \snippet examples/network/fortuneclient/client.cpp 7
 147
 148     When the server answers, the following code is executed to read
 149     the data from the socket:
 150
 151     \snippet examples/network/fortuneclient/client.cpp 9
 152
 153     The server's answer starts with a \e size field (which we store
 154     in \c blockSize), followed by \e size bytes of data. If the
 155     client hasn't received all the data yet, it waits for the server
 156     to send more.
 157
 158     An alternative approach is to use a blocking socket. The code can
 159     then be concentrated in one function:
 160
 161     \snippet examples/network/blockingfortuneclient/fortunethread.cpp 7
 162
 163     \section2 TCP Server
 164
 165     The following code snippets illustrate how to write a TCP server
 166     using QTcpServer and QTcpSocket. Here's how to set up a TCP
 167     server:
 168
 169     \snippet examples/network/fortuneserver/server.cpp 0
 170     \codeline
 171     \snippet examples/network/fortuneserver/server.cpp 3
 172
 173     When a client tries to connect to the server, the following code
 174     in the sendFortune() slot is executed:
 175
 176     \snippet examples/network/fortuneserver/server.cpp 5
 177
 178     \section2 UDP Senders and Receivers
 179
 180     Here's how to broadcast a UDP datagram:
 181
 182     \snippet examples/network/broadcastsender/sender.cpp 0
 183     \snippet examples/network/broadcastsender/sender.cpp 1
 184
 185     Here's how to receive a UDP datagram:
 186
 187     \snippet examples/network/broadcastreceiver/receiver.cpp 0
 188     \codeline
 189     \snippet examples/network/broadcastreceiver/receiver.cpp 1
 190
 191     Then in the processPendingDatagrams() slot:
 192
 193     \snippet examples/network/broadcastreceiver/receiver.cpp 2
 194
 195     \section1 Comparison with Qt 3
 196
 197     The main difference between Qt 3 and Qt 4 is that the very high
 198     level QNetworkProtocol and QUrlOperator abstraction has been
 199     eliminated. These classes attempted the impossible (unify FTP and
 200     HTTP under one roof), and unsurprisingly failed at that. Qt 4
 201     still provides QFtp and QHttp classes, but only with the more
 202     mature API that appeared in Qt 3.1.
 203
 204     The QSocket class in Qt 3 has been renamed QTcpSocket. The new
 205     class is reentrant and supports blocking. It's also easier to
 206     handle closing than with Qt 3, where you had to connect to both
 207     the QSocket::connectionClosed() and the
 208     QSocket::delayedCloseFinished() signals.
 209
 210     The QServerSocket class in Qt 3 has been renamed QTcpServer. The
 211     API has changed quite a bit. While in Qt 3 it was necessary to
 212     subclass QServerSocket and reimplement the newConnection() pure
 213     virtual function, QTcpServer now emits a
 214     \l{QTcpServer::newConnection()}{newConnection()} signal that you
 215     can connect to a slot.
 216
 217     The QHostInfo class has been redesigned to use the operating system's
 218     getaddrinfo() function instead of implementing the DNS protocol.
 219     Internally, QHostInfo simply starts a thread and calls getaddrinfo()
 220     in that thread. This wasn't possible in Qt 3 because
 221     getaddrinfo() is a blocking call and Qt 3 could be configured
 222     without multithreading support.
 223
 224     The QSocketDevice class in Qt 3 is no longer part of the public
 225     Qt API. If you used QSocketDevice to send or receive UDP
 226     datagrams, use QUdpSocket instead. If you used QSocketDevice
 227     because it supported blocking sockets, use QTcpSocket or
 228     QUdpSocket instead and use the blocking functions
 229     (\l{QAbstractSocket::waitForConnected()}{waitForConnected()},
 230     \l{QAbstractSocket::waitForConnected()}{waitForReadyRead()},
 231     etc.). If you used QSocketDevice from a non-GUI thread because it
 232     was the only reentrant networking class in Qt 3, use QTcpSocket,
 233     QTcpServer, or QUdpSocket instead.
 234
 235     Internally, Qt 4 has a class called QSocketLayer that provides a
 236     cross-platform low-level socket API. It resembles the old
 237     QSocketDevice class. We might make it public in a later release
 238     if users ask for it.
 239
 240     As an aid to porting to Qt 4, the \l{Qt3Support}
 241     library includes Q3Dns, Q3ServerSocket, Q3Socket, and Q3SocketDevice
 242     classes.
 243 */