src/network/doc/src/network-programming.qdoc

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