diff options
Diffstat (limited to 'doc/src/qtnetwork.qdoc')
| -rw-r--r-- | doc/src/qtnetwork.qdoc | 358 |
1 files changed, 0 insertions, 358 deletions
diff --git a/doc/src/qtnetwork.qdoc b/doc/src/qtnetwork.qdoc deleted file mode 100644 index 36a1166..0000000 --- a/doc/src/qtnetwork.qdoc +++ /dev/null @@ -1,358 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying -** this package. -** -** 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.1, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@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. -*/ |