diff -r dee5afe5301f -r 3f74d0d4af4c doc/src/examples/fortuneclient.qdoc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/src/examples/fortuneclient.qdoc Thu Apr 08 14:19:33 2010 +0300 @@ -0,0 +1,174 @@ +/**************************************************************************** +** +** Copyright (C) 2010 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: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$ +** +****************************************************************************/ + +/*! + \example network/fortuneclient + \title Fortune Client Example + + The Fortune Client example shows how to create a client for a simple + network service using QTcpSocket. It is intended to be run alongside the + \l{network/fortuneserver}{Fortune Server} example or + the \l{network/threadedfortuneserver}{Threaded Fortune Server} example. + + \image fortuneclient-example.png Screenshot of the Fortune Client example + + This example uses a simple QDataStream-based data transfer protocol to + request a line of text from a fortune server (from the + \l{network/fortuneserver}{Fortune Server} example). The client requests a + fortune by simply connecting to the server. The server then responds with + a 16-bit (quint16) integer containing the length of the fortune text, + followed by a QString. + + QTcpSocket supports two general approaches to network programming: + + \list + + \o \e{The asynchronous (non-blocking) approach.} Operations are scheduled + and performed when control returns to Qt's event loop. When the operation + is finished, QTcpSocket emits a signal. For example, + QTcpSocket::connectToHost() returns immediately, and when the connection + has been established, QTcpSocket emits + \l{QTcpSocket::connected()}{connected()}. + + \o \e{The synchronous (blocking) approach.} In non-GUI and multithreaded + applications, you can call the \c waitFor...() functions (e.g., + QTcpSocket::waitForConnected()) to suspend the calling thread until the + operation has completed, instead of connecting to signals. + + \endlist + + In this example, we will demonstrate the asynchronous approach. The + \l{network/blockingfortuneclient}{Blocking Fortune Client} example + illustrates the synchronous approach. + + Our class contains some data and a few private slots: + + \snippet examples/network/fortuneclient/client.h 0 + + Other than the widgets that make up the GUI, the data members include a + QTcpSocket pointer, a copy of the fortune text currently displayed, and + the size of the packet we are currently reading (more on this later). + + The socket is initialized in the Client constructor. We'll pass the main + widget as parent, so that we won't have to worry about deleting the + socket: + + \snippet examples/network/fortuneclient/client.cpp 0 + \dots + \snippet examples/network/fortuneclient/client.cpp 1 + + The only QTcpSocket signals we need in this example are + QTcpSocket::readyRead(), signifying that data has been received, and + QTcpSocket::error(), which we will use to catch any connection errors: + + \dots + \snippet examples/network/fortuneclient/client.cpp 3 + \dots + \snippet examples/network/fortuneclient/client.cpp 5 + + Clicking the \gui{Get Fortune} button will invoke the \c + requestNewFortune() slot: + + \snippet examples/network/fortuneclient/client.cpp 6 + + In this slot, we initialize \c blockSize to 0, preparing to read a new block + of data. Because we allow the user to click \gui{Get Fortune} before the + previous connection finished closing, we start off by aborting the + previous connection by calling QTcpSocket::abort(). (On an unconnected + socket, this function does nothing.) We then proceed to connecting to the + fortune server by calling QTcpSocket::connectToHost(), passing the + hostname and port from the user interface as arguments. + + As a result of calling \l{QTcpSocket::connectToHost()}{connectToHost()}, + one of two things can happen: + + \list + \o \e{The connection is established.} In this case, the server will send us a + fortune. QTcpSocket will emit \l{QTcpSocket::readyRead()}{readyRead()} + every time it receives a block of data. + + \o \e{An error occurs.} We need to inform the user if the connection + failed or was broken. In this case, QTcpSocket will emit + \l{QTcpSocket::error()}{error()}, and \c Client::displayError() will be + called. + \endlist + + Let's go through the \l{QTcpSocket::error()}{error()} case first: + + \snippet examples/network/fortuneclient/client.cpp 13 + + We pop up all errors in a dialog using + QMessageBox::information(). QTcpSocket::RemoteHostClosedError is silently + ignored, because the fortune server protocol ends with the server closing + the connection. + + Now for the \l{QTcpSocket::readyRead()}{readyRead()} alternative. This + signal is connected to \c Client::readFortune(): + + \snippet examples/network/fortuneclient/client.cpp 8 + \codeline + \snippet examples/network/fortuneclient/client.cpp 10 + + The protocol is based on QDataStream, so we start by creating a stream + object, passing the socket to QDataStream's constructor. We then + explicitly set the protocol version of the stream to QDataStream::Qt_4_0 + to ensure that we're using the same version as the fortune server, no + matter which version of Qt the client and server use. + + Now, TCP is based on sending a stream of data, so we cannot expect to get + the entire fortune in one go. Especially on a slow network, the data can + be received in several small fragments. QTcpSocket buffers up all incoming + data and emits \l{QTcpSocket::readyRead()}{readyRead()} for every new + block that arrives, and it is our job to ensure that we have received all + the data we need before we start parsing. The server's response starts + with the size of the packet, so first we need to ensure that we can read + the size, then we will wait until QTcpSocket has received the full packet. + + \snippet examples/network/fortuneclient/client.cpp 11 + \codeline + \snippet examples/network/fortuneclient/client.cpp 12 + + We proceed by using QDataStream's streaming operator to read the fortune + from the socket into a QString. Once read, we can call QLabel::setText() + to display the fortune. + + \sa {Fortune Server Example}, {Blocking Fortune Client Example} +*/