|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 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 QNetworkAccessManager and its associated classes use |
|
113 QTcpSocket internally to implement the FTP and HTTP protocols. The |
|
114 classes work asynchronously and can schedule (i.e., queue) |
|
115 requests. |
|
116 |
|
117 The network module contains four helper classes: QHostAddress, |
|
118 QHostInfo, QUrl, and QUrlInfo. QHostAddress stores an IPv4 or IPv6 |
|
119 address, QHostInfo resolves host names into addresses, QUrl stores a |
|
120 URL, and QUrlInfo stores information about a resource pointed to |
|
121 by a URL, such as the file size and modification date. (Because |
|
122 QUrl is used by QTextBrowser, it is part of the QtCore library and |
|
123 not of QtNetwork.) |
|
124 |
|
125 See the \l QtNetwork module overview for more information. |
|
126 |
|
127 \section1 Example Code |
|
128 |
|
129 All the code snippets presented here are quoted from |
|
130 self-contained, compilable examples located in Qt's \c |
|
131 examples/network directory. |
|
132 |
|
133 \section2 TCP Client |
|
134 |
|
135 The first example illustrates how to write a TCP client using |
|
136 QTcpSocket. The client talks to a fortune server that provides |
|
137 fortune to the user. Here's how to set up the socket: |
|
138 |
|
139 \snippet examples/network/fortuneclient/client.cpp 1 |
|
140 \codeline |
|
141 \snippet examples/network/fortuneclient/client.cpp 2 |
|
142 \snippet examples/network/fortuneclient/client.cpp 4 |
|
143 |
|
144 When the user requests a new fortune, the client establishes a |
|
145 connection to the server: |
|
146 |
|
147 \snippet examples/network/fortuneclient/client.cpp 7 |
|
148 |
|
149 When the server answers, the following code is executed to read |
|
150 the data from the socket: |
|
151 |
|
152 \snippet examples/network/fortuneclient/client.cpp 9 |
|
153 |
|
154 The server's answer starts with a \e size field (which we store |
|
155 in \c blockSize), followed by \e size bytes of data. If the |
|
156 client hasn't received all the data yet, it waits for the server |
|
157 to send more. |
|
158 |
|
159 An alternative approach is to use a blocking socket. The code can |
|
160 then be concentrated in one function: |
|
161 |
|
162 \snippet examples/network/blockingfortuneclient/fortunethread.cpp 7 |
|
163 |
|
164 \section2 TCP Server |
|
165 |
|
166 The following code snippets illustrate how to write a TCP server |
|
167 using QTcpServer and QTcpSocket. Here's how to set up a TCP |
|
168 server: |
|
169 |
|
170 \snippet examples/network/fortuneserver/server.cpp 0 |
|
171 \codeline |
|
172 \snippet examples/network/fortuneserver/server.cpp 3 |
|
173 |
|
174 When a client tries to connect to the server, the following code |
|
175 in the sendFortune() slot is executed: |
|
176 |
|
177 \snippet examples/network/fortuneserver/server.cpp 5 |
|
178 |
|
179 \section2 UDP Senders and Receivers |
|
180 |
|
181 Here's how to broadcast a UDP datagram: |
|
182 |
|
183 \snippet examples/network/broadcastsender/sender.cpp 0 |
|
184 \snippet examples/network/broadcastsender/sender.cpp 1 |
|
185 |
|
186 Here's how to receive a UDP datagram: |
|
187 |
|
188 \snippet examples/network/broadcastreceiver/receiver.cpp 0 |
|
189 \codeline |
|
190 \snippet examples/network/broadcastreceiver/receiver.cpp 1 |
|
191 |
|
192 Then in the processPendingDatagrams() slot: |
|
193 |
|
194 \snippet examples/network/broadcastreceiver/receiver.cpp 2 |
|
195 |
|
196 \section1 Comparison with Qt 3 |
|
197 |
|
198 The main difference between Qt 3 and Qt 4 is that the very high |
|
199 level QNetworkProtocol and QUrlOperator abstraction has been |
|
200 eliminated. These classes attempted the impossible (unify FTP and |
|
201 HTTP under one roof), and unsurprisingly failed at that. Qt 4 |
|
202 still provides QFtp, and it also provides the QNetworkAccessManager. |
|
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 */ |