diff options
Diffstat (limited to 'doc/src/network-programming/qtnetwork.qdoc')
| -rw-r--r-- | doc/src/network-programming/qtnetwork.qdoc | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/doc/src/network-programming/qtnetwork.qdoc b/doc/src/network-programming/qtnetwork.qdoc new file mode 100644 index 0000000000..61ff2c5fbe --- /dev/null +++ b/doc/src/network-programming/qtnetwork.qdoc @@ -0,0 +1,350 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group network + \title Network Programming API + \brief Classes for Network Programming + + \ingroup groups +*/ + +/*! + \page network-programming.html + \title Network Programming + \ingroup qt-network + \brief An Introduction to Network Programming with Qt + + The QtNetwork module offers classes that allow you to write TCP/IP clients + and servers. It offers classes such as QFtp that implement specific + application-level protocols, lower-level classes such as QTcpSocket, + QTcpServer and QUdpSocket that represent low level network concepts, + and high level classes such as QNetworkRequest, QNetworkReply and + QNetworkAccessManager to perform network operations using common protocols. + It also offers classes such as QNetworkConfiguration, + QNetworkConfigurationManager and QNetworkSession that implement bearer + management. + + \tableofcontents + + \section1 Qt's Classes for Network Programming + + The following classes provide support for network programming in Qt. + + \annotatedlist network + + \section1 High Level Network Operations for HTTP and FTP + + The Network Access API is a collection of classes for performing + common network operations. The API provides an abstraction layer + over the specific operations and protocols used (for example, + getting and posting data over HTTP), and only exposes classes, + functions, and signals for general or high level concepts. + + Network requests are represented by the QNetworkRequest class, + which also acts as a general container for information associated + with a request, such as any header information and the encryption + used. The URL specified when a request object is constructed + determines the protocol used for a request. + Currently HTTP, FTP and local file URLs are supported for uploading + and downloading. + + The coordination of network operations is performed by the + QNetworkAccessManager class. Once a request has been created, + this class is used to dispatch it and emit signals to report on + its progress. The manager also coordinates the use of + \l{QNetworkCookieJar}{cookies} to store data on the client, + authentication requests, and the use of proxies. + + Replies to network requests are represented by the QNetworkReply + class; these are created by QNetworkAccessManager when a request + is dispatched. The signals provided by QNetworkReply can be used + to monitor each reply individually, or developers may choose to + use the manager's signals for this purpose instead and discard + references to replies. Since QNetworkReply is a subclass of + QIODevice, replies can be handled synchronously or asynchronously; + i.e., as blocking or non-blocking operations. + + Each application or library can create one or more instances of + QNetworkAccessManager to handle network communication. + + \section1 Writing FTP Clients with QFtp + + FTP (File Transfer Protocol) is a protocol used almost exclusively + for browsing remote directories and for transferring files. + + \image httpstack.png FTP Client and Server + + FTP uses two network connections, one for sending + commands and one for transferring data. The + FTP protocol has a state and requires the client to send several + commands before a file transfer takes place. + FTP clients establish a connection + and keeps it open throughout the session. In each session, multiple + transfers can occur. + + The QFtp class provides client-side support for FTP. + It has the following characteristics: + \list + + \o \e{Non-blocking behavior.} QFtp is asynchronous. + You can schedule a series of commands which are executed later, + when control returns to Qt's event loop. + + \o \e{Command IDs.} Each command has a unique ID number that you + can use to follow the execution of the command. For example, QFtp + emits the \l{QFtp::commandStarted()}{commandStarted()} and + \l{QFtp::commandFinished()}{commandFinished()} signal with the + command ID for each command that is executed. + + \o \e{Data transfer progress indicators.} QFtp emits signals + whenever data is transferred (QFtp::dataTransferProgress(), + QNetworkReply::downloadProgress(), and + QNetworkReply::uploadProgress()). You could connect these signals + to QProgressBar::setProgress() or QProgressDialog::setProgress(), + for example. + + \o \e{QIODevice support.} The class supports convenient + uploading from and downloading to \l{QIODevice}s, in addition to a + QByteArray-based API. + + \endlist + + There are two main ways of using QFtp. The most common + approach is to keep track of the command IDs and follow the + execution of every command by connecting to the appropriate + signals. The other approach is to schedule all commands at once + and only connect to the done() signal, which is emitted when all + scheduled commands have been executed. The first approach + requires more work, but it gives you more control over the + execution of individual commands and allows you to initiate new + commands based on the result of a previous command. It also + enables you to provide detailed feedback to the user. + + The \l{network/qftp}{FTP} example + illustrates how to write an FTP client. + Writing your own FTP (or HTTP) server is possible using the + lower-level classes QTcpSocket and QTcpServer. + + \section1 Using TCP with QTcpSocket and QTcpServer + + TCP (Transmission Control Protocol) is a low-level network + protocol used by most Internet protocols, including HTTP and FTP, + for data transfer. It is a reliable, stream-oriented, + connection-oriented transport protocol. It is particularly well + suited to the continuous transmission of data. + + \image tcpstream.png A TCP Stream + + The QTcpSocket class provides an interface for TCP. You can use + QTcpSocket to implement standard network protocols such as POP3, + SMTP, and NNTP, as well as custom protocols. + + A TCP connection must be established to a remote host and port + before any data transfer can begin. Once the connection has been + established, the IP address and port of the peer are available + through QTcpSocket::peerAddress() and QTcpSocket::peerPort(). At + any time, the peer can close the connection, and data transfer + will then stop immediately. + + QTcpSocket works asynchronously and emits signals to report status + changes and errors, just like QNetworkAccessManager and QFtp. It + relies on the event loop to detect incoming data and to + automatically flush outgoing data. You can write data to the + socket using QTcpSocket::write(), and read data using + QTcpSocket::read(). QTcpSocket represents two independent streams + of data: one for reading and one for writing. + + Since QTcpSocket inherits QIODevice, you can use it with + QTextStream and QDataStream. When reading from a QTcpSocket, you + must make sure that enough data is available by calling + QTcpSocket::bytesAvailable() beforehand. + + If you need to handle incoming TCP connections (e.g., in a server + application), use the QTcpServer class. Call QTcpServer::listen() + to set up the server, and connect to the + QTcpServer::newConnection() signal, which is emitted once for + every client that connects. In your slot, call + QTcpServer::nextPendingConnection() to accept the connection and + use the returned QTcpSocket to communicate with the client. + + Although most of its functions work asynchronously, it's possible + to use QTcpSocket synchronously (i.e., blocking). To get blocking + behavior, call QTcpSocket's waitFor...() functions; these suspend + the calling thread until a signal has been emitted. For example, + after calling the non-blocking QTcpSocket::connectToHost() + function, call QTcpSocket::waitForConnected() to block the thread + until the \l{QTcpSocket::connected()}{connected()} signal has + been emitted. + + Synchronous sockets often lead to code with a simpler flow of + control. The main disadvantage of the waitFor...() approach is + that events won't be processed while a waitFor...() function is + blocking. If used in the GUI thread, this might freeze the + application's user interface. For this reason, we recommend that + you use synchronous sockets only in non-GUI threads. When used + synchronously, QTcpSocket doesn't require an event loop. + + The \l{network/fortuneclient}{Fortune Client} and + \l{network/fortuneserver}{Fortune Server} examples show how to use + QTcpSocket and QTcpServer to write TCP client-server + applications. See also \l{network/blockingfortuneclient}{Blocking + Fortune Client} for an example on how to use a synchronous + QTcpSocket in a separate thread (without using an event loop), + and \l{network/threadedfortuneserver}{Threaded Fortune Server} + for an example of a multithreaded TCP server with one thread per + active client. + + \section1 Using UDP with QUdpSocket + + UDP (User Datagram Protocol) is a lightweight, unreliable, + datagram-oriented, connectionless protocol. It can be used when + reliability isn't important. For example, a server that reports + the time of day could choose UDP. If a datagram with the time of + day is lost, the client can simply make another request. + + \image udppackets.png UDP Packets + + The QUdpSocket class allows you to send and receive UDP + datagrams. It inherits QAbstractSocket, and it therefore shares + most of QTcpSocket's interface. The main difference is that + QUdpSocket transfers data as datagrams instead of as a continuous + stream of data. In short, a datagram is a data packet of limited + size (normally smaller than 512 bytes), containing the IP address + and port of the datagram's sender and receiver in addition to the + data being transferred. + + QUdpSocket supports IPv4 broadcasting. Broadcasting is often used + to implement network discovery protocols, such as finding which + host on the network has the most free hard disk space. One host + broadcasts a datagram to the network that all other hosts + receive. Each host that receives a request then sends a reply + back to the sender with its current amount of free disk space. + The originator waits until it has received replies from all + hosts, and can then choose the server with most free space to + store data. To broadcast a datagram, simply send it to the + special address QHostAddress::Broadcast (255.255.255.255), or + to your local network's broadcast address. + + QUdpSocket::bind() prepares the socket for accepting incoming + datagrams, much like QTcpServer::listen() for TCP servers. + Whenever one or more datagrams arrive, QUdpSocket emits the + \l{QUdpSocket::readyRead()}{readyRead()} signal. Call + QUdpSocket::readDatagram() to read the datagram. + + The \l{network/broadcastsender}{Broadcast Sender} and + \l{network/broadcastreceiver}{Broadcast Receiver} examples show how to + write a UDP sender and a UDP receiver using Qt. + + QUdpSocket also supports multicasting. The + \l{network/multicastsender}{Multicast Sender} and + \l{network/multicastreceiver}{Multicast Receiver} examples show how to use + write UDP multicast clients. + + \section1 Resolving Host Names using QHostInfo + + Before establishing a network connection, QTcpSocket and + QUdpSocket perform a name lookup, translating the host name + you're connecting to into an IP address. This operation is + usually performed using the DNS (Domain Name Service) protocol. + + QHostInfo provides a static function that lets you perform such a + lookup yourself. By calling QHostInfo::lookupHost() with a host + name, a QObject pointer, and a slot signature, QHostInfo will + perform the name lookup and invoke the given slot when the + results are ready. The actual lookup is done in a separate + thread, making use of the operating system's own methods for + performing name lookups. + + QHostInfo also provides a static function called + QHostInfo::fromName() that takes the host name as argument and + returns the results. In this case, the name lookup is performed + in the same thread as the caller. This overload is useful for + non-GUI applications or for doing name lookups in a separate, + non-GUI thread. (Calling this function in a GUI thread may cause + your user interface to freeze while the function blocks as + it performs the lookup.) + + \section1 Support for Network Proxies + + Network communication with Qt can be performed through proxies, + which direct or filter network traffic between local and remote + connections. + + Individual proxies are represented by the QNetworkProxy class, + which is used to describe and configure the connection to a proxy. + Proxy types which operate on different levels of network communication + are supported, with SOCKS 5 support allowing proxying of network + traffic at a low level, and HTTP and FTP proxying working at the + protocol level. See QNetworkProxy::ProxyType for more information. + + Proxying can be enabled on a per-socket basis or for all network + communication in an application. A newly opened socket can be + made to use a proxy by calling its QAbstractSocket::setProxy() + function before it is connected. Application-wide proxying can + be enabled for all subsequent socket connections through the use + of the QNetworkProxy::setApplicationProxy() function. + + Proxy factories are used to create policies for proxy use. + QNetworkProxyFactory supplies proxies based on queries for specific + proxy types. The queries themselves are encoded in QNetworkProxyQuery + objects which enable proxies to be selected based on key criteria, + such as the purpose of the proxy (TCP, UDP, TCP server, URL request), + local port, remote host and port, and the protocol in use (HTTP, FTP, + etc.). + + QNetworkProxyFactory::proxyForQuery() is used to query the factory + directly. An application-wide policy for proxying can be implemented + by passing a factory to QNetworkProxyFactory::setApplicationProxyFactory() + and a custom proxying policy can be created by subclassing + QNetworkProxyFactory; see the class documentation for details. + + \section1 Bearer Management Support + + Bearer Management controls the connectivity state of the device such that + the application can start or stop network interfaces and roam + transparently between access points. + + The QNetworkConfigurationManager class manages the list of network + configurations known to the device. A network configuration describes the + set of parameters used to start a network interface and is represented by + the QNetworkConfiguration class. + + A network interface is started by openning a QNetworkSession based on a + given network configuration. In most situations creating a network session + based on the platform specified default network configuration is + appropriate. The default network configuration is returned by the + QNetworkConfigurationManager::defaultConfiguration() function. + + On some platforms it is a platform requirement that the application open a + network session before any network operations can be performed. This can be + tested by the presents of the + QNetworkConfigurationManager::NetworkSessionRequired flag in the value + returned by the QNetworkConfigurationManager::capabilities() function. + + \sa {Bearer Management} +*/ |