Update copyright headers
[qt:qt.git] / 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 */