Move opengl/wid/net example docs to proper folders.

Change-Id: I846439a9cf7ad965ed27a00f98dbc4ff97abe73b
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>

29 files changed, 1129 insertions, 0 deletions

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
--- /dev/null
+++ b/examples/network/doc/images/blockingfortuneclient-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/broadcastreceiver-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/broadcastsender-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/fortuneclient-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/fortuneserver-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/googlesuggest-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/http-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/loopback-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/multicastreceiver-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/multicastsender-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/network-chat-example.png
diff --git a/examples/network/doc/images/securesocketclient.png b/examples/network/doc/images/securesocketclient.png
new file mode 100644
index 0000000000..8736cbc264
--- /dev/null
+++ b/examples/network/doc/images/securesocketclient.png
diff --git a/examples/network/doc/images/securesocketclient2.png b/examples/network/doc/images/securesocketclient2.png
new file mode 100644
index 0000000000..23db851e61
--- /dev/null
+++ b/examples/network/doc/images/securesocketclient2.png
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
--- /dev/null
+++ b/examples/network/doc/images/threadedfortuneserver-example.png
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
--- /dev/null
+++ b/examples/network/doc/images/torrent-example.png
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
+*/