1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $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
The server's answer starts with a \e size field (which we store
in \c blockSize), followed by \e size bytes of data. If the
client hasn't received all the data yet, it waits for the server
to send more.
An alternative approach is to use a blocking socket. The code can
then be concentrated in one function:
\snippet examples/network/blockingfortuneclient/fortunethread.cpp 7
\section2 TCP Server
The following code snippets illustrate how to write a TCP server
using QTcpServer and QTcpSocket. Here's how to set up a TCP
server:
\snippet examples/network/fortuneserver/server.cpp 0
\codeline
\snippet examples/network/fortuneserver/server.cpp 3
When a client tries to connect to the server, the following code
in the sendFortune() slot is executed:
\snippet examples/network/fortuneserver/server.cpp 5
\section2 UDP Senders and Receivers
Here's how to broadcast a UDP datagram:
\snippet examples/network/broadcastsender/sender.cpp 0
\snippet examples/network/broadcastsender/sender.cpp 1
Here's how to receive a UDP datagram:
\snippet examples/network/broadcastreceiver/receiver.cpp 0
\codeline
\snippet examples/network/broadcastreceiver/receiver.cpp 1
Then in the processPendingDatagrams() slot:
\snippet examples/network/broadcastreceiver/receiver.cpp 2
\section1 Comparison with Qt 3
The main difference between Qt 3 and Qt 4 is that the very high
level QNetworkProtocol and QUrlOperator abstraction has been
eliminated. These classes attempted the impossible (unify FTP and
HTTP under one roof), and unsurprisingly failed at that. Qt 4
still provides QFtp, and it also provides the QNetworkAccessManager.
The QSocket class in Qt 3 has been renamed QTcpSocket. The new
class is reentrant and supports blocking. It's also easier to
handle closing than with Qt 3, where you had to connect to both
the QSocket::connectionClosed() and the
QSocket::delayedCloseFinished() signals.
The QServerSocket class in Qt 3 has been renamed QTcpServer. The
API has changed quite a bit. While in Qt 3 it was necessary to
subclass QServerSocket and reimplement the newConnection() pure
virtual function, QTcpServer now emits a
\l{QTcpServer::newConnection()}{newConnection()} signal that you
can connect to a slot.
The QHostInfo class has been redesigned to use the operating system's
getaddrinfo() function instead of implementing the DNS protocol.
Internally, QHostInfo simply starts a thread and calls getaddrinfo()
in that thread. This wasn't possible in Qt 3 because
getaddrinfo() is a blocking call and Qt 3 could be configured
without multithreading support.
The QSocketDevice class in Qt 3 is no longer part of the public
Qt API. If you used QSocketDevice to send or receive UDP
datagrams, use QUdpSocket instead. If you used QSocketDevice
because it supported blocking sockets, use QTcpSocket or
QUdpSocket instead and use the blocking functions
(\l{QAbstractSocket::waitForConnected()}{waitForConnected()},
\l{QAbstractSocket::waitForConnected()}{waitForReadyRead()},
etc.). If you used QSocketDevice from a non-GUI thread because it
was the only reentrant networking class in Qt 3, use QTcpSocket,
QTcpServer, or QUdpSocket instead.
Internally, Qt 4 has a class called QSocketLayer that provides a
cross-platform low-level socket API. It resembles the old
QSocketDevice class. We might make it public in a later release
if users ask for it.
As an aid to porting to Qt 4, the \l{Qt3Support}
library includes Q3Dns, Q3ServerSocket, Q3Socket, and Q3SocketDevice
classes.
*/
|
