diff options
| author | Marius Storm-Olsen <marius.storm-olsen@nokia.com> | 2012-05-10 09:11:17 +0200 |
|---|---|---|
| committer | Marius Storm-Olsen <marius.storm-olsen@nokia.com> | 2012-05-10 09:11:23 +0200 |
| commit | 9456528aac80c6d4c41fa96d88696dc55414b710 (patch) | |
| tree | f9fdcc9cd3c7468503590bec7ed082294a0cffde /src/network | |
| parent | 75552c8f62dcfb8012c306b37c79ec629448d780 (diff) | |
| parent | ee38dec6f3aff6f7f277323c5c8488d4cd385693 (diff) | |
Merge branch 'docs-refactoring' into master
Change-Id: Iebd1966abace3cdf7f9428dcfc1ded5b124ab113
Diffstat (limited to 'src/network')
52 files changed, 2123 insertions, 57 deletions
diff --git a/src/network/access/qftp.cpp b/src/network/access/qftp.cpp index ba30ad08ba..324126baae 100644 --- a/src/network/access/qftp.cpp +++ b/src/network/access/qftp.cpp @@ -1361,7 +1361,7 @@ int QFtpPrivate::addCommand(QFtpCommand *cmd) e.g. if you want to connect and login to a FTP server. This is simply achieved: - \snippet doc/src/snippets/code/src_network_access_qftp.cpp 0 + \snippet code/src_network_access_qftp.cpp 0 In this case two FTP commands have been scheduled. When the last scheduled command has finished, a done() signal is emitted with @@ -1379,12 +1379,12 @@ int QFtpPrivate::addCommand(QFtpCommand *cmd) Example: If you want to download the INSTALL file from the Qt FTP server, you would write this: - \snippet doc/src/snippets/code/src_network_access_qftp.cpp 1 + \snippet code/src_network_access_qftp.cpp 1 For this example the following sequence of signals is emitted (with small variations, depending on network traffic, etc.): - \snippet doc/src/snippets/code/src_network_access_qftp.cpp 2 + \snippet code/src_network_access_qftp.cpp 2 The dataTransferProgress() signal in the above example is useful if you want to show a \link QProgressBar progress bar \endlink to @@ -1397,7 +1397,7 @@ int QFtpPrivate::addCommand(QFtpCommand *cmd) If the login fails for the above example, the signals would look like this: - \snippet doc/src/snippets/code/src_network_access_qftp.cpp 3 + \snippet code/src_network_access_qftp.cpp 3 You can then get details about the error with the error() and errorString() functions. diff --git a/src/network/access/qhttpmultipart.cpp b/src/network/access/qhttpmultipart.cpp index 27164d69ae..ca7e2f6be8 100644 --- a/src/network/access/qhttpmultipart.cpp +++ b/src/network/access/qhttpmultipart.cpp @@ -62,7 +62,7 @@ QT_BEGIN_NAMESPACE and a data block, which are separated by each other by two consecutive new lines. An example for one part would be: - \snippet doc/src/snippets/code/src_network_access_qhttppart.cpp 0 + \snippet code/src_network_access_qhttppart.cpp 0 For setting headers, use setHeader() and setRawHeader(), which behave exactly like QNetworkRequest::setHeader() and QNetworkRequest::setRawHeader(). @@ -77,12 +77,12 @@ QT_BEGIN_NAMESPACE To construct a QHttpPart with a small body, consider the following snippet (this produces the data shown in the example above): - \snippet doc/src/snippets/code/src_network_access_qhttppart.cpp 1 + \snippet code/src_network_access_qhttppart.cpp 1 To construct a QHttpPart reading from a device (e.g. a file), the following can be applied: - \snippet doc/src/snippets/code/src_network_access_qhttppart.cpp 2 + \snippet code/src_network_access_qhttppart.cpp 2 Be aware that QHttpPart does not take ownership of the device when set, so it is the developer's responsibility to destroy it when it is not needed anymore. @@ -226,7 +226,7 @@ void QHttpPart::setBodyDevice(QIODevice *device) As an example, consider the following code snippet, which constructs a multipart message containing a text part followed by an image part: - \snippet doc/src/snippets/code/src_network_access_qhttpmultipart.cpp 0 + \snippet code/src_network_access_qhttpmultipart.cpp 0 \sa QHttpPart, QNetworkAccessManager::post() */ diff --git a/src/network/access/qnetworkaccessmanager.cpp b/src/network/access/qnetworkaccessmanager.cpp index b539ed4d9a..66d8a66b43 100644 --- a/src/network/access/qnetworkaccessmanager.cpp +++ b/src/network/access/qnetworkaccessmanager.cpp @@ -178,7 +178,7 @@ static void ensureInitialized() returned in response to the corresponding request. A simple download off the network could be accomplished with: - \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 0 + \snippet code/src_network_access_qnetworkaccessmanager.cpp 0 QNetworkAccessManager has an asynchronous API. When the \tt replyFinished slot above is called, the parameter it @@ -197,7 +197,7 @@ static void ensureInitialized() A more involved example, assuming the manager is already existent, can be: - \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 1 + \snippet code/src_network_access_qnetworkaccessmanager.cpp 1 \section1 Network and Roaming support @@ -283,11 +283,11 @@ static void ensureInitialized() By default the value of this property reflects the physical state of the device. Applications may override it to disable all network requests via this network access manager by calling - \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 4 + \snippet code/src_network_access_qnetworkaccessmanager.cpp 4 Network requests can be reenabled again by calling - \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 5 + \snippet code/src_network_access_qnetworkaccessmanager.cpp 5 \note Calling setNetworkAccessible() does not change the network state. */ @@ -805,12 +805,12 @@ QNetworkReply *QNetworkAccessManager::deleteResource(const QNetworkRequest &requ To restore the default network configuration set the network configuration to the value returned from QNetworkConfigurationManager::defaultConfiguration(). - \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 2 + \snippet code/src_network_access_qnetworkaccessmanager.cpp 2 If an invalid network configuration is set, a network session will not be created. In this case network requests will be processed regardless, but may fail. For example: - \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 3 + \snippet code/src_network_access_qnetworkaccessmanager.cpp 3 \sa configuration(), QNetworkSession */ diff --git a/src/network/access/qnetworkdiskcache.cpp b/src/network/access/qnetworkdiskcache.cpp index bcaf81a6a0..0a1d43f70f 100644 --- a/src/network/access/qnetworkdiskcache.cpp +++ b/src/network/access/qnetworkdiskcache.cpp @@ -88,17 +88,17 @@ QT_BEGIN_NAMESPACE A network disk cache can be enabled by: - \snippet doc/src/snippets/code/src_network_access_qnetworkdiskcache.cpp 0 + \snippet code/src_network_access_qnetworkdiskcache.cpp 0 When sending requests, to control the preference of when to use the cache and when to use the network, consider the following: - \snippet doc/src/snippets/code/src_network_access_qnetworkdiskcache.cpp 1 + \snippet code/src_network_access_qnetworkdiskcache.cpp 1 To check whether the response came from the cache or from the network, the following can be applied: - \snippet doc/src/snippets/code/src_network_access_qnetworkdiskcache.cpp 2 + \snippet code/src_network_access_qnetworkdiskcache.cpp 2 */ /*! diff --git a/src/network/access/qnetworkreply.cpp b/src/network/access/qnetworkreply.cpp index aefe07223f..3b6ec5d4b5 100644 --- a/src/network/access/qnetworkreply.cpp +++ b/src/network/access/qnetworkreply.cpp @@ -616,7 +616,7 @@ void QNetworkReply::setSslConfiguration(const QSslConfiguration &config) If, for instance, you want to issue a request to a server that uses a self-signed certificate, consider the following snippet: - \snippet doc/src/snippets/code/src_network_access_qnetworkreply.cpp 0 + \snippet code/src_network_access_qnetworkreply.cpp 0 Multiple calls to this function will replace the list of errors that were passed in previous calls. diff --git a/src/network/access/qnetworkrequest.cpp b/src/network/access/qnetworkrequest.cpp index 1c8655e9ae..9df06328a1 100644 --- a/src/network/access/qnetworkrequest.cpp +++ b/src/network/access/qnetworkrequest.cpp @@ -487,7 +487,7 @@ QList<QByteArray> QNetworkRequest::rawHeaderList() const the corresponding "cooked" header will be set as well. For example: - \snippet doc/src/snippets/code/src_network_access_qnetworkrequest.cpp 0 + \snippet code/src_network_access_qnetworkrequest.cpp 0 will also set the known header LastModifiedHeader to be the QDateTime object of the parsed date. diff --git a/src/network/bearer/qnetworkconfigmanager.cpp b/src/network/bearer/qnetworkconfigmanager.cpp index 511bec8f23..0561ea93d1 100644 --- a/src/network/bearer/qnetworkconfigmanager.cpp +++ b/src/network/bearer/qnetworkconfigmanager.cpp @@ -321,7 +321,7 @@ QNetworkConfiguration QNetworkConfigurationManager::configurationFromIdentifier( This is equivalent to the following code snippet: - \snippet doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp 0 + \snippet code/src_network_bearer_qnetworkconfigmanager.cpp 0 \sa onlineStateChanged() */ diff --git a/src/network/doc/doc.pri b/src/network/doc/doc.pri deleted file mode 100644 index 7ca0ad07d4..0000000000 --- a/src/network/doc/doc.pri +++ /dev/null @@ -1,3 +0,0 @@ -qtPrepareTool(QDOC, qdoc) -docs.commands += $$QDOC $$QT.network.sources/doc/qtnetwork.qdocconf -QMAKE_EXTRA_TARGETS += docs diff --git a/src/network/doc/images/roaming-states.png b/src/network/doc/images/roaming-states.png Binary files differnew file mode 100644 index 0000000000..bc61cac219 --- /dev/null +++ b/src/network/doc/images/roaming-states.png diff --git a/src/network/doc/images/tcpstream.png b/src/network/doc/images/tcpstream.png Binary files differnew file mode 100644 index 0000000000..7975376c8c --- /dev/null +++ b/src/network/doc/images/tcpstream.png diff --git a/src/network/doc/images/udppackets.png b/src/network/doc/images/udppackets.png Binary files differnew file mode 100644 index 0000000000..bd66c3f65e --- /dev/null +++ b/src/network/doc/images/udppackets.png diff --git a/src/network/doc/qtnetwork.qdocconf b/src/network/doc/qtnetwork.qdocconf index 2e58ad65c9..e14fb32232 100644 --- a/src/network/doc/qtnetwork.qdocconf +++ b/src/network/doc/qtnetwork.qdocconf @@ -2,7 +2,7 @@ include(../../../doc/global/qt-cpp-ignore.qdocconf) project = QtNetwork description = Qt Network Reference Documentation -url = http://qt-project.org/doc/qt-5.0/qtsql +url = http://qt-project.org/doc/qt-5.0/qtnetwork version = 5.0.0 sourceencoding = UTF-8 diff --git a/src/network/doc/snippets/code/doc_src_qtnetwork.cpp b/src/network/doc/snippets/code/doc_src_qtnetwork.cpp new file mode 100644 index 0000000000..7fa8a29db0 --- /dev/null +++ b/src/network/doc/snippets/code/doc_src_qtnetwork.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +#include <QtNetwork> +//! [1] diff --git a/src/network/doc/snippets/code/doc_src_qtnetwork.pro b/src/network/doc/snippets/code/doc_src_qtnetwork.pro new file mode 100644 index 0000000000..a100943e58 --- /dev/null +++ b/src/network/doc/snippets/code/doc_src_qtnetwork.pro @@ -0,0 +1,3 @@ +#! [0] +QT += network +#! [0] diff --git a/src/network/doc/snippets/code/src_network_access_qftp.cpp b/src/network/doc/snippets/code/src_network_access_qftp.cpp new file mode 100644 index 0000000000..db1817ce9f --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qftp.cpp @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFtp *ftp = new QFtp(parent); +ftp->connectToHost("ftp.qt.nokia.com"); +ftp->login(); +//! [0] + + +//! [1] +ftp->connectToHost("ftp.qt.nokia.com"); // id == 1 +ftp->login(); // id == 2 +ftp->cd("qt"); // id == 3 +ftp->get("INSTALL"); // id == 4 +ftp->close(); // id == 5 +//! [1] + + +//! [2] +start(1) +stateChanged(HostLookup) +stateChanged(Connecting) +stateChanged(Connected) +finished(1, false) + +start(2) +stateChanged(LoggedIn) +finished(2, false) + +start(3) +finished(3, false) + +start(4) +dataTransferProgress(0, 3798) +dataTransferProgress(2896, 3798) +readyRead() +dataTransferProgress(3798, 3798) +readyRead() +finished(4, false) + +start(5) +stateChanged(Closing) +stateChanged(Unconnected) +finished(5, false) + +done(false) +//! [2] + + +//! [3] +start(1) +stateChanged(HostLookup) +stateChanged(Connecting) +stateChanged(Connected) +finished(1, false) + +start(2) +finished(2, true) + +done(true) +//! [3] diff --git a/src/network/doc/snippets/code/src_network_access_qhttpmultipart.cpp b/src/network/doc/snippets/code/src_network_access_qhttpmultipart.cpp new file mode 100644 index 0000000000..981a93a3ca --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qhttpmultipart.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ + +//! [0] +QHttpMultiPart *multiPart = new QHttpMultiPart(QHttpMultiPart::FormDataType); + +QHttpPart textPart; +textPart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"text\"")); +textPart.setBody("my text"); + +QHttpPart imagePart; +imagePart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("image/jpeg")); +imagePart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"image\"")); +QFile *file = new QFile("image.jpg"); +file->open(QIODevice::ReadOnly); +imagePart.setBodyDevice(file); +file->setParent(multiPart); // we cannot delete the file now, so delete it with the multiPart + +multiPart->append(textPart); +multiPart->append(imagePart); + +QUrl url("http://my.server.tld"); +QNetworkRequest request(url); + +QNetworkAccessManager manager; +QNetworkReply *reply = manager.post(request, multiPart); +multiPart->setParent(reply); // delete the multiPart with the reply +// here connect signals etc. +//! [0] diff --git a/src/network/doc/snippets/code/src_network_access_qhttppart.cpp b/src/network/doc/snippets/code/src_network_access_qhttppart.cpp new file mode 100644 index 0000000000..1dca3d6683 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qhttppart.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ + +//! [0] +Content-Type: text/plain +Content-Disposition: form-data; name="text" + +here goes the body +//! [0] + +//! [1] +QHttpPart textPart; +textPart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("text/plain")); +textPart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"text\"")); +textPart.setBody("here goes the body"); +//! [1] + +//! [2] +QHttpPart imagePart; +imagePart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("image/jpeg")); +imagePart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"image\"")); +imagePart.setRawHeader("Content-ID", "my@content.id"); // add any headers you like via setRawHeader() +QFile *file = new QFile("image.jpg"); +file->open(QIODevice::ReadOnly); +imagePart.setBodyDevice(file); +//! [2] + diff --git a/src/network/doc/snippets/code/src_network_access_qnetworkaccessmanager.cpp b/src/network/doc/snippets/code/src_network_access_qnetworkaccessmanager.cpp new file mode 100644 index 0000000000..ab8fc97d04 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qnetworkaccessmanager.cpp @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkAccessManager *manager = new QNetworkAccessManager(this); +connect(manager, SIGNAL(finished(QNetworkReply*)), + this, SLOT(replyFinished(QNetworkReply*))); + +manager->get(QNetworkRequest(QUrl("http://qt.nokia.com"))); +//! [0] + + +//! [1] +QNetworkRequest request; +request.setUrl(QUrl("http://qt.nokia.com")); +request.setRawHeader("User-Agent", "MyOwnBrowser 1.0"); + +QNetworkReply *reply = manager->get(request); +connect(reply, SIGNAL(readyRead()), this, SLOT(slotReadyRead())); +connect(reply, SIGNAL(error(QNetworkReply::NetworkError)), + this, SLOT(slotError(QNetworkReply::NetworkError))); +connect(reply, SIGNAL(sslErrors(QList<QSslError>)), + this, SLOT(slotSslErrors(QList<QSslError>))); +//! [1] + +//! [2] +QNetworkConfigurationManager manager; +networkAccessManager->setConfiguration(manager.defaultConfiguration()); +//! [2] + +//! [3] +networkAccessManager->setConfiguration(QNetworkConfiguration()); +//! [3] + +//! [4] +networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible); +//! [4] + +//! [5] +networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible); +//! [5] + diff --git a/src/network/doc/snippets/code/src_network_access_qnetworkdiskcache.cpp b/src/network/doc/snippets/code/src_network_access_qnetworkdiskcache.cpp new file mode 100644 index 0000000000..bc272a2223 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qnetworkdiskcache.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkAccessManager *manager = new QNetworkAccessManager(this); +QNetworkDiskCache *diskCache = new QNetworkDiskCache(this); +diskCache->setCacheDirectory("cacheDir"); +manager->setCache(diskCache); +//! [0] + +//! [1] +// do a normal request (preferred from network, as this is the default) +QNetworkRequest request(QUrl(QString("http://qt.nokia.com"))); +manager->get(request); + +// do a request preferred from cache +QNetworkRequest request2(QUrl(QString("http://qt.nokia.com"))); +request2.setAttribute(QNetworkRequest::CacheLoadControlAttribute, QNetworkRequest::PreferCache); +manager->get(request2); +//! [1] + +//! [2] +void replyFinished(QNetworkReply *reply) { + QVariant fromCache = reply->attribute(QNetworkRequest::SourceIsFromCacheAttribute); + qDebug() << "page from cache?" << fromCache.toBool(); +} +//! [2] diff --git a/src/network/doc/snippets/code/src_network_access_qnetworkreply.cpp b/src/network/doc/snippets/code/src_network_access_qnetworkreply.cpp new file mode 100644 index 0000000000..0f1b4c2014 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qnetworkreply.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem")); +QSslError error(QSslError::SelfSignedCertificate, cert.at(0)); +QList<QSslError> expectedSslErrors; +expectedSslErrors.append(error); + +QNetworkReply *reply = manager.get(QNetworkRequest(QUrl("https://server.tld/index.html"))); +reply->ignoreSslErrors(expectedSslErrors); +// here connect signals etc. +//! [0] diff --git a/src/network/doc/snippets/code/src_network_access_qnetworkrequest.cpp b/src/network/doc/snippets/code/src_network_access_qnetworkrequest.cpp new file mode 100644 index 0000000000..bdf696e851 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_access_qnetworkrequest.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +request.setRawHeader("Last-Modified", "Sun, 06 Nov 1994 08:49:37 GMT"); +//! [0] diff --git a/src/network/doc/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp b/src/network/doc/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp new file mode 100644 index 0000000000..2d62d758b7 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkConfigurationManager mgr; +QList<QNetworkConfiguration> activeConfigs = mgr.allConfigurations(QNetworkConfiguration::Active) +if (activeConfigs.count() > 0) + Q_ASSERT(mgr.isOnline()) +else + Q_ASSERT(!mgr.isOnline()) +//! [0] diff --git a/src/network/doc/snippets/code/src_network_kernel_qdnslookup.cpp b/src/network/doc/snippets/code/src_network_kernel_qdnslookup.cpp new file mode 100644 index 0000000000..f2e530ff96 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_kernel_qdnslookup.cpp @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Jeremy Lainé <jeremy.laine@m4x.org> +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyObject::lookupServers() +{ + // Create a DNS lookup. + dns = new QDnsLookup(this); + connect(dns, SIGNAL(finished()), + this, SLOT(handleServers())); + + // Find the XMPP servers for gmail.com + dns->setType(QDnsLookup::SRV); + dns->setName("_xmpp-client._tcp.gmail.com"); + dns->lookup(); +} +//! [0] + + +//! [1] +void MyObject::handleServers() +{ + // Check the lookup succeeded. + if (dns->error() != QDnsLookup::NoError) { + qWarning("DNS lookup failed"); + dns->deleteLater(); + return; + } + + // Handle the results. + foreach (const QDnsServiceRecord &record, dns->serviceRecords()) { + ... + } + dns->deleteLater(); +} +//! [1] diff --git a/src/network/doc/snippets/code/src_network_kernel_qhostaddress.cpp b/src/network/doc/snippets/code/src_network_kernel_qhostaddress.cpp new file mode 100644 index 0000000000..c03054c243 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_kernel_qhostaddress.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +Q_IPV6ADDR addr = hostAddr.toIPv6Address(); +// addr contains 16 unsigned characters + +for (int i = 0; i < 16; ++i) { + // process addr[i] +} +//! [0] diff --git a/src/network/doc/snippets/code/src_network_kernel_qhostinfo.cpp b/src/network/doc/snippets/code/src_network_kernel_qhostinfo.cpp new file mode 100644 index 0000000000..7607841ac5 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_kernel_qhostinfo.cpp @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// To find the IP address of qt.nokia.com +QHostInfo::lookupHost("qt.nokia.com", + this, SLOT(printResults(QHostInfo))); + +// To find the host name for 4.2.2.1 +QHostInfo::lookupHost("4.2.2.1", + this, SLOT(printResults(QHostInfo))); +//! [0] + + +//! [1] +QHostInfo info = QHostInfo::fromName("qt.nokia.com"); +//! [1] + + +//! [2] +QHostInfo::lookupHost("www.kde.org", + this, SLOT(lookedUp(QHostInfo))); +//! [2] + + +//! [3] +void MyWidget::lookedUp(const QHostInfo &host) +{ + if (host.error() != QHostInfo::NoError) { + qDebug() << "Lookup failed:" << host.errorString(); + return; + } + + foreach (const QHostAddress &address, host.addresses()) + qDebug() << "Found address:" << address.toString(); +} +//! [3] + + +//! [4] +QHostInfo::lookupHost("4.2.2.1", + this, SLOT(lookedUp(QHostInfo))); +//! [4] + + +//! [5] +QHostInfo info; +... +if (!info.addresses().isEmpty()) { + QHostAddress address = info.addresses().first(); + // use the first IP address +} +//! [5] diff --git a/src/network/doc/snippets/code/src_network_kernel_qnetworkproxy.cpp b/src/network/doc/snippets/code/src_network_kernel_qnetworkproxy.cpp new file mode 100644 index 0000000000..eadf4f91a5 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_kernel_qnetworkproxy.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkProxy proxy; +proxy.setType(QNetworkProxy::Socks5Proxy); +proxy.setHostName("proxy.example.com"); +proxy.setPort(1080); +proxy.setUser("username"); +proxy.setPassword("password"); +QNetworkProxy::setApplicationProxy(proxy); +//! [0] + + +//! [1] +serverSocket->setProxy(QNetworkProxy::NoProxy); +//! [1] diff --git a/src/network/doc/snippets/code/src_network_socket_qabstractsocket.cpp b/src/network/doc/snippets/code/src_network_socket_qabstractsocket.cpp new file mode 100644 index 0000000000..b419b33c92 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_socket_qabstractsocket.cpp @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +socket->connectToHost("imap", 143); +if (socket->waitForConnected(1000)) + qDebug("Connected!"); +//! [0] + + +//! [1] +socket->disconnectFromHost(); + if (socket->state() == QAbstractSocket::UnconnectedState || + socket->waitForDisconnected(1000)) + qDebug("Disconnected!"); +//! [1] + + +//! [2] + // This slot is connected to QAbstractSocket::readyRead() + void SocketClass::readyReadSlot() + { + while (!socket.atEnd()) { + QByteArray data = socket.read(100); + .... + } + } +//! [2] + + +//! [3] +socket->setProxy(QNetworkProxy::NoProxy); +//! [3] diff --git a/src/network/doc/snippets/code/src_network_socket_qlocalsocket_unix.cpp b/src/network/doc/snippets/code/src_network_socket_qlocalsocket_unix.cpp new file mode 100644 index 0000000000..947e89900a --- /dev/null +++ b/src/network/doc/snippets/code/src_network_socket_qlocalsocket_unix.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +socket->connectToServer("market"); +if (socket->waitForConnected(1000)) + qDebug("Connected!"); +//! [0] + + +//! [1] +socket->disconnectFromServer(); +if (socket->waitForDisconnected(1000)) + qDebug("Disconnected!"); +//! [1] diff --git a/src/network/doc/snippets/code/src_network_socket_qnativesocketengine.cpp b/src/network/doc/snippets/code/src_network_socket_qnativesocketengine.cpp new file mode 100644 index 0000000000..98ac70cc49 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_socket_qnativesocketengine.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNativeSocketEngine socketLayer; +socketLayer.initialize(QAbstractSocket::TcpSocket, QAbstractSocket::IPv4Protocol); +socketLayer.connectToHost(QHostAddress::LocalHost, 22); +// returns false + +socketLayer.waitForWrite(); +socketLayer.connectToHost(QHostAddress::LocalHost, 22); +// returns true +//! [0] + + +//! [1] +QNativeSocketEngine socketLayer; +socketLayer.bind(QHostAddress::Any, 4000); +socketLayer.listen(); +if (socketLayer.waitForRead()) { + int clientSocket = socketLayer.accept(); + // a client is connected +} +//! [1] diff --git a/src/network/doc/snippets/code/src_network_socket_qtcpserver.cpp b/src/network/doc/snippets/code/src_network_socket_qtcpserver.cpp new file mode 100644 index 0000000000..90c4a86836 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_socket_qtcpserver.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +server->setProxy(QNetworkProxy::NoProxy); +//! [0] diff --git a/src/network/doc/snippets/code/src_network_socket_qudpsocket.cpp b/src/network/doc/snippets/code/src_network_socket_qudpsocket.cpp new file mode 100644 index 0000000000..2a90772623 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_socket_qudpsocket.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void Server::initSocket() +{ + udpSocket = new QUdpSocket(this); + udpSocket->bind(QHostAddress::LocalHost, 7755); + + connect(udpSocket, SIGNAL(readyRead()), + this, SLOT(readPendingDatagrams())); +} + +void Server::readPendingDatagrams() +{ + while (udpSocket->hasPendingDatagrams()) { + QByteArray datagram; + datagram.resize(udpSocket->pendingDatagramSize()); + QHostAddress sender; + quint16 senderPort; + + udpSocket->readDatagram(datagram.data(), datagram.size(), + &sender, &senderPort); + + processTheDatagram(datagram); + } +} +//! [0] diff --git a/src/network/doc/snippets/code/src_network_ssl_qsslcertificate.cpp b/src/network/doc/snippets/code/src_network_ssl_qsslcertificate.cpp new file mode 100644 index 0000000000..0538990a3d --- /dev/null +++ b/src/network/doc/snippets/code/src_network_ssl_qsslcertificate.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +foreach (const QSslCertificate &cert, QSslCertificate::fromPath("C:/ssl/certificate.*.pem", QSsl::Pem, + QRegExp::Wildcard)) { + qDebug() << cert.issuerInfo(QSslCertificate::Organization); +} +//! [0] diff --git a/src/network/doc/snippets/code/src_network_ssl_qsslconfiguration.cpp b/src/network/doc/snippets/code/src_network_ssl_qsslconfiguration.cpp new file mode 100644 index 0000000000..a3a08f68d1 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_ssl_qsslconfiguration.cpp @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSslConfiguration config = sslSocket.sslConfiguration(); +config.setProtocol(QSsl::TlsV1_0); +sslSocket.setSslConfiguration(config); +//! [0] diff --git a/src/network/doc/snippets/code/src_network_ssl_qsslsocket.cpp b/src/network/doc/snippets/code/src_network_ssl_qsslsocket.cpp new file mode 100644 index 0000000000..4d8e3668b5 --- /dev/null +++ b/src/network/doc/snippets/code/src_network_ssl_qsslsocket.cpp @@ -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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSslSocket *socket = new QSslSocket(this); +connect(socket, SIGNAL(encrypted()), this, SLOT(ready())); + +socket->connectToHostEncrypted("imap.example.com", 993); +//! [0] + + +//! [1] +void SslServer::incomingConnection(qintptr socketDescriptor) +{ + QSslSocket *serverSocket = new QSslSocket; + if (serverSocket->setSocketDescriptor(socketDescriptor)) { + connect(serverSocket, SIGNAL(encrypted()), this, SLOT(ready())); + serverSocket->startServerEncryption(); + } else { + delete serverSocket; + } +} +//! [1] + + +//! [2] +QSslSocket socket; +socket.connectToHostEncrypted("http.example.com", 443); +if (!socket.waitForEncrypted()) { + qDebug() << socket.errorString(); + return false; +} + +socket.write("GET / HTTP/1.0\r\n\r\n"); +while (socket.waitForReadyRead()) + qDebug() << socket.readAll().data(); +//! [2] + + +//! [3] +QSslSocket socket; +connect(&socket, SIGNAL(encrypted()), receiver, SLOT(socketEncrypted())); + +socket.connectToHostEncrypted("imap", 993); +socket->write("1 CAPABILITY\r\n"); +//! [3] + + +//! [4] +QSslSocket socket; +socket.setCiphers("DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA"); +//! [4] + + +//! [5] +socket->connectToHostEncrypted("imap", 993); +if (socket->waitForEncrypted(1000)) + qDebug("Encrypted!"); +//! [5] + +//! [6] +QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem")); +QSslError error(QSslError::SelfSignedCertificate, cert.at(0)); +QList<QSslError> expectedSslErrors; +expectedSslErrors.append(error); + +QSslSocket socket; +socket.ignoreSslErrors(expectedSslErrors); +socket.connectToHostEncrypted("server.tld", 443); +//! [6] diff --git a/src/network/doc/snippets/network/tcpwait.cpp b/src/network/doc/snippets/network/tcpwait.cpp new file mode 100644 index 0000000000..9ee68e5b13 --- /dev/null +++ b/src/network/doc/snippets/network/tcpwait.cpp @@ -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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QTcpSocket> + +#include "server.h" + +int main(int argv, char **args) +{ + QCoreApplication app(argv, args); + + QTcpSocket socket; + socket.connectToHost("localhost", 1025); + +//! [0] + int numRead = 0, numReadTotal = 0; + char buffer[50]; + + forever { + numRead = socket.read(buffer, 50); + + // do whatever with array + + numReadTotal += numRead; + if (numRead == 0 && !socket.waitForReadyRead()) + break; + } +//! [0] + + return app.exec(); +} diff --git a/src/network/doc/src/bearermanagement.qdoc b/src/network/doc/src/bearermanagement.qdoc new file mode 100644 index 0000000000..91dc32c5a5 --- /dev/null +++ b/src/network/doc/src/bearermanagement.qdoc @@ -0,0 +1,268 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page bearer-management.html + +\title Bearer Management +\ingroup qt-network +\brief An API to control the system's connectivity state. + +Bearer Management controls the connectivity state of the system so that +the user can start or stop interfaces or roam transparently between +access points. + +\tableofcontents + + +\section1 Overview + +The Bearer Management API controls the system's connectivity state. This +incorporates simple information such as whether the device is online and +how many interfaces there are as well as enables the application developer +to start, stop network interfaces and influences other connection specific +details. Depending on the platform's capabilities it may even provide +session management so that a network interface remains up for as long as +clients have a registered interest in them while at the same time +optimizes the interface's uptime. + +This API does not provide support for management of network configurations +themselves. It is up to the platform to provide infrastructure which +enables to user to create, edit or delete network configurations. + +\section2 The API in Detail + +Computer systems manage their network interfaces via a set of configurations. +Each configuration describes a set of parameters which instruct the system +how a particular network interface is started. One of the most simplistic +examples might be an Ethernet configuration that links a network card to a +DHCP server. A more complex example might be a Wireless LAN configuration +which may comprise of hardware details such as the WLAN card address, +WLAN access point details (e.g ESSID, encryption details) and user specific +information (for example username and password). Once the network interface +was configured and started according to the configuration blue print, +multiple applications are free to use this link layer connection/session +for their own socket operations. Note that the QNetworkConfiguration object +only provides limited information about the configuration details themselves. +It's main purpose is to act as a configuration identifier through which link +layer connections can be created, destroyed and monitored. + +QNetworkSession provides two types of use cases. It enables the monitoring of +physical network interfaces and management of network sessions. Network sessions +are a common feature on mobile devices where multiple applications +can request network sessions as they see fit. The system consolidates and tracks +active network sessions for the same network interface by maintaining the link +layer connections until the last session has been closed. The subsequent table +lists the major QNetworkSession functions and how they fit into the session and +hardware management categories: + +\table 60% +\header \li Interface management \li Session management +\row \li QNetworkSession::stop() \li QNetworkSession::open() +\row \li QNetworkSession::interface() \li QNetworkSession::close() +\row \li QNetworkSession::state() \li QNetworkSession::isOpen() +\row \li QNetworkSession::bytesWritten() \li QNetworkSession::migrate() +\row \li QNetworkSession::bytesReceived() \li QNetworkSession::ignore() +\row \li QNetworkSession::activeTime() \li QNetworkSession::accept() +\row \li QNetworkSession::stateChanged() \li QNetworkSession::reject() +\row \li \li QNetworkSession::opened() +\row \li \li QNetworkSession::closed() +\endtable + +The state of the session represents the state of the underlying access point +whereas the session's openness implies the networking/connectivity state available +to the current process. + +Possible use cases for interface management are network management related +applications which intend to monitor the connectivity state but do not engage +in network communication themselves. Any application wanting to open a socket +to a remote address will typically use session management related functionality. + +\section3 Service networks + +Some mobile platforms use the concept of grouped access points (also +called SNAP or Service Network Access Point). In principle multiple +configurations are grouped together and possibly even prioritized when +compared to each other. This is useful for use cases where all +configurations serve a similar purpose or context. A common context could +be that they provide access to the public Internet or possibly only to the +office Intranet. By providing a pool of configurations the system can make +a decision based on given priorities which usually map to factors such as +speed, availability and cost. Furthermore the system can automatically +roam from one access point to the next one while ensuring minimal impact on +the user experience. + +The \l{QNetworkConfiguration::Type} flag specifies to what category a +configuration belongs. The \l{QNetworkConfiguration::InternetAccessPoint} +type is the most common example. It represents a configuration that can be +used to create a session. The above mentioned grouping behavior is provided +by \l {QNetworkConfiguration::ServiceNetwork} configurations. Service +networks are place holders until such time when the user attempts to +\l {QNetworkSession::open()}{open()} a new session. At that point in time +the system determines which of the configurations \l{QNetworkConfiguration::children()} +is best to use. The selection algorithm is provided by the platform and is usually managed +by network settings applications. A service network can only have one level of indirection +which implies children can only be of type \l {QNetworkConfiguration::InternetAccessPoint}. + +Most systems allow the user to define the systems default configuration. +Usually the default behavior is either a service network, a particular +Internet access point or the user instructs the platform to ask the user +once an application requests the network. User interaction is generally +implemented by some sort of system dialog which shows up at the appropriate +point in time. The application does not have to handle the user input. This +API provides the \l QNetworkConfigurationManager::defaultConfiguration() +call which serves a similar purpose. The subsequent code snippet provides +a quick way how an application can quickly create a new network session +without (or only minimal) user interaction: + +\code + // Set Internet Access Point + QNetworkConfigurationManager manager; + const bool canStartIAP = (manager.capabilities() + & QNetworkConfigurationManager::CanStartAndStopInterfaces); + // Is there default access point, use it + QNetworkConfiguration cfg = manager.defaultConfiguration(); + if (!cfg.isValid() || (!canStartIAP && cfg.state() != QNetworkConfiguration::Active)) { + QMessageBox::information(this, tr("Network"), tr( + "No Access Point found.")); + return; + } + + session = new QNetworkSession(cfg, this); + session->open(); + session->waitForOpened(-1); +\endcode + +To accommodate the "Ask user" use case the default configuration can be of +type QNetworkConfiguration::UserChoice. A user choice configuration is +resolved as part of the \l {QNetworkSession::open()} call. Note that a +\l{QNetworkConfiguration::UserChoice}{UserChoice} configuration is only +ever returned via \l {QNetworkConfigurationManager::defaultConfiguration()} +and not \l QNetworkConfigurationManager::allConfigurations(). + +On systems which do not maintain a list of +\l {QNetworkConfigurationManager::defaultConfiguration()}{defaultConfiguration()} +an invalid configuration is returned. A possible workaround could be to +implement a custom dialog which is populated based on what +\l QNetworkConfigurationManager::allConfigurations() returns. + +\section3 Managing network sessions + +A QNetworkSession object separates a \l {QNetworkSession::state()}{state()} +and an \l{QNetworkSession::isOpen()}{isOpen()} condition. + +The state() attribute enables developers to detect whether the system +currently maintains a global network session for the given +QNetworkConfiguration. If \l {QNetworkSession::isOpen()}{isOpen()} +returns true the QNetworkSession instance at hand was at least one of the +entities requesting the global network session. This distinction is +required to support the notion of session registrations. For as long as +there are one or more open QNetworkSession instances the underlying +network interface is not shut down. Therefore the session +\l{QNetworkSession::state()}{state()} can be used to monitor the state of +network interfaces. + +An open session is created by calling \l {QNetworkSession::open()} and +closed via \l{QNetworkSession::close()}, respectively. If the session +is \l{QNetworkSession::Disconnected}{disconnected} at the time of the +\l{QNetworkSession::open()}{open()} call the underlying interface is started; +otherwise only the reference counter against the global session is +incremented. The opposite behavior can be observed when using +\l{QNetworkSession::close()}{close()}. + +In some use cases it may be necessary to turn the interface off despite of +open sessions. This can be achieved by calling +\l{QNetworkSession::stop()}{stop()}. An example use case could be a +network manager type of application allowing the user to control the +overall state of the devices connectivity. + +Global (inter-process) session support is platform dependent and can be +detected via \l {QNetworkConfigurationManager::SystemSessionSupport}. +If the system does not support global session calling +\l{QNetworkSession::close()}{close()} never stops the interface. + +\section3 Roaming + +Roaming is the process of reconnecting a device from one network to another +while minimizing the impact on the application. The system notifies the application +about link layer changes so that the required preparation can be taken. +The most common reaction would be to reinitialize sockets and to renegotiate +stateful connections with other parties. In the most extreme cases applications +may even prevent the roaming altogether. + +Roaming is initiated when the system determines that a more appropriate access point +becomes available to the user. In general such a decision is based on cost, network speed +or network type (access to certain private networks may only be provided via certain access points). +Almost all devices providing roaming support have some form of global configuration application +enabling the user to define such groups of access points (service networks) and priorities. + +This API supports two types of roaming. Application level roaming (ALR) +provides the most control over the process. Applications will be notified about upcoming +link layer changes and get the opportunity to test the new access point. Eventually they can +reject or accept the link layer change. The second form of roaming is referred to as Forced Roaming. +The system simply changes the link layer without consulting the application. It is up to +the application to detect that some of its internal socket may have become invalid. As a consequence +it has to reinitialize those sockets and reestablish the previous user session without +any interruption. Forced roaming has the advantage that applications don't have to +manage the entire roaming process by themselves. + +QNetworkSession is the central class for managing roaming related issues. + +\section3 Platform capabilities + +Some API features are not available on all platforms. The +\l QNetworkConfigurationManager::Capability should be used to detect +platform features at runtime. The following table lists the various +platform APIs being used by this API. This may assist in the process of +determining the feature support: + +\table + \header + \li Platform + \li Backend capabilities + \row + \li Linux\unicode{0xAE} + \li Linux uses the \l {http://projects.gnome.org/NetworkManager}{NetworkManager} + and \l {http://connman.net/}{ConnMan} / \l {http://ofono.org/}{oFono} APIs + which support interface notifications and starting and stopping of network + interfaces. + \row + \li Windows\unicode{0xAE} XP + \li This platform supports interface notifications without active polling. + \row + \li Windows XP SP2+Hotfixes, Windows XP SP3, Windows Vista, Windows 7 + \li In addition to standard Windows XP wifi access point monitoring has been improved which includes the ability to start and stop wifi interfaces. This requires Windows to manage the wifi interfaces. + \row + \li Mac OS\unicode{0xAE} + \li This platform has full support by way of CoreWLAN offered in Mac OS 10.6. Previous + versions of Mac OS - 10.5 and 10.4 have limited support. + \row + \li All other platforms (*nix, Windows Mobile) + \li This backend is the fallback for all platforms supports network interface notifications via active polling only. +\endtable + +*/ diff --git a/src/network/doc/src/network-programming.qdoc b/src/network/doc/src/network-programming.qdoc new file mode 100644 index 0000000000..0701b04f6f --- /dev/null +++ b/src/network/doc/src/network-programming.qdoc @@ -0,0 +1,291 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group network + \title Network Programming API + \brief Classes for Network Programming + + \ingroup groups +*/ + +/*! + \page network-programming.html + \title Network Programming + \ingroup qt-network + \brief An Introduction to Network Programming with Qt + + The QtNetwork module offers classes that allow you to write TCP/IP clients + and servers. It offers lower-level classes such as QTcpSocket, + QTcpServer and QUdpSocket that represent low level network concepts, + and high level classes such as QNetworkRequest, QNetworkReply and + QNetworkAccessManager to perform network operations using common protocols. + It also offers classes such as QNetworkConfiguration, + QNetworkConfigurationManager and QNetworkSession that implement bearer + management. + + \tableofcontents + + \section1 Qt's Classes for Network Programming + + The following classes provide support for network programming in Qt. + + \annotatedlist network + + \section1 High Level Network Operations for HTTP and FTP + + The Network Access API is a collection of classes for performing + common network operations. The API provides an abstraction layer + over the specific operations and protocols used (for example, + getting and posting data over HTTP), and only exposes classes, + functions, and signals for general or high level concepts. + + Network requests are represented by the QNetworkRequest class, + which also acts as a general container for information associated + with a request, such as any header information and the encryption + used. The URL specified when a request object is constructed + determines the protocol used for a request. + Currently HTTP, FTP and local file URLs are supported for uploading + and downloading. + + The coordination of network operations is performed by the + QNetworkAccessManager class. Once a request has been created, + this class is used to dispatch it and emit signals to report on + its progress. The manager also coordinates the use of + \l{QNetworkCookieJar}{cookies} to store data on the client, + authentication requests, and the use of proxies. + + Replies to network requests are represented by the QNetworkReply + class; these are created by QNetworkAccessManager when a request + is dispatched. The signals provided by QNetworkReply can be used + to monitor each reply individually, or developers may choose to + use the manager's signals for this purpose instead and discard + references to replies. Since QNetworkReply is a subclass of + QIODevice, replies can be handled synchronously or asynchronously; + i.e., as blocking or non-blocking operations. + + Each application or library can create one or more instances of + QNetworkAccessManager to handle network communication. + + \section1 Using TCP with QTcpSocket and QTcpServer + + TCP (Transmission Control Protocol) is a low-level network + protocol used by most Internet protocols, including HTTP and FTP, + for data transfer. It is a reliable, stream-oriented, + connection-oriented transport protocol. It is particularly well + suited to the continuous transmission of data. + + \image tcpstream.png A TCP Stream + + The QTcpSocket class provides an interface for TCP. You can use + QTcpSocket to implement standard network protocols such as POP3, + SMTP, and NNTP, as well as custom protocols. + + A TCP connection must be established to a remote host and port + before any data transfer can begin. Once the connection has been + established, the IP address and port of the peer are available + through QTcpSocket::peerAddress() and QTcpSocket::peerPort(). At + any time, the peer can close the connection, and data transfer + will then stop immediately. + + QTcpSocket works asynchronously and emits signals to report status + changes and errors, just like QNetworkAccessManager. It + relies on the event loop to detect incoming data and to + automatically flush outgoing data. You can write data to the + socket using QTcpSocket::write(), and read data using + QTcpSocket::read(). QTcpSocket represents two independent streams + of data: one for reading and one for writing. + + Since QTcpSocket inherits QIODevice, you can use it with + QTextStream and QDataStream. When reading from a QTcpSocket, you + must make sure that enough data is available by calling + QTcpSocket::bytesAvailable() beforehand. + + If you need to handle incoming TCP connections (e.g., in a server + application), use the QTcpServer class. Call QTcpServer::listen() + to set up the server, and connect to the + QTcpServer::newConnection() signal, which is emitted once for + every client that connects. In your slot, call + QTcpServer::nextPendingConnection() to accept the connection and + use the returned QTcpSocket to communicate with the client. + + Although most of its functions work asynchronously, it's possible + to use QTcpSocket synchronously (i.e., blocking). To get blocking + behavior, call QTcpSocket's waitFor...() functions; these suspend + the calling thread until a signal has been emitted. For example, + after calling the non-blocking QTcpSocket::connectToHost() + function, call QTcpSocket::waitForConnected() to block the thread + until the \l{QTcpSocket::connected()}{connected()} signal has + been emitted. + + Synchronous sockets often lead to code with a simpler flow of + control. The main disadvantage of the waitFor...() approach is + that events won't be processed while a waitFor...() function is + blocking. If used in the GUI thread, this might freeze the + application's user interface. For this reason, we recommend that + you use synchronous sockets only in non-GUI threads. When used + synchronously, QTcpSocket doesn't require an event loop. + + The \l{network/fortuneclient}{Fortune Client} and + \l{network/fortuneserver}{Fortune Server} examples show how to use + QTcpSocket and QTcpServer to write TCP client-server + applications. See also \l{network/blockingfortuneclient}{Blocking + Fortune Client} for an example on how to use a synchronous + QTcpSocket in a separate thread (without using an event loop), + and \l{network/threadedfortuneserver}{Threaded Fortune Server} + for an example of a multithreaded TCP server with one thread per + active client. + + \section1 Using UDP with QUdpSocket + + UDP (User Datagram Protocol) is a lightweight, unreliable, + datagram-oriented, connectionless protocol. It can be used when + reliability isn't important. For example, a server that reports + the time of day could choose UDP. If a datagram with the time of + day is lost, the client can simply make another request. + + \image udppackets.png UDP Packets + + The QUdpSocket class allows you to send and receive UDP + datagrams. It inherits QAbstractSocket, and it therefore shares + most of QTcpSocket's interface. The main difference is that + QUdpSocket transfers data as datagrams instead of as a continuous + stream of data. In short, a datagram is a data packet of limited + size (normally smaller than 512 bytes), containing the IP address + and port of the datagram's sender and receiver in addition to the + data being transferred. + + QUdpSocket supports IPv4 broadcasting. Broadcasting is often used + to implement network discovery protocols, such as finding which + host on the network has the most free hard disk space. One host + broadcasts a datagram to the network that all other hosts + receive. Each host that receives a request then sends a reply + back to the sender with its current amount of free disk space. + The originator waits until it has received replies from all + hosts, and can then choose the server with most free space to + store data. To broadcast a datagram, simply send it to the + special address QHostAddress::Broadcast (255.255.255.255), or + to your local network's broadcast address. + + QUdpSocket::bind() prepares the socket for accepting incoming + datagrams, much like QTcpServer::listen() for TCP servers. + Whenever one or more datagrams arrive, QUdpSocket emits the + \l{QUdpSocket::readyRead()}{readyRead()} signal. Call + QUdpSocket::readDatagram() to read the datagram. + + The \l{network/broadcastsender}{Broadcast Sender} and + \l{network/broadcastreceiver}{Broadcast Receiver} examples show how to + write a UDP sender and a UDP receiver using Qt. + + QUdpSocket also supports multicasting. The + \l{network/multicastsender}{Multicast Sender} and + \l{network/multicastreceiver}{Multicast Receiver} examples show how to use + write UDP multicast clients. + + \section1 Resolving Host Names using QHostInfo + + Before establishing a network connection, QTcpSocket and + QUdpSocket perform a name lookup, translating the host name + you're connecting to into an IP address. This operation is + usually performed using the DNS (Domain Name Service) protocol. + + QHostInfo provides a static function that lets you perform such a + lookup yourself. By calling QHostInfo::lookupHost() with a host + name, a QObject pointer, and a slot signature, QHostInfo will + perform the name lookup and invoke the given slot when the + results are ready. The actual lookup is done in a separate + thread, making use of the operating system's own methods for + performing name lookups. + + QHostInfo also provides a static function called + QHostInfo::fromName() that takes the host name as argument and + returns the results. In this case, the name lookup is performed + in the same thread as the caller. This overload is useful for + non-GUI applications or for doing name lookups in a separate, + non-GUI thread. (Calling this function in a GUI thread may cause + your user interface to freeze while the function blocks as + it performs the lookup.) + + \section1 Support for Network Proxies + + Network communication with Qt can be performed through proxies, + which direct or filter network traffic between local and remote + connections. + + Individual proxies are represented by the QNetworkProxy class, + which is used to describe and configure the connection to a proxy. + Proxy types which operate on different levels of network communication + are supported, with SOCKS 5 support allowing proxying of network + traffic at a low level, and HTTP and FTP proxying working at the + protocol level. See QNetworkProxy::ProxyType for more information. + + Proxying can be enabled on a per-socket basis or for all network + communication in an application. A newly opened socket can be + made to use a proxy by calling its QAbstractSocket::setProxy() + function before it is connected. Application-wide proxying can + be enabled for all subsequent socket connections through the use + of the QNetworkProxy::setApplicationProxy() function. + + Proxy factories are used to create policies for proxy use. + QNetworkProxyFactory supplies proxies based on queries for specific + proxy types. The queries themselves are encoded in QNetworkProxyQuery + objects which enable proxies to be selected based on key criteria, + such as the purpose of the proxy (TCP, UDP, TCP server, URL request), + local port, remote host and port, and the protocol in use (HTTP, FTP, + etc.). + + QNetworkProxyFactory::proxyForQuery() is used to query the factory + directly. An application-wide policy for proxying can be implemented + by passing a factory to QNetworkProxyFactory::setApplicationProxyFactory() + and a custom proxying policy can be created by subclassing + QNetworkProxyFactory; see the class documentation for details. + + \section1 Bearer Management Support + + Bearer Management controls the connectivity state of the device such that + the application can start or stop network interfaces and roam + transparently between access points. + + The QNetworkConfigurationManager class manages the list of network + configurations known to the device. A network configuration describes the + set of parameters used to start a network interface and is represented by + the QNetworkConfiguration class. + + A network interface is started by openning a QNetworkSession based on a + given network configuration. In most situations creating a network session + based on the platform specified default network configuration is + appropriate. The default network configuration is returned by the + QNetworkConfigurationManager::defaultConfiguration() function. + + On some platforms it is a platform requirement that the application open a + network session before any network operations can be performed. This can be + tested by the presents of the + QNetworkConfigurationManager::NetworkSessionRequired flag in the value + returned by the QNetworkConfigurationManager::capabilities() function. + + \sa {Bearer Management} +*/ diff --git a/src/network/doc/src/qtnetwork.qdoc b/src/network/doc/src/qtnetwork.qdoc new file mode 100644 index 0000000000..092880ef59 --- /dev/null +++ b/src/network/doc/src/qtnetwork.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \module QtNetwork + \title QtNetwork Module + \ingroup modules + + \brief The QtNetwork module provides classes to make network programming + easier and portable. + + To include the definitions of the module's classes, use the + following directive: + + \snippet code/doc_src_qtnetwork.cpp 1 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet code/doc_src_qtnetwork.pro 0 +*/ diff --git a/src/network/doc/src/ssl.qdoc b/src/network/doc/src/ssl.qdoc new file mode 100644 index 0000000000..21828d7af9 --- /dev/null +++ b/src/network/doc/src/ssl.qdoc @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page ssl.html + \title Secure Sockets Layer (SSL) Classes + \brief Classes for secure communication over network sockets. + \ingroup qt-network + + \keyword SSL + + The classes below provide support for secure network communication using + the Secure Sockets Layer (SSL) protocol, using the \l{OpenSSL Toolkit} to + perform encryption and protocol handling. + + See the \l{General Qt Requirements} page for information about the + versions of OpenSSL that are known to work with Qt. + + \section1 Enabling and Disabling SSL Support + + When building Qt from source, the configuration system checks for the presence + of the \c{openssl/opensslv.h} header provided by source or developer packages + of OpenSSL. + + By default, an SSL-enabled Qt library dynamically loads any installed OpenSSL + library at run-time. However, it is possible to link against the library at + compile-time by configuring Qt with the \c{-openssl-linked} option. + + When building a version of Qt linked against OpenSSL, the build system will + attempt to link with libssl and libcrypt libraries located in the default + location on the developer's system. This location is configurable: + set the \c OPENSSL_LIBS environment variable to contain the linker options + required to link Qt against the installed library. For example, on a Unix/Linux + system: + + \code + ./configure -openssl-linked OPENSSL_LIBS='-L/opt/ssl/lib -lssl -lcrypto' + \endcode + + To disable SSL support in a Qt build, configure Qt with the \c{-no-openssl} + option. + + \section1 Licensing Information + + \note Due to import and export restrictions in some parts of the world, we + are unable to supply the OpenSSL Toolkit with Qt packages. Developers wishing + to use SSL communication in their deployed applications should either ensure + that their users have the appropriate libraries installed, or they should + consult a suitably qualified legal professional to ensure that applications + using code from the OpenSSL project are correctly certified for import + and export in relevant regions of the world. + + When the QtNetwork module is built with SSL support, the library is linked + against OpenSSL in a way that requires OpenSSL license compliance. +*/ diff --git a/src/network/kernel/qdnslookup.cpp b/src/network/kernel/qdnslookup.cpp index 7a1d4e45de..a826422978 100644 --- a/src/network/kernel/qdnslookup.cpp +++ b/src/network/kernel/qdnslookup.cpp @@ -171,11 +171,11 @@ static void qt_qdnsservicerecord_sort(QList<QDnsServiceRecord> &records) For example, you can determine which servers an XMPP chat client should connect to for a given domain with: - \snippet doc/src/snippets/code/src_network_kernel_qdnslookup.cpp 0 + \snippet code/src_network_kernel_qdnslookup.cpp 0 Once the request finishes you can handle the results with: - \snippet doc/src/snippets/code/src_network_kernel_qdnslookup.cpp 1 + \snippet code/src_network_kernel_qdnslookup.cpp 1 \note If you simply want to find the IP address(es) associated with a host name, or the host name associated with an IP address you should use diff --git a/src/network/kernel/qhostaddress.cpp b/src/network/kernel/qhostaddress.cpp index 56473e2982..3ca0f84c39 100644 --- a/src/network/kernel/qhostaddress.cpp +++ b/src/network/kernel/qhostaddress.cpp @@ -644,7 +644,7 @@ QAbstractSocket::NetworkLayerProtocol QHostAddress::protocol() const Returns the IPv6 address as a Q_IPV6ADDR structure. The structure consists of 16 unsigned characters. - \snippet doc/src/snippets/code/src_network_kernel_qhostaddress.cpp 0 + \snippet code/src_network_kernel_qhostaddress.cpp 0 This value is valid if the protocol() is \l{QAbstractSocket::}{IPv6Protocol}. diff --git a/src/network/kernel/qhostinfo.cpp b/src/network/kernel/qhostinfo.cpp index 085f2f6651..32cf90145c 100644 --- a/src/network/kernel/qhostinfo.cpp +++ b/src/network/kernel/qhostinfo.cpp @@ -83,7 +83,7 @@ Q_GLOBAL_STATIC(QHostInfoLookupManager, theHostInfoLookupManager) Example: - \snippet doc/src/snippets/code/src_network_kernel_qhostinfo.cpp 0 + \snippet code/src_network_kernel_qhostinfo.cpp 0 The slot is invoked when the results are ready. The results are @@ -97,7 +97,7 @@ Q_GLOBAL_STATIC(QHostInfoLookupManager, theHostInfoLookupManager) If you want a blocking lookup, use the QHostInfo::fromName() function: - \snippet doc/src/snippets/code/src_network_kernel_qhostinfo.cpp 1 + \snippet code/src_network_kernel_qhostinfo.cpp 1 QHostInfo supports Internationalized Domain Names (IDNs) through the IDNA and Punycode standards. @@ -126,12 +126,12 @@ static QBasicAtomicInt theIdCounter = Q_BASIC_ATOMIC_INITIALIZER(1); The lookup is performed by a single function call, for example: - \snippet doc/src/snippets/code/src_network_kernel_qhostinfo.cpp 2 + \snippet code/src_network_kernel_qhostinfo.cpp 2 The implementation of the slot prints basic information about the addresses returned by the lookup, or reports an error if it failed: - \snippet doc/src/snippets/code/src_network_kernel_qhostinfo.cpp 3 + \snippet code/src_network_kernel_qhostinfo.cpp 3 If you pass a literal IP address to \a name instead of a host name, QHostInfo will search for the domain name for the IP (i.e., QHostInfo will @@ -139,7 +139,7 @@ static QBasicAtomicInt theIdCounter = Q_BASIC_ATOMIC_INITIALIZER(1); contain both the resolved domain name and IP addresses for the host name. Example: - \snippet doc/src/snippets/code/src_network_kernel_qhostinfo.cpp 4 + \snippet code/src_network_kernel_qhostinfo.cpp 4 \note There is no guarantee on the order the signals will be emitted if you start multiple requests with lookupHost(). @@ -311,7 +311,7 @@ QHostInfo::~QHostInfo() Example: - \snippet doc/src/snippets/code/src_network_kernel_qhostinfo.cpp 5 + \snippet code/src_network_kernel_qhostinfo.cpp 5 \sa hostName(), error() */ diff --git a/src/network/kernel/qnetworkproxy.cpp b/src/network/kernel/qnetworkproxy.cpp index 6c1ee0ef42..50bf670e7e 100644 --- a/src/network/kernel/qnetworkproxy.cpp +++ b/src/network/kernel/qnetworkproxy.cpp @@ -59,14 +59,14 @@ network-enabled applications that you have written should automatically support network proxy using the following code. - \snippet doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp 0 + \snippet code/src_network_kernel_qnetworkproxy.cpp 0 An alternative to setting an application wide proxy is to specify the proxy for individual sockets using QAbstractSocket::setProxy() and QTcpServer::setProxy(). In this way, it is possible to disable the use of a proxy for specific sockets using the following code: - \snippet doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp 1 + \snippet code/src_network_kernel_qnetworkproxy.cpp 1 Network proxy is not used if the address used in \l {QAbstractSocket::connectToHost()}{connectToHost()}, \l @@ -800,7 +800,7 @@ QList<QByteArray> QNetworkProxy::rawHeaderList() const the corresponding "cooked" header will be set as well. For example: - \snippet doc/src/snippets/code/src_network_access_qnetworkrequest.cpp 0 + \snippet code/src_network_access_qnetworkrequest.cpp 0 will also set the known header LastModifiedHeader to be the QDateTime object of the parsed date. diff --git a/src/network/network.pro b/src/network/network.pro index a6597338f5..3e1bc6d4e5 100644 --- a/src/network/network.pro +++ b/src/network/network.pro @@ -24,9 +24,11 @@ load(qt_module_config) HEADERS += $$QT_SOURCE_TREE/src/network/qtnetworkversion.h +QMAKE_DOCS = $$PWD/doc/qtnetwork.qdocconf +QMAKE_DOCS_INDEX = ../../doc + include(access/access.pri) include(bearer/bearer.pri) -include(doc/doc.pri) include(kernel/kernel.pri) include(socket/socket.pri) include(ssl/ssl.pri) diff --git a/src/network/socket/qabstractsocket.cpp b/src/network/socket/qabstractsocket.cpp index 9d95d3a70e..9a974c1326 100644 --- a/src/network/socket/qabstractsocket.cpp +++ b/src/network/socket/qabstractsocket.cpp @@ -142,7 +142,7 @@ We show an example: - \snippet doc/src/snippets/network/tcpwait.cpp 0 + \snippet network/tcpwait.cpp 0 If \l{QIODevice::}{waitForReadyRead()} returns false, the connection has been closed or an error has occurred. @@ -1937,7 +1937,7 @@ static int qt_timeout_value(int msecs, int elapsed) The following example waits up to one second for a connection to be established: - \snippet doc/src/snippets/code/src_network_socket_qabstractsocket.cpp 0 + \snippet code/src_network_socket_qabstractsocket.cpp 0 If msecs is -1, this function will not time out. @@ -2182,7 +2182,7 @@ bool QAbstractSocket::waitForBytesWritten(int msecs) The following example waits up to one second for a connection to be closed: - \snippet doc/src/snippets/code/src_network_socket_qabstractsocket.cpp 1 + \snippet code/src_network_socket_qabstractsocket.cpp 1 If msecs is -1, this function will not time out. @@ -2285,7 +2285,7 @@ bool QAbstractSocket::isSequential() const This function is most commonly used when reading data from the socket in a loop. For example: - \snippet doc/src/snippets/code/src_network_socket_qabstractsocket.cpp 2 + \snippet code/src_network_socket_qabstractsocket.cpp 2 \sa bytesAvailable(), readyRead() */ @@ -2873,7 +2873,7 @@ void QAbstractSocket::setSocketError(SocketError socketError) To disable the use of a proxy for this socket, use the QNetworkProxy::NoProxy proxy type: - \snippet doc/src/snippets/code/src_network_socket_qabstractsocket.cpp 3 + \snippet code/src_network_socket_qabstractsocket.cpp 3 The default value for the proxy is QNetworkProxy::DefaultProxy, which means the socket will use the application settings: if a diff --git a/src/network/socket/qlocalsocket.cpp b/src/network/socket/qlocalsocket.cpp index ced7bba09b..9947f3d16e 100644 --- a/src/network/socket/qlocalsocket.cpp +++ b/src/network/socket/qlocalsocket.cpp @@ -255,7 +255,7 @@ QT_BEGIN_NAMESPACE The following example waits up to one second for a connection to be established: - \snippet doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp 0 + \snippet code/src_network_socket_qlocalsocket_unix.cpp 0 If \a msecs is -1, this function will not time out. @@ -274,7 +274,7 @@ QT_BEGIN_NAMESPACE The following example waits up to one second for a connection to be closed: - \snippet doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp 1 + \snippet code/src_network_socket_qlocalsocket_unix.cpp 1 If \a msecs is -1, this function will not time out. diff --git a/src/network/socket/qnativesocketengine.cpp b/src/network/socket/qnativesocketengine.cpp index 8fac3613c0..f2e2f692ac 100644 --- a/src/network/socket/qnativesocketengine.cpp +++ b/src/network/socket/qnativesocketengine.cpp @@ -494,7 +494,7 @@ qintptr QNativeSocketEngine::socketDescriptor() const waitForWrite(). Example: - \snippet doc/src/snippets/code/src_network_socket_qnativesocketengine.cpp 0 + \snippet code/src_network_socket_qnativesocketengine.cpp 0 Otherwise, error() should be called to determine the cause of the error. @@ -590,7 +590,7 @@ bool QNativeSocketEngine::bind(const QHostAddress &address, quint16 port) the blocking function waitForRead(). Example: - \snippet doc/src/snippets/code/src_network_socket_qnativesocketengine.cpp 1 + \snippet code/src_network_socket_qnativesocketengine.cpp 1 \sa bind(), accept() */ diff --git a/src/network/socket/qtcpserver.cpp b/src/network/socket/qtcpserver.cpp index 42f0056524..9cca943189 100644 --- a/src/network/socket/qtcpserver.cpp +++ b/src/network/socket/qtcpserver.cpp @@ -654,7 +654,7 @@ QString QTcpServer::errorString() const To disable the use of a proxy for this socket, use the QNetworkProxy::NoProxy proxy type: - \snippet doc/src/snippets/code/src_network_socket_qtcpserver.cpp 0 + \snippet code/src_network_socket_qtcpserver.cpp 0 \sa proxy(), QNetworkProxy */ diff --git a/src/network/socket/qudpsocket.cpp b/src/network/socket/qudpsocket.cpp index 23c1956ec5..8e3c427d45 100644 --- a/src/network/socket/qudpsocket.cpp +++ b/src/network/socket/qudpsocket.cpp @@ -75,7 +75,7 @@ Example: - \snippet doc/src/snippets/code/src_network_socket_qudpsocket.cpp 0 + \snippet code/src_network_socket_qudpsocket.cpp 0 QUdpSocket also supports UDP multicast. Use joinMulticastGroup() and leaveMulticastGroup() to control group membership, and diff --git a/src/network/ssl/qsslcertificate.cpp b/src/network/ssl/qsslcertificate.cpp index 1fc84cbec1..ba07e7ef06 100644 --- a/src/network/ssl/qsslcertificate.cpp +++ b/src/network/ssl/qsslcertificate.cpp @@ -834,7 +834,7 @@ QByteArray QSslCertificate::toText() const Example: - \snippet doc/src/snippets/code/src_network_ssl_qsslcertificate.cpp 0 + \snippet code/src_network_ssl_qsslcertificate.cpp 0 \sa fromData() */ diff --git a/src/network/ssl/qsslconfiguration.cpp b/src/network/ssl/qsslconfiguration.cpp index ec49c0f56e..bdd10e7834 100644 --- a/src/network/ssl/qsslconfiguration.cpp +++ b/src/network/ssl/qsslconfiguration.cpp @@ -102,7 +102,7 @@ const QSsl::SslOptions QSslConfigurationPrivate::defaultSslOptions = QSsl::SslOp achieve that. The following example illustrates how to change the protocol to TLSv1_0 in a QSslSocket object: - \snippet doc/src/snippets/code/src_network_ssl_qsslconfiguration.cpp 0 + \snippet code/src_network_ssl_qsslconfiguration.cpp 0 \sa QSsl::SslProtocol, QSslCertificate, QSslCipher, QSslKey QSslSocket, QNetworkAccessManager, diff --git a/src/network/ssl/qsslsocket.cpp b/src/network/ssl/qsslsocket.cpp index a041a2aaf1..936f46d95f 100644 --- a/src/network/ssl/qsslsocket.cpp +++ b/src/network/ssl/qsslsocket.cpp @@ -71,7 +71,7 @@ This method starts an immediate SSL handshake once the connection has been established. - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 0 + \snippet code/src_network_ssl_qsslsocket.cpp 0 As with a plain QTcpSocket, QSslSocket enters the HostLookupState, ConnectingState, and finally the ConnectedState, if the connection @@ -94,7 +94,7 @@ the existing one passed in. It then initiates the SSL handshake by calling startServerEncryption(). - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 1 + \snippet code/src_network_ssl_qsslsocket.cpp 1 If an error occurs, QSslSocket emits the sslErrors() signal. In this case, if no action is taken to ignore the error(s), the connection @@ -122,7 +122,7 @@ waitForEncrypted(), which will block the calling thread until an encrypted connection has been established. - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 2 + \snippet code/src_network_ssl_qsslsocket.cpp 2 QSslSocket provides an extensive, easy-to-use API for handling cryptographic ciphers, private keys, and local, peer, and @@ -397,7 +397,7 @@ void QSslSocket::resume() If the SSL handshake is successful, QSslSocket emits encrypted(). - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 3 + \snippet code/src_network_ssl_qsslsocket.cpp 3 \b{Note:} The example above shows that text can be written to the socket immediately after requesting the encrypted connection, @@ -1149,7 +1149,7 @@ void QSslSocket::setCiphers(const QList<QSslCipher> &ciphers) is a colon-separated list of cipher suite names. The ciphers are listed in order of preference, starting with the most preferred cipher. For example: - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 4 + \snippet code/src_network_ssl_qsslsocket.cpp 4 Each cipher name in \a ciphers must be the name of a cipher in the list returned by supportedCiphers(). Restricting the cipher suite @@ -1438,7 +1438,7 @@ bool QSslSocket::waitForConnected(int msecs) The following example waits up to one second for the socket to be encrypted: - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 5 + \snippet code/src_network_ssl_qsslsocket.cpp 5 If msecs is -1, this function will not time out. @@ -1736,7 +1736,7 @@ void QSslSocket::ignoreSslErrors() If, for instance, you want to connect to a server that uses a self-signed certificate, consider the following snippet: - \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 6 + \snippet code/src_network_ssl_qsslsocket.cpp 6 Multiple calls to this function will replace the list of errors that were passed in previous calls. |
