doc/src/network-programming/qtnetwork.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 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:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \group network
  30     \title Network Programming API
  31     \brief Classes for Network Programming
  32
  33     \ingroup groups
  34 */
  35
  36 /*!
  37     \page network-programming.html
  38     \title Network Programming
  39     \ingroup qt-network
  40     \brief An Introduction to Network Programming with Qt
  41
  42     The QtNetwork module offers classes that allow you to write TCP/IP clients
  43     and servers. It offers classes such as QFtp that implement specific
  44     application-level protocols, lower-level classes such as QTcpSocket,
  45     QTcpServer and QUdpSocket that represent low level network concepts,
  46     and high level classes such as QNetworkRequest, QNetworkReply and
  47     QNetworkAccessManager to perform network operations using common protocols.
  48     It also offers classes such as QNetworkConfiguration,
  49     QNetworkConfigurationManager and QNetworkSession that implement bearer
  50     management.
  51
  52     \tableofcontents
  53
  54     \section1 Qt's Classes for Network Programming
  55
  56     The following classes provide support for network programming in Qt.
  57
  58     \annotatedlist network
  59
  60     \section1 High Level Network Operations for HTTP and FTP
  61
  62     The Network Access API is a collection of classes for performing
  63     common network operations. The API provides an abstraction layer
  64     over the specific operations and protocols used (for example,
  65     getting and posting data over HTTP), and only exposes classes,
  66     functions, and signals for general or high level concepts.
  67
  68     Network requests are represented by the QNetworkRequest class,
  69     which also acts as a general container for information associated
  70     with a request, such as any header information and the encryption
  71     used. The URL specified when a request object is constructed
  72     determines the protocol used for a request.
  73     Currently HTTP, FTP and local file URLs are supported for uploading
  74     and downloading.
  75
  76     The coordination of network operations is performed by the
  77     QNetworkAccessManager class. Once a request has been created,
  78     this class is used to dispatch it and emit signals to report on
  79     its progress. The manager also coordinates the use of
  80     \l{QNetworkCookieJar}{cookies} to store data on the client,
  81     authentication requests, and the use of proxies.
  82
  83     Replies to network requests are represented by the QNetworkReply
  84     class; these are created by QNetworkAccessManager when a request
  85     is dispatched. The signals provided by QNetworkReply can be used
  86     to monitor each reply individually, or developers may choose to
  87     use the manager's signals for this purpose instead and discard
  88     references to replies. Since QNetworkReply is a subclass of
  89     QIODevice, replies can be handled synchronously or asynchronously;
  90     i.e., as blocking or non-blocking operations.
  91
  92     Each application or library can create one or more instances of
  93     QNetworkAccessManager to handle network communication.
  94
  95     \section1 Writing FTP Clients with QFtp
  96
  97     FTP (File Transfer Protocol) is a protocol used almost exclusively
  98     for browsing remote directories and for transferring files.
  99
 100     \image httpstack.png FTP Client and Server
 101
 102     FTP uses two network connections, one for sending
 103     commands and one for transferring data. The
 104     FTP protocol has a state and requires the client to send several
 105     commands before a file transfer takes place.
 106     FTP clients establish a connection
 107     and keeps it open throughout the session. In each session, multiple
 108     transfers can occur.
 109
 110     The QFtp class provides client-side support for FTP.
 111     It has the following characteristics:
 112     \list
 113
 114     \o \e{Non-blocking behavior.} QFtp is asynchronous.
 115     You can schedule a series of commands which are executed later,
 116     when control returns to Qt's event loop.
 117
 118     \o \e{Command IDs.} Each command has a unique ID number that you
 119     can use to follow the execution of the command. For example, QFtp
 120     emits the \l{QFtp::commandStarted()}{commandStarted()} and
 121     \l{QFtp::commandFinished()}{commandFinished()} signal with the
 122     command ID for each command that is executed.
 123
 124     \o \e{Data transfer progress indicators.} QFtp emits signals
 125     whenever data is transferred (QFtp::dataTransferProgress(),
 126     QNetworkReply::downloadProgress(), and
 127     QNetworkReply::uploadProgress()).  You could connect these signals
 128     to QProgressBar::setProgress() or QProgressDialog::setProgress(),
 129     for example.
 130
 131     \o \e{QIODevice support.} The class supports convenient
 132     uploading from and downloading to \l{QIODevice}s, in addition to a
 133     QByteArray-based API.
 134
 135     \endlist
 136
 137     There are two main ways of using QFtp. The most common
 138     approach is to keep track of the command IDs and follow the
 139     execution of every command by connecting to the appropriate
 140     signals. The other approach is to schedule all commands at once
 141     and only connect to the done() signal, which is emitted when all
 142     scheduled commands have been executed. The first approach
 143     requires more work, but it gives you more control over the
 144     execution of individual commands and allows you to initiate new
 145     commands based on the result of a previous command. It also
 146     enables you to provide detailed feedback to the user.
 147
 148     The \l{network/qftp}{FTP} example
 149     illustrates how to write an FTP client.
 150     Writing your own FTP (or HTTP) server is possible using the
 151     lower-level classes QTcpSocket and QTcpServer.
 152
 153     \section1 Using TCP with QTcpSocket and QTcpServer
 154
 155     TCP (Transmission Control Protocol) is a low-level network
 156     protocol used by most Internet protocols, including HTTP and FTP,
 157     for data transfer. It is a reliable, stream-oriented,
 158     connection-oriented transport protocol. It is particularly well
 159     suited to the continuous transmission of data.
 160
 161     \image tcpstream.png A TCP Stream
 162
 163     The QTcpSocket class provides an interface for TCP. You can use
 164     QTcpSocket to implement standard network protocols such as POP3,
 165     SMTP, and NNTP, as well as custom protocols.
 166
 167     A TCP connection must be established to a remote host and port
 168     before any data transfer can begin. Once the connection has been
 169     established, the IP address and port of the peer are available
 170     through QTcpSocket::peerAddress() and QTcpSocket::peerPort(). At
 171     any time, the peer can close the connection, and data transfer
 172     will then stop immediately.
 173
 174     QTcpSocket works asynchronously and emits signals to report status
 175     changes and errors, just like QNetworkAccessManager and QFtp. It
 176     relies on the event loop to detect incoming data and to
 177     automatically flush outgoing data. You can write data to the
 178     socket using QTcpSocket::write(), and read data using
 179     QTcpSocket::read(). QTcpSocket represents two independent streams
 180     of data: one for reading and one for writing.
 181
 182     Since QTcpSocket inherits QIODevice, you can use it with
 183     QTextStream and QDataStream. When reading from a QTcpSocket, you
 184     must make sure that enough data is available by calling
 185     QTcpSocket::bytesAvailable() beforehand.
 186
 187     If you need to handle incoming TCP connections (e.g., in a server
 188     application), use the QTcpServer class. Call QTcpServer::listen()
 189     to set up the server, and connect to the
 190     QTcpServer::newConnection() signal, which is emitted once for
 191     every client that connects. In your slot, call
 192     QTcpServer::nextPendingConnection() to accept the connection and
 193     use the returned QTcpSocket to communicate with the client.
 194
 195     Although most of its functions work asynchronously, it's possible
 196     to use QTcpSocket synchronously (i.e., blocking). To get blocking
 197     behavior, call QTcpSocket's waitFor...() functions; these suspend
 198     the calling thread until a signal has been emitted. For example,
 199     after calling the non-blocking QTcpSocket::connectToHost()
 200     function, call QTcpSocket::waitForConnected() to block the thread
 201     until the \l{QTcpSocket::connected()}{connected()} signal has
 202     been emitted.
 203
 204     Synchronous sockets often lead to code with a simpler flow of
 205     control. The main disadvantage of the waitFor...() approach is
 206     that events won't be processed while a waitFor...() function is
 207     blocking. If used in the GUI thread, this might freeze the
 208     application's user interface. For this reason, we recommend that
 209     you use synchronous sockets only in non-GUI threads. When used
 210     synchronously, QTcpSocket doesn't require an event loop.
 211
 212     The \l{network/fortuneclient}{Fortune Client} and
 213     \l{network/fortuneserver}{Fortune Server} examples show how to use
 214     QTcpSocket and QTcpServer to write TCP client-server
 215     applications. See also \l{network/blockingfortuneclient}{Blocking
 216     Fortune Client} for an example on how to use a synchronous
 217     QTcpSocket in a separate thread (without using an event loop),
 218     and \l{network/threadedfortuneserver}{Threaded Fortune Server}
 219     for an example of a multithreaded TCP server with one thread per
 220     active client.
 221
 222     \section1 Using UDP with QUdpSocket
 223
 224     UDP (User Datagram Protocol) is a lightweight, unreliable,
 225     datagram-oriented, connectionless protocol. It can be used when
 226     reliability isn't important. For example, a server that reports
 227     the time of day could choose UDP. If a datagram with the time of
 228     day is lost, the client can simply make another request.
 229
 230     \image udppackets.png UDP Packets
 231
 232     The QUdpSocket class allows you to send and receive UDP
 233     datagrams. It inherits QAbstractSocket, and it therefore shares
 234     most of QTcpSocket's interface. The main difference is that
 235     QUdpSocket transfers data as datagrams instead of as a continuous
 236     stream of data. In short, a datagram is a data packet of limited
 237     size (normally smaller than 512 bytes), containing the IP address
 238     and port of the datagram's sender and receiver in addition to the
 239     data being transferred.
 240
 241     QUdpSocket supports IPv4 broadcasting. Broadcasting is often used
 242     to implement network discovery protocols, such as finding which
 243     host on the network has the most free hard disk space. One host
 244     broadcasts a datagram to the network that all other hosts
 245     receive. Each host that receives a request then sends a reply
 246     back to the sender with its current amount of free disk space.
 247     The originator waits until it has received replies from all
 248     hosts, and can then choose the server with most free space to
 249     store data. To broadcast a datagram, simply send it to the
 250     special address QHostAddress::Broadcast (255.255.255.255), or
 251     to your local network's broadcast address.
 252
 253     QUdpSocket::bind() prepares the socket for accepting incoming
 254     datagrams, much like QTcpServer::listen() for TCP servers.
 255     Whenever one or more datagrams arrive, QUdpSocket emits the
 256     \l{QUdpSocket::readyRead()}{readyRead()} signal. Call
 257     QUdpSocket::readDatagram() to read the datagram.
 258
 259     The \l{network/broadcastsender}{Broadcast Sender} and
 260     \l{network/broadcastreceiver}{Broadcast Receiver} examples show how to
 261     write a UDP sender and a UDP receiver using Qt.
 262
 263     QUdpSocket also supports multicasting. The
 264     \l{network/multicastsender}{Multicast Sender} and
 265     \l{network/multicastreceiver}{Multicast Receiver} examples show how to use
 266     write UDP multicast clients.
 267
 268     \section1 Resolving Host Names using QHostInfo
 269
 270     Before establishing a network connection, QTcpSocket and
 271     QUdpSocket perform a name lookup, translating the host name
 272     you're connecting to into an IP address. This operation is
 273     usually performed using the DNS (Domain Name Service) protocol.
 274
 275     QHostInfo provides a static function that lets you perform such a
 276     lookup yourself. By calling QHostInfo::lookupHost() with a host
 277     name, a QObject pointer, and a slot signature, QHostInfo will
 278     perform the name lookup and invoke the given slot when the
 279     results are ready. The actual lookup is done in a separate
 280     thread, making use of the operating system's own methods for
 281     performing name lookups.
 282
 283     QHostInfo also provides a static function called
 284     QHostInfo::fromName() that takes the host name as argument and
 285     returns the results. In this case, the name lookup is performed
 286     in the same thread as the caller. This overload is useful for
 287     non-GUI applications or for doing name lookups in a separate,
 288     non-GUI thread. (Calling this function in a GUI thread may cause
 289     your user interface to freeze while the function blocks as
 290     it performs the lookup.)
 291
 292     \section1 Support for Network Proxies
 293
 294     Network communication with Qt can be performed through proxies,
 295     which direct or filter network traffic between local and remote
 296     connections.
 297
 298     Individual proxies are represented by the QNetworkProxy class,
 299     which is used to describe and configure the connection to a proxy.
 300     Proxy types which operate on different levels of network communication
 301     are supported, with SOCKS 5 support allowing proxying of network
 302     traffic at a low level, and HTTP and FTP proxying working at the
 303     protocol level. See QNetworkProxy::ProxyType for more information.
 304
 305     Proxying can be enabled on a per-socket basis or for all network
 306     communication in an application. A newly opened socket can be
 307     made to use a proxy by calling its QAbstractSocket::setProxy()
 308     function before it is connected. Application-wide proxying can
 309     be enabled for all subsequent socket connections through the use
 310     of the QNetworkProxy::setApplicationProxy() function.
 311
 312     Proxy factories are used to create policies for proxy use.
 313     QNetworkProxyFactory supplies proxies based on queries for specific
 314     proxy types. The queries themselves are encoded in QNetworkProxyQuery
 315     objects which enable proxies to be selected based on key criteria,
 316     such as the purpose of the proxy (TCP, UDP, TCP server, URL request),
 317     local port, remote host and port, and the protocol in use (HTTP, FTP,
 318     etc.).
 319
 320     QNetworkProxyFactory::proxyForQuery() is used to query the factory
 321     directly. An application-wide policy for proxying can be implemented
 322     by passing a factory to QNetworkProxyFactory::setApplicationProxyFactory()
 323     and a custom proxying policy can be created by subclassing
 324     QNetworkProxyFactory; see the class documentation for details.
 325
 326     \section1 Bearer Management Support
 327
 328     Bearer Management controls the connectivity state of the device such that
 329     the application can start or stop network interfaces and roam
 330     transparently between access points.
 331
 332     The QNetworkConfigurationManager class manages the list of network
 333     configurations known to the device. A network configuration describes the
 334     set of parameters used to start a network interface and is represented by
 335     the QNetworkConfiguration class.
 336
 337     A network interface is started by openning a QNetworkSession based on a
 338     given network configuration. In most situations creating a network session
 339     based on the platform specified default network configuration is
 340     appropriate. The default network configuration is returned by the
 341     QNetworkConfigurationManager::defaultConfiguration() function.
 342
 343     On some platforms it is a platform requirement that the application open a
 344     network session before any network operations can be performed. This can be
 345     tested by the presents of the
 346     QNetworkConfigurationManager::NetworkSessionRequired flag in the value
 347     returned by the QNetworkConfigurationManager::capabilities() function.
 348
 349     \sa {Bearer Management}
 350 */