From d16c565ca6a55788435c52ad45647eda67854d80 Mon Sep 17 00:00:00 2001 From: Frederik Gladhorn Date: Tue, 18 Sep 2012 20:32:53 +0200 Subject: Move opengl/wid/net example docs to proper folders. Change-Id: I846439a9cf7ad965ed27a00f98dbc4ff97abe73b Reviewed-by: Jerome Pasion Reviewed-by: Martin Smith --- .../doc/images/blockingfortuneclient-example.png | Bin 0 -> 9199 bytes .../doc/images/broadcastreceiver-example.png | Bin 0 -> 7447 bytes .../network/doc/images/broadcastsender-example.png | Bin 0 -> 5688 bytes .../network/doc/images/fortuneclient-example.png | Bin 0 -> 8282 bytes .../network/doc/images/fortuneserver-example.png | Bin 0 -> 7883 bytes .../network/doc/images/googlesuggest-example.png | Bin 0 -> 9006 bytes examples/network/doc/images/http-example.png | Bin 0 -> 7006 bytes examples/network/doc/images/loopback-example.png | Bin 0 -> 6195 bytes .../doc/images/multicastreceiver-example.png | Bin 0 -> 13042 bytes .../network/doc/images/multicastsender-example.png | Bin 0 -> 21092 bytes .../network/doc/images/network-chat-example.png | Bin 0 -> 17453 bytes examples/network/doc/images/securesocketclient.png | Bin 0 -> 12056 bytes .../network/doc/images/securesocketclient2.png | Bin 0 -> 15532 bytes .../doc/images/threadedfortuneserver-example.png | Bin 0 -> 8528 bytes examples/network/doc/images/torrent-example.png | Bin 0 -> 18915 bytes .../network/doc/src/blockingfortuneclient.qdoc | 216 +++++++++++++++++++++ examples/network/doc/src/broadcastreceiver.qdoc | 36 ++++ examples/network/doc/src/broadcastsender.qdoc | 36 ++++ examples/network/doc/src/fortuneclient.qdoc | 160 +++++++++++++++ examples/network/doc/src/fortuneserver.qdoc | 105 ++++++++++ examples/network/doc/src/googlesuggest.qdoc | 180 +++++++++++++++++ examples/network/doc/src/http.qdoc | 36 ++++ examples/network/doc/src/loopback.qdoc | 36 ++++ examples/network/doc/src/multicastreceiver.qdoc | 36 ++++ examples/network/doc/src/multicastsender.qdoc | 36 ++++ examples/network/doc/src/network-chat.qdoc | 37 ++++ examples/network/doc/src/securesocketclient.qdoc | 39 ++++ .../network/doc/src/threadedfortuneserver.qdoc | 107 ++++++++++ examples/network/doc/src/torrent.qdoc | 69 +++++++ 29 files changed, 1129 insertions(+) create mode 100644 examples/network/doc/images/blockingfortuneclient-example.png create mode 100644 examples/network/doc/images/broadcastreceiver-example.png create mode 100644 examples/network/doc/images/broadcastsender-example.png create mode 100644 examples/network/doc/images/fortuneclient-example.png create mode 100644 examples/network/doc/images/fortuneserver-example.png create mode 100644 examples/network/doc/images/googlesuggest-example.png create mode 100644 examples/network/doc/images/http-example.png create mode 100644 examples/network/doc/images/loopback-example.png create mode 100644 examples/network/doc/images/multicastreceiver-example.png create mode 100644 examples/network/doc/images/multicastsender-example.png create mode 100644 examples/network/doc/images/network-chat-example.png create mode 100644 examples/network/doc/images/securesocketclient.png create mode 100644 examples/network/doc/images/securesocketclient2.png create mode 100644 examples/network/doc/images/threadedfortuneserver-example.png create mode 100644 examples/network/doc/images/torrent-example.png create mode 100644 examples/network/doc/src/blockingfortuneclient.qdoc create mode 100644 examples/network/doc/src/broadcastreceiver.qdoc create mode 100644 examples/network/doc/src/broadcastsender.qdoc create mode 100644 examples/network/doc/src/fortuneclient.qdoc create mode 100644 examples/network/doc/src/fortuneserver.qdoc create mode 100644 examples/network/doc/src/googlesuggest.qdoc create mode 100644 examples/network/doc/src/http.qdoc create mode 100644 examples/network/doc/src/loopback.qdoc create mode 100644 examples/network/doc/src/multicastreceiver.qdoc create mode 100644 examples/network/doc/src/multicastsender.qdoc create mode 100644 examples/network/doc/src/network-chat.qdoc create mode 100644 examples/network/doc/src/securesocketclient.qdoc create mode 100644 examples/network/doc/src/threadedfortuneserver.qdoc create mode 100644 examples/network/doc/src/torrent.qdoc (limited to 'examples/network/doc') diff --git a/examples/network/doc/images/blockingfortuneclient-example.png b/examples/network/doc/images/blockingfortuneclient-example.png new file mode 100644 index 0000000000..cdb7cac0d3 Binary files /dev/null and b/examples/network/doc/images/blockingfortuneclient-example.png differ diff --git a/examples/network/doc/images/broadcastreceiver-example.png b/examples/network/doc/images/broadcastreceiver-example.png new file mode 100644 index 0000000000..b83789523c Binary files /dev/null and b/examples/network/doc/images/broadcastreceiver-example.png differ diff --git a/examples/network/doc/images/broadcastsender-example.png b/examples/network/doc/images/broadcastsender-example.png new file mode 100644 index 0000000000..bf7ccbeb9e Binary files /dev/null and b/examples/network/doc/images/broadcastsender-example.png differ diff --git a/examples/network/doc/images/fortuneclient-example.png b/examples/network/doc/images/fortuneclient-example.png new file mode 100644 index 0000000000..b34a98736d Binary files /dev/null and b/examples/network/doc/images/fortuneclient-example.png differ diff --git a/examples/network/doc/images/fortuneserver-example.png b/examples/network/doc/images/fortuneserver-example.png new file mode 100644 index 0000000000..73f27d5653 Binary files /dev/null and b/examples/network/doc/images/fortuneserver-example.png differ diff --git a/examples/network/doc/images/googlesuggest-example.png b/examples/network/doc/images/googlesuggest-example.png new file mode 100644 index 0000000000..477d444cbd Binary files /dev/null and b/examples/network/doc/images/googlesuggest-example.png differ diff --git a/examples/network/doc/images/http-example.png b/examples/network/doc/images/http-example.png new file mode 100644 index 0000000000..16b0539b1b Binary files /dev/null and b/examples/network/doc/images/http-example.png differ diff --git a/examples/network/doc/images/loopback-example.png b/examples/network/doc/images/loopback-example.png new file mode 100644 index 0000000000..2b1bd4a0f2 Binary files /dev/null and b/examples/network/doc/images/loopback-example.png differ diff --git a/examples/network/doc/images/multicastreceiver-example.png b/examples/network/doc/images/multicastreceiver-example.png new file mode 100644 index 0000000000..8de11cda63 Binary files /dev/null and b/examples/network/doc/images/multicastreceiver-example.png differ diff --git a/examples/network/doc/images/multicastsender-example.png b/examples/network/doc/images/multicastsender-example.png new file mode 100644 index 0000000000..a619b047e3 Binary files /dev/null and b/examples/network/doc/images/multicastsender-example.png differ diff --git a/examples/network/doc/images/network-chat-example.png b/examples/network/doc/images/network-chat-example.png new file mode 100644 index 0000000000..949bb07d87 Binary files /dev/null and b/examples/network/doc/images/network-chat-example.png differ diff --git a/examples/network/doc/images/securesocketclient.png b/examples/network/doc/images/securesocketclient.png new file mode 100644 index 0000000000..8736cbc264 Binary files /dev/null and b/examples/network/doc/images/securesocketclient.png differ diff --git a/examples/network/doc/images/securesocketclient2.png b/examples/network/doc/images/securesocketclient2.png new file mode 100644 index 0000000000..23db851e61 Binary files /dev/null and b/examples/network/doc/images/securesocketclient2.png differ diff --git a/examples/network/doc/images/threadedfortuneserver-example.png b/examples/network/doc/images/threadedfortuneserver-example.png new file mode 100644 index 0000000000..57c66a5605 Binary files /dev/null and b/examples/network/doc/images/threadedfortuneserver-example.png differ diff --git a/examples/network/doc/images/torrent-example.png b/examples/network/doc/images/torrent-example.png new file mode 100644 index 0000000000..1032716e04 Binary files /dev/null and b/examples/network/doc/images/torrent-example.png differ diff --git a/examples/network/doc/src/blockingfortuneclient.qdoc b/examples/network/doc/src/blockingfortuneclient.qdoc new file mode 100644 index 0000000000..90bf439354 --- /dev/null +++ b/examples/network/doc/src/blockingfortuneclient.qdoc @@ -0,0 +1,216 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example blockingfortuneclient + \title Blocking Fortune Client Example + + The Blocking Fortune Client example shows how to create a client for a + network service using QTcpSocket's synchronous API in a non-GUI thread. + + \image blockingfortuneclient-example.png + + QTcpSocket supports two general approaches to network programming: + + \list + + \li \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()}. + + \li \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 + + The implementation is very similar to the + \l{fortuneclient}{Fortune Client} example, but instead of having + QTcpSocket as a member of the main class, doing asynchronous networking in + the main thread, we will do all network operations in a separate thread + and use QTcpSocket's blocking API. + + The purpose of this example is to demonstrate a pattern that you can use + to simplify your networking code, without losing responsiveness in your + user interface. Use of Qt's blocking network API often leads to + simpler code, but because of its blocking behavior, it should only be used + in non-GUI threads to prevent the user interface from freezing. But + contrary to what many think, using threads with QThread does not + necessarily add unmanagable complexity to your application. + + We will start with the FortuneThread class, which handles the network + code. + + \snippet blockingfortuneclient/fortunethread.h 0 + + FortuneThread is a QThread subclass that provides an API for scheduling + requests for fortunes, and it has signals for delivering fortunes and + reporting errors. You can call requestNewFortune() to request a new + fortune, and the result is delivered by the newFortune() signal. If any + error occurs, the error() signal is emitted. + + It's important to notice that requestNewFortune() is called from the main, + GUI thread, but the host name and port values it stores will be accessed + from FortuneThread's thread. Because we will be reading and writing + FortuneThread's data members from different threads concurrently, we use + QMutex to synchronize access. + + \snippet blockingfortuneclient/fortunethread.cpp 2 + + The requestNewFortune() function stores the host name and port of the + fortune server as member data, and we lock the mutex with QMutexLocker to + protect this data. We then start the thread, unless it is already + running. We will come back to the QWaitCondition::wakeOne() call later. + + \snippet blockingfortuneclient/fortunethread.cpp 4 + \snippet blockingfortuneclient/fortunethread.cpp 5 + + In the run() function, we start by acquiring the mutex lock, fetching the + host name and port from the member data, and then releasing the lock + again. The case that we are protecting ourselves against is that \c + requestNewFortune() could be called at the same time as we are fetching + this data. QString is \l reentrant but \e not \l{thread-safe}, and we must + also avoid the unlikely risk of reading the host name from one request, + and port of another. And as you might have guessed, FortuneThread can only + handle one request at a time. + + The run() function now enters a loop: + + \snippet blockingfortuneclient/fortunethread.cpp 6 + + The loop will continue requesting fortunes for as long as \e quit is + false. We start our first request by creating a QTcpSocket on the stack, + and then we call \l{QTcpSocket::connectToHost()}{connectToHost()}. This + starts an asynchronous operation which, after control returns to Qt's + event loop, will cause QTcpSocket to emit + \l{QTcpSocket::connected()}{connected()} or + \l{QTcpSocket::error()}{error()}. + + \snippet blockingfortuneclient/fortunethread.cpp 8 + + But since we are running in a non-GUI thread, we do not have to worry + about blocking the user interface. So instead of entering an event loop, + we simply call QTcpSocket::waitForConnected(). This function will wait, + blocking the calling thread, until QTcpSocket emits connected() or an + error occurs. If connected() is emitted, the function returns true; if the + connection failed or timed out (which in this example happens after 5 + seconds), false is returned. QTcpSocket::waitForConnected(), like the + other \c waitFor...() functions, is part of QTcpSocket's \e{blocking + API}. + + After this statement, we have a connected socket to work with. Now it's + time to see what the fortune server has sent us. + + \snippet blockingfortuneclient/fortunethread.cpp 9 + \snippet blockingfortuneclient/fortunethread.cpp 10 + + This step is to read the size of the packet. Although we are only reading + two bytes here, and the \c while loop may seem to overdo it, we present this + code to demonstrate a good pattern for waiting for data using + QTcpSocket::waitForReadyRead(). It goes like this: For as long as we still + need more data, we call waitForReadyRead(). If it returns false, + we abort the operation. After this statement, we know that we have received + enough data. + + \snippet blockingfortuneclient/fortunethread.cpp 11 + + Now we can create a QDataStream object, passing the socket to + QDataStream's constructor, and as in the other client examples we set + the stream protocol version to QDataStream::Qt_4_0, and read the size + of the packet. + + \snippet blockingfortuneclient/fortunethread.cpp 12 + \snippet blockingfortuneclient/fortunethread.cpp 13 + + Again, we'll use a loop that waits for more data by calling + QTcpSocket::waitForReadyRead(). In this loop, we're waiting until + QTcpSocket::bytesAvailable() returns the full packet size. + + \snippet blockingfortuneclient/fortunethread.cpp 14 + + Now that we have all the data that we need, we can use QDataStream to + read the fortune string from the packet. The resulting fortune is + delivered by emitting newFortune(). + + \snippet blockingfortuneclient/fortunethread.cpp 15 + + The final part of our loop is that we acquire the mutex so that we can + safely read from our member data. We then let the thread go to sleep by + calling QWaitCondition::wait(). At this point, we can go back to + requestNewFortune() and look closed at the call to wakeOne(): + + \snippet blockingfortuneclient/fortunethread.cpp 1 + \dots + \snippet blockingfortuneclient/fortunethread.cpp 3 + + What happened here was that because the thread falls asleep waiting for a + new request, we needed to wake it up again when a new request + arrives. QWaitCondition is often used in threads to signal a wakeup call + like this. + + \snippet blockingfortuneclient/fortunethread.cpp 0 + + Finishing off the FortuneThread walkthrough, this is the destructor that + sets \e quit to true, wakes up the thread and waits for the thread to exit + before returning. This lets the \c while loop in run() will finish its current + iteration. When run() returns, the thread will terminate and be destroyed. + + Now for the BlockingClient class: + + \snippet blockingfortuneclient/blockingclient.h 0 + + BlockingClient is very similar to the Client class in the + \l{fortuneclient}{Fortune Client} example, but in this class + we store a FortuneThread member instead of a pointer to a QTcpSocket. + When the user clicks the "Get Fortune" button, the same slot is called, + but its implementation is slightly different: + + \snippet blockingfortuneclient/blockingclient.cpp 0 + \snippet blockingfortuneclient/blockingclient.cpp 1 + + We connect our FortuneThread's two signals newFortune() and error() (which + are somewhat similar to QTcpSocket::readyRead() and QTcpSocket::error() in + the previous example) to requestNewFortune() and displayError(). + + \snippet blockingfortuneclient/blockingclient.cpp 2 + + The requestNewFortune() slot calls FortuneThread::requestNewFortune(), + which \e shedules the request. When the thread has received a new fortune + and emits newFortune(), our showFortune() slot is called: + + \snippet blockingfortuneclient/blockingclient.cpp 3 + \codeline + \snippet blockingfortuneclient/blockingclient.cpp 4 + + Here, we simply display the fortune we received as the argument. + + \sa {Fortune Client Example}, {Fortune Server Example} +*/ diff --git a/examples/network/doc/src/broadcastreceiver.qdoc b/examples/network/doc/src/broadcastreceiver.qdoc new file mode 100644 index 0000000000..61abcca15f --- /dev/null +++ b/examples/network/doc/src/broadcastreceiver.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example broadcastreceiver + \title Broadcast Receiver Example + + The Broadcast Receiver example shows how to receive information that is broadcasted + over a local network. + + \image broadcastreceiver-example.png +*/ diff --git a/examples/network/doc/src/broadcastsender.qdoc b/examples/network/doc/src/broadcastsender.qdoc new file mode 100644 index 0000000000..79127efbfb --- /dev/null +++ b/examples/network/doc/src/broadcastsender.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example broadcastsender + \title Broadcast Sender Example + + The Broadcast Sender example shows how to broadcast information to multiple clients + on a local network. + + \image broadcastsender-example.png +*/ diff --git a/examples/network/doc/src/fortuneclient.qdoc b/examples/network/doc/src/fortuneclient.qdoc new file mode 100644 index 0000000000..ccf5d8f150 --- /dev/null +++ b/examples/network/doc/src/fortuneclient.qdoc @@ -0,0 +1,160 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example 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{fortuneserver}{Fortune Server} example or + the \l{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{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 + + \li \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()}. + + \li \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{blockingfortuneclient}{Blocking Fortune Client} example + illustrates the synchronous approach. + + Our class contains some data and a few private slots: + + \snippet 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 fortuneclient/client.cpp 0 + \dots + \snippet 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 fortuneclient/client.cpp 3 + \dots + \snippet fortuneclient/client.cpp 5 + + Clicking the \uicontrol{Get Fortune} button will invoke the \c + requestNewFortune() slot: + + \snippet 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 \uicontrol{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 + \li \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. + + \li \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 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 fortuneclient/client.cpp 8 + \codeline + \snippet 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 fortuneclient/client.cpp 11 + \codeline + \snippet 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} +*/ diff --git a/examples/network/doc/src/fortuneserver.qdoc b/examples/network/doc/src/fortuneserver.qdoc new file mode 100644 index 0000000000..0bc50283c3 --- /dev/null +++ b/examples/network/doc/src/fortuneserver.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example fortuneserver + \title Fortune Server Example + + The Fortune Server example shows how to create a server for a simple + network service. It is intended to be run alongside the + \l{fortuneclient}{Fortune Client} example or the + \l{blockingfortuneclient}{Blocking Fortune Client} example. + + \image fortuneserver-example.png Screenshot of the Fortune Server example + + This example uses QTcpServer to accept incoming TCP connections, and a + simple QDataStream based data transfer protocol to write a fortune to the + connecting client (from the \l{fortuneclient}{Fortune Client} + example), before closing the connection. + + \snippet fortuneserver/server.h 0 + + The server is implemented using a simple class with only one slot, for + handling incoming connections. + + \snippet fortuneserver/server.cpp 1 + + In its constructor, our Server object calls QTcpServer::listen() to set up + a QTcpServer to listen on all addresses, on an arbitrary port. In then + displays the port QTcpServer picked in a label, so that user knows which + port the fortune client should connect to. + + \snippet fortuneserver/server.cpp 2 + + Our server generates a list of random fortunes that is can send to + connecting clients. + + \snippet fortuneserver/server.cpp 3 + + When a client connects to our server, QTcpServer will emit + QTcpServer::newConnection(). In turn, this will invoke our + sendFortune() slot: + + \snippet fortuneserver/server.cpp 4 + + The purpose of this slot is to select a random line from our list of + fortunes, encode it into a QByteArray using QDataStream, and then write it + to the connecting socket. This is a common way to transfer binary data + using QTcpSocket. First we create a QByteArray and a QDataStream object, + passing the bytearray to QDataStream's constructor. We then explicitly set + the protocol version of QDataStream to QDataStream::Qt_4_0 to ensure that + we can communicate with clients from future versions of Qt. (See + QDataStream::setVersion().) + + \snippet fortuneserver/server.cpp 6 + + At the start of our QByteArray, we reserve space for a 16 bit integer that + will contain the total size of the data block we are sending. We continue + by streaming in a random fortune. Then we seek back to the beginning of + the QByteArray, and overwrite the reserved 16 bit integer value with the + total size of the array. By doing this, we provide a way for clients to + verify how much data they can expect before reading the whole packet. + + \snippet fortuneserver/server.cpp 7 + + We then call QTcpServer::newPendingConnection(), which returns the + QTcpSocket representing the server side of the connection. By connecting + QTcpSocket::disconnected() to QObject::deleteLater(), we ensure that the + socket will be deleted after disconnecting. + + \snippet fortuneserver/server.cpp 8 + + The encoded fortune is written using QTcpSocket::write(), and we finally + call QTcpSocket::disconnectFromHost(), which will close the connection + after QTcpSocket has finished writing the fortune to the network. Because + QTcpSocket works asynchronously, the data will be written after this + function returns, and control goes back to Qt's event loop. The socket + will then close, which in turn will cause QObject::deleteLater() to delete + it. + + \sa {Fortune Client Example}, {Threaded Fortune Server Example} + */ diff --git a/examples/network/doc/src/googlesuggest.qdoc b/examples/network/doc/src/googlesuggest.qdoc new file mode 100644 index 0000000000..b083f0cd58 --- /dev/null +++ b/examples/network/doc/src/googlesuggest.qdoc @@ -0,0 +1,180 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example googlesuggest + \title Google Suggest Example + + The Google Suggest example demonstrates how to use the QNetworkAccessManager + class to obtain a list of suggestions from the Google search engine as the + user types into a QLineEdit. + + \image googlesuggest-example.png + + The application makes use of the \c get function in + QNetworkAccessManager to post a request and obtain the result of the search + query sent to the Google search engine. The results returned are listed as + clickable links appearing below the search box as a drop-down menu. + + The widget is built up by a QLineEdit as the search box, and a QTreeView + used as a popup menu below the search box. + + \section1 GSuggestCompletion Class Declaration + + This class implements an event filter and a number of functions to display + the search results and to determent when and how to perform the search. + + \snippet googlesuggest/googlesuggest.h 1 + + The class connects to a QLineEdit and uses a QTreeWidget to display the + results. A QTimer controls the start of the network requests that are + executed using a QNetworkAccessManager. + + \section1 GSuggestCompletion Class Implementation + + We start by defining a constant containing the URL to be used in the Google + queries. This is the basis for the query. The letters typed into the search + box will be added to the query to perform the search itself. + + \snippet googlesuggest/googlesuggest.cpp 1 + + In the constructor, we set the parent of this GSuggestCompletion instance + to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored + in the explicit \c editor member variable. + + We then create a QTreeWidget as a toplevel widget and configure the various + properties to give it the look of a popup widget. + + The popup will be populated by the results returned from Google. We set + the number of columns to be two, since we want to display both the + suggested search term and the number of hits it will trigger in the search + engine. + + Furthermore, we install the GSuggestCompletion instance as an event filter + on the QTreeWidget, and connect the \c itemClicked() signal with the \c + doneCompletion() slot. + + A single-shot QTimer is used to start the request when the user has stopped + typing for 500 ms. + + Finally, we connect the networkManagers \c finished() signal with the \c + handleNetworkData() slot to handle the incoming data. + + \snippet googlesuggest/googlesuggest.cpp 2 + + Since the QTreeWidget popup has been instantiated as a toplevel widget, the + destructor has to delete it explicitly from memory to avoid a memory leak. + + \snippet googlesuggest/googlesuggest.cpp 3 + + The event filter handles mouse press and key press events that are + delivered to the popup. For mouse press events we just hide the popup and + return focus to the editor widget, and then return true to prevent further + event processing. + + Key event handling is implemented so that Enter and Return execute the + selected link, while the Escape key hides the popup. Since we want to be + able to navigate the list of suggestions using the different navigation + keys on the keyboard we let Qt continue regular event processing for those + by returning false from the eventFilter reimplementation. + + For all other keys, the event will be passed on to the editor widget and the + popup is hidden. This way the user's typing will not be interrupted by the + popping up of the completion list. + + \snippet googlesuggest/googlesuggest.cpp 4 + + The \c showCompletion() function populates the QTreeWidget with the results + returned from the query. It takes two QStringLists, one with the suggested + search terms and the other with the corresponding number of hits. + + \snippet googlesuggest/googlesuggest.cpp 5 + + A QTreeWidgetItem is created for each index in the list and inserted into + the QTreeWidget. Finally, we adjust position and size of the popup to make + sure that it pops up in the correct position below the editor, and show it. + + The \c doneCompletion() function, which is called by the event filter when + either Enter or Return keys are pressed, stops the timer to prevent further + requests and passes the text of the selected item to the editor. We then + make the \c editor QLineEdit emit the returnPressed() signal, to which the + application can connect to open the respective web page. + + \snippet googlesuggest/googlesuggest.cpp 6 + + The \c autoSuggest() slot is called when the timer times out, and uses the + text in the editor to build the complete search query. The query is then + passed to the QNetworkAccessManager's \c get() function to start the + request. + + \snippet googlesuggest/googlesuggest.cpp 7 + + The function \c preventSuggest() stops the timer to prevent further + requests from being started. + + \snippet googlesuggest/googlesuggest.cpp 8 + + When the network request is finished, the QNetworkAccessManager delivers the + data received from the server through the networkReply object. + + \snippet googlesuggest/googlesuggest.cpp 9 + + To extract the data from the reply we use the \c readAll() function, which + is inherited from QIODevice and returns a QByteArray. Since this data is + encoded in XML we can use a QXmlStreamReader to traverse the data and + extract the search result as QStrings, which we can stream into two + QStringLists used to populate the popup. + + Finally, we schedule the QNetworkReply object for deletion using the \c + deleteLater function. + + \section1 SearchBox Class Declaration + + The SearchBox class inherits QLineEdit and adds the protected slot \c + doSearch(). + + A \c GSuggestCompletion member provides the SearchBox with the request + functionality and the suggestions returned from the Google search engine. + + \snippet googlesuggest/searchbox.h 1 + + \section1 SearchBox Class Implementation + + The search box constructor instantiates the GSuggestCompletion object and + connects the returnPressed() signal to the doSearch() slot. + + \snippet googlesuggest/searchbox.cpp 1 + + The function \c doSearch() stops the completer from sending any further + queries to the search engine. + + Further, the function extracts the selected search phrase and opens it + in the default web browser using QDesktopServices. + + \snippet googlesuggest/searchbox.cpp 2 + +*/ diff --git a/examples/network/doc/src/http.qdoc b/examples/network/doc/src/http.qdoc new file mode 100644 index 0000000000..6b30a83c96 --- /dev/null +++ b/examples/network/doc/src/http.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example http + \title HTTP Example + + The HTTP example demonstrates a simple HTTP client that shows how to fetch files + specified by URLs from remote hosts. + + \image http-example.png +*/ diff --git a/examples/network/doc/src/loopback.qdoc b/examples/network/doc/src/loopback.qdoc new file mode 100644 index 0000000000..ecae81307b --- /dev/null +++ b/examples/network/doc/src/loopback.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example loopback + \title Loopback Example + + The Loopback example shows how to communicate between simple clients and servers on a local + host. + + \image loopback-example.png +*/ diff --git a/examples/network/doc/src/multicastreceiver.qdoc b/examples/network/doc/src/multicastreceiver.qdoc new file mode 100644 index 0000000000..e36e01a38c --- /dev/null +++ b/examples/network/doc/src/multicastreceiver.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multicastreceiver + \title Multicast Receiver Example + + The Multicast Receiever example shows how to receive information that is + sent to a multicast group. + + \image multicastreceiver-example.png +*/ diff --git a/examples/network/doc/src/multicastsender.qdoc b/examples/network/doc/src/multicastsender.qdoc new file mode 100644 index 0000000000..a1d70caf86 --- /dev/null +++ b/examples/network/doc/src/multicastsender.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multicastsender + \title Multicast Sender Example + + The Multicast Sender example shows how to send information to multiple + clients in a multicast group. + + \image multicastsender-example.png +*/ diff --git a/examples/network/doc/src/network-chat.qdoc b/examples/network/doc/src/network-chat.qdoc new file mode 100644 index 0000000000..3e0d7540b9 --- /dev/null +++ b/examples/network/doc/src/network-chat.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network-chat + \title Network Chat Example + + The Network Chat example demonstrates a stateful peer-to-peer Chat client + that uses broadcasting with QUdpSocket and QNetworkInterface to discover + its peers. + + \image network-chat-example.png +*/ diff --git a/examples/network/doc/src/securesocketclient.qdoc b/examples/network/doc/src/securesocketclient.qdoc new file mode 100644 index 0000000000..b740af3531 --- /dev/null +++ b/examples/network/doc/src/securesocketclient.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example securesocketclient + \title Secure Socket Client Example + + The Secure Socket Client example shows how to use QSslSocket to + communicate over an encrypted (SSL) connection. It also demonstrates how + to deal with authenticity problems, and how to display security and + certificate information. + + \image securesocketclient.png + \image securesocketclient2.png +*/ diff --git a/examples/network/doc/src/threadedfortuneserver.qdoc b/examples/network/doc/src/threadedfortuneserver.qdoc new file mode 100644 index 0000000000..33b6892363 --- /dev/null +++ b/examples/network/doc/src/threadedfortuneserver.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threadedfortuneserver + \title Threaded Fortune Server Example + + The Threaded Fortune Server example shows how to create a server for a + simple network service that uses threads to handle requests from different + clients. It is intended to be run alongside the Fortune Client example. + + \image threadedfortuneserver-example.png + + The implementation of this example is similar to that of the + \l{fortuneserver}{Fortune Server} example, but here we will + implement a subclass of QTcpServer that starts each connection in a + different thread. + + For this we need two classes: FortuneServer, a QTcpServer subclass, and + FortuneThread, which inherits QThread. + + \snippet threadedfortuneserver/fortuneserver.h 0 + + FortuneServer inherits QTcpServer and reimplements + QTcpServer::incomingConnection(). We also use it for storing the list of + random fortunes. + + \snippet threadedfortuneserver/fortuneserver.cpp 0 + + We use FortuneServer's constructor to simply generate the list of + fortunes. + + \snippet threadedfortuneserver/fortuneserver.cpp 1 + + Our implementation of QTcpServer::incomingConnection() creates a + FortuneThread object, passing the incoming socket descriptor and a random + fortune to FortuneThread's constructor. By connecting FortuneThread's + finished() signal to QObject::deleteLater(), we ensure that the thread + gets deleted once it has finished. We can then call QThread::start(), + which starts the thread. + + \snippet threadedfortuneserver/fortunethread.h 0 + + Moving on to the FortuneThread class, this is a QThread subclass whose job + is to write the fortune to the connected socket. The class reimplements + QThread::run(), and it has a signal for reporting errors. + + \snippet threadedfortuneserver/fortunethread.cpp 0 + + FortuneThread's constructor simply stores the socket descriptor and + fortune text, so that they are available for run() later on. + + \snippet threadedfortuneserver/fortunethread.cpp 1 + + The first thing our run() function does is to create a QTcpSocket object + on the stack. What's worth noticing is that we are creating this object + inside the thread, which automatically associates the socket to the + thread's event loop. This ensures that Qt will not try to deliver events + to our socket from the main thread while we are accessing it from + FortuneThread::run(). + + \snippet threadedfortuneserver/fortunethread.cpp 2 + + The socket is initialized by calling QTcpSocket::setSocketDescriptor(), + passing our socket descriptor as an argument. We expect this to succeed, + but just to be sure, (although unlikely, the system may run out of + resources,) we catch the return value and report any error. + + \snippet threadedfortuneserver/fortunethread.cpp 3 + + As with the \l{fortuneserver}{Fortune Server} example, we encode + the fortune into a QByteArray using QDataStream. + + \snippet threadedfortuneserver/fortunethread.cpp 4 + + But unlike the previous example, we finish off by calling + QTcpSocket::waitForDisconnected(), which blocks the calling thread until + the socket has disconnected. Because we are running in a separate thread, + the GUI will remain responsive. + + \sa {Fortune Server Example}, {Fortune Client Example}, {Blocking Fortune + Client Example} +*/ diff --git a/examples/network/doc/src/torrent.qdoc b/examples/network/doc/src/torrent.qdoc new file mode 100644 index 0000000000..a13d447277 --- /dev/null +++ b/examples/network/doc/src/torrent.qdoc @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example torrent + \title Torrent Example + + The Torrent example is a functional BitTorrent client that + illustrates how to write a complex TCP/IP application using Qt. + + \image torrent-example.png + + \section1 License Information + + The implementation of the US Secure Hash Algorithm 1 (SHA1) in this example is + derived from the original description in \l{RFC 3174}. + + \legalese + Copyright (C) The Internet Society (2001). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + \endlegalese +*/ -- cgit v1.2.3