doc/src/porting/qt4-network.qdoc

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