diff options
Diffstat (limited to 'doc/src/qtnetwork.qdoc')
| -rw-r--r-- | doc/src/qtnetwork.qdoc | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/doc/src/qtnetwork.qdoc b/doc/src/qtnetwork.qdoc new file mode 100644 index 0000000000..2be7457859 --- /dev/null +++ b/doc/src/qtnetwork.qdoc @@ -0,0 +1,358 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtNetwork + \title QtNetwork Module + \contentspage Qt's Modules + \previouspage QtGui + \nextpage QtOpenGL + \ingroup modules + + \brief The QtNetwork module offers classes that allow you to + write TCP/IP clients and servers. + + The network module provides classes to make network programming + easier and portable. It offers classes such as QHttp and 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. + + The QtNetwork module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. + + Topics: + + \tableofcontents + + \section1 Configuring the Build Process + + Applications that use Qt's networking classes need to + be configured to be built against the QtNetwork module. + The following declaration in a \c qmake project file ensures that + an application is compiled and linked appropriately: + + \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 0 + + This line is necessary because only the QtCore and QtGui modules + are used in the default build process. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 1 + + \section1 High Level Network Operations + + 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. + + 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 HTTP and FTP Clients with QHttp and QFtp + + HTTP (Hypertext Transfer Protocol) is an application-level + network protocol used mainly for downloading HTML and XML files, + but it is also used as a high-level transport protocol for many + other types of data, from images and movies to purchase orders + and banking transactions. In contrast, FTP (File Transfer + Protocol) is a protocol used almost exclusively for browsing + remote directories and for transferring files. + + \image httpstack.png HTTP Client and Server + + HTTP is a simpler protocol than FTP in many ways. It uses only + one network connection, while FTP uses two (one for sending + commands, and one for transferring data). HTTP is a stateless + protocol; requests and responses are always self-contained. The + FTP protocol has a state and requires the client to send several + commands before a file transfer takes place. + + In practice, HTTP clients often use separate connections for + separate requests, whereas FTP clients establish one connection + and keep it open throughout the session. + + The QHttp and QFtp classes provide client-side support for HTTP + and FTP. Since the two protocols are used to solve the same + problems, the QHttp and QFtp classes have many features in + common: + + \list + + \o \e{Non-blocking behavior.} QHttp and QFtp are asynchronous. + You can schedule a series of commands (also called "requests" for + HTTP). The commands 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. QHttp has a + \l{QHttp::requestStarted()}{requestStarted()} and a + \l{QHttp::requestFinished()}{requestFinished()} signal that work + the same way. + + \o \e{Data transfer progress indicators.} QHttp and QFtp emit + signals whenever data is transferred + (QFtp::dataTransferProgress(), QHttp::dataReadProgress(), and + QHttp::dataSendProgress()). You could connect these signals to + QProgressBar::setProgress() or QProgressDialog::setProgress(), + for example. + + \o \e{QIODevice support.} Both classes support convenient + uploading from and downloading to \l{QIODevice}s, in addition to a + QByteArray-based API. + + \endlist + + There are two main ways of using QHttp and 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/http}{HTTP} and \l{network/ftp}{FTP} examples + illustrate how to write an HTTP and an FTP client. + + Writing your own HTTP or FTP 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 QHttp 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. + + \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. +*/ |