From cd621c201ca637385c6e3409d5c84ecec5fb5418 Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Fri, 16 Sep 2011 14:14:43 +0200 Subject: Move the module qdoc files from qtdoc and split up doc/src. Change-Id: I7d992889379d78e07a0b7023facebd7421cf6d22 Reviewed-on: http://codereview.qt-project.org/5092 Reviewed-by: Qt Sanity Bot Reviewed-by: Jerome Pasion --- .../files-and-resources/datastreamformat.qdoc | 361 +++++++++++++++++++++ doc/src/network/files-and-resources/resources.qdoc | 214 ++++++++++++ .../network-programming/bearermanagement.qdoc | 271 ++++++++++++++++ doc/src/network/network-programming/qtnetwork.qdoc | 350 ++++++++++++++++++++ doc/src/network/network-programming/ssl.qdoc | 79 +++++ doc/src/network/qtnetwork.qdoc | 18 + 6 files changed, 1293 insertions(+) create mode 100644 doc/src/network/files-and-resources/datastreamformat.qdoc create mode 100644 doc/src/network/files-and-resources/resources.qdoc create mode 100644 doc/src/network/network-programming/bearermanagement.qdoc create mode 100644 doc/src/network/network-programming/qtnetwork.qdoc create mode 100644 doc/src/network/network-programming/ssl.qdoc create mode 100644 doc/src/network/qtnetwork.qdoc (limited to 'doc/src/network') diff --git a/doc/src/network/files-and-resources/datastreamformat.qdoc b/doc/src/network/files-and-resources/datastreamformat.qdoc new file mode 100644 index 0000000000..6fe888b52e --- /dev/null +++ b/doc/src/network/files-and-resources/datastreamformat.qdoc @@ -0,0 +1,361 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE: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 datastreamformat.html + \title Serializing Qt Data Types + \ingroup qt-network + \brief Representations of data types that can be serialized by QDataStream. + + The \l QDataStream allows you to serialize some of the Qt data types. + The table below lists the data types that QDataStream can serialize + and how they are represented. The format described below is + \l{QDataStream::setVersion()}{version 12}. + + It is always best to cast integers to a Qt integer type, such as + qint16 or quint32, when reading and writing. This ensures that + you always know exactly what size integers you are reading and + writing, no matter what the underlying platform and architecture + the application happens to be running on. + + \table + \row \o bool + \o \list + \o boolean + \endlist + \row \o qint8 + \o \list + \o signed byte + \endlist + \row \o qint16 + \o \list + \o signed 16-bit integer + \endlist + \row \o qint32 + \o \list + \o signed 32-bit integer + \endlist + \row \o qint64 + \o \list + \o signed 64-bit integer + \endlist + \row \o quint8 + \o \list + \o unsigned byte + \endlist + \row \o quint16 + \o \list + \o unsigned 16-bit integer + \endlist + \row \o quint32 + \o \list + \o unsigned 32-bit integer + \endlist + \row \o quint64 + \o \list + \o unsigned 64-bit integer + \endlist + \row \o \c float + \o \list + \o 32-bit floating point number using the standard IEEE 754 format + \endlist + \row \o \c double + \o \list + \o 64-bit floating point number using the standard IEEE 754 format + \endlist + \row \o \c {const char *} + \o \list + \o The string length (quint32) + \o The string bytes, excluding the terminating 0 + \endlist + \row \o QBitArray + \o \list + \o The array size (quint32) + \o The array bits, i.e. (size + 7)/8 bytes + \endlist + \row \o QBrush + \o \list + \o The brush style (quint8) + \o The brush color (QColor) + \o If style is CustomPattern, the brush pixmap (QPixmap) + \endlist + \row \o QByteArray + \o \list + \o If the byte array is null: 0xFFFFFFFF (quint32) + \o Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes + \endlist + \row \o \l QColor + \o \list + \o Color spec (qint8) + \o Alpha value (quint16) + \o Red value (quint16) + \o Green value (quint16) + \o Blue value (quint16) + \o Pad value (quint16) + \endlist + \row \o QCursor + \o \list + \o Shape ID (qint16) + \o If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint) + \endlist + \row \o QDate + \o \list + \o Julian day (quint32) + \endlist + \row \o QDateTime + \o \list + \o Date (QDate) + \o Time (QTime) + \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8) + \endlist + \row \o QEasingCurve + \o \list + \o type (quint8) + \o func (quint64) + \o hasConfig (bool) + \o If hasConfig is true then these fields follow: + \o list + \o period (double) + \o amplitude (double) + \o overshoot (double) + \endlist + \row \o QFont + \o \list + \o The family (QString) + \o The point size (qint16) + \o The style hint (quint8) + \o The char set (quint8) + \o The weight (quint8) + \o The font bits (quint8) + \endlist + \row \o QHash + \o \list + \o The number of items (quint32) + \o For all items, the key (Key) and value (T) + \endlist + \row \o QIcon + \o \list + \o The number of pixmap entries (quint32) + \o For all pixmap entries: + \list + \o The pixmap (QPixmap) + \o The file name (QString) + \o The pixmap size (QSize) + \o The \l{QIcon::Mode}{mode} (quint32) + \o The \l{QIcon::State}{state} (quint32) + \endlist + \endlist + \row \o QImage + \o \list + \o If the image is null a "null image" marker is saved; + otherwise the image is saved in PNG or BMP format (depending + on the stream version). If you want control of the format, + stream the image into a QBuffer (using QImageIO) and stream + that. + \endlist + \row \o QKeySequence + \o \list + \o A QList, where each integer is a key in the key sequence + \endlist + \row \o QLinkedList + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \row \o QList + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \row \o QMap + \o \list + \o The number of items (quint32) + \o For all items, the key (Key) and value (T) + \endlist + \row \o QMatrix + \o \list + \o m11 (double) + \o m12 (double) + \o m21 (double) + \o m22 (double) + \o dx (double) + \o dy (double) + \endlist + \row \o QMatrix4x4 + \o \list + \o m11 (double) + \o m12 (double) + \o m13 (double) + \o m14 (double) + \o m21 (double) + \o m22 (double) + \o m23 (double) + \o m24 (double) + \o m31 (double) + \o m32 (double) + \o m33 (double) + \o m34 (double) + \o m41 (double) + \o m42 (double) + \o m43 (double) + \o m44 (double) + \endlist + \row \o QPair + \o \list + \o first (T1) + \o second (T2) + \endlist + \row \o QPalette + \o The disabled, active, and inactive color groups, each of which consists + of the following: + \list + \o foreground (QBrush) + \o button (QBrush) + \o light (QBrush) + \o midlight (QBrush) + \o dark (QBrush) + \o mid (QBrush) + \o text (QBrush) + \o brightText (QBrush) + \o buttonText (QBrush) + \o base (QBrush) + \o background (QBrush) + \o shadow (QBrush) + \o highlight (QBrush) + \o highlightedText (QBrush) + \o link (QBrush) + \o linkVisited (QBrush) + \endlist + \row \o QPen + \o \list + \o The pen styles (quint8) + \o The pen width (quint16) + \o The pen color (QColor) + \endlist + \row \o QPicture + \o \list + \o The size of the picture data (quint32) + \o The raw bytes of picture data (char) + \endlist + \row \o QPixmap + \o \list + \o Save it as a PNG image. + \endlist + \row \o QPoint + \o \list + \o The x coordinate (qint32) + \o The y coordinate (qint32) + \endlist + \row \o QQuaternion + \o \list + \o The scalar component (double) + \o The x coordinate (double) + \o The y coordinate (double) + \o The z coordinate (double) + \endlist + \row \o QRect + \o \list + \o left (qint32) + \o top (qint32) + \o right (qint32) + \o bottom (qint32) + \endlist + \row \o QRegExp + \o \list + \o The regexp pattern (QString) + \o Case sensitivity (quint8) + \o Regular expression syntax (quint8) + \o Minimal matching (quint8) + \endlist + \row \o QRegion + \o \list + \o The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32) + \o 10 (qint32) + \o The number of rectangles (quint32) + \o The rectangles in sequential order (QRect) + \endlist + \row \o QSize + \o \list + \o width (qint32) + \o height (qint32) + \endlist + \row \o QString + \o \list + \o If the string is null: 0xFFFFFFFF (quint32) + \o Otherwise: The string length in bytes (quint32) followed by the data in UTF-16 + \endlist + \row \o QTime + \o \list + \o Milliseconds since midnight (quint32) + \endlist + \row \o QTransform + \o \list + \o m11 (double) + \o m12 (double) + \o m13 (double) + \o m21 (double) + \o m22 (double) + \o m23 (double) + \o m31 (double) + \o m32 (double) + \o m33 (double) + \endlist + \row \o QUrl + \o \list + \o Holds an URL (QString) + \endlist + \row \o QVariant + \o \list + \o The type of the data (quint32) + \o The null flag (qint8) + \o The data of the specified type + \endlist + \row \o QVector2D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \endlist + \row \o QVector3D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \o the z coordinate (double) + \endlist + \row \o QVector4D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \o the z coordinate (double) + \o the w coordinate (double) + \endlist + \row \o QVector + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \endtable +*/ diff --git a/doc/src/network/files-and-resources/resources.qdoc b/doc/src/network/files-and-resources/resources.qdoc new file mode 100644 index 0000000000..d6e320bf04 --- /dev/null +++ b/doc/src/network/files-and-resources/resources.qdoc @@ -0,0 +1,214 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE: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 io + \title Input/Output and Networking + \ingroup groups + + \brief Classes providing file input and output along with directory and + network handling. + + These classes are used to handle input and output to and from external + devices, processes, files etc. as well as manipulating files and directories. +*/ + +/*! + \page resources.html + \title The Qt Resource System + \ingroup qt-network + \brief A platform-independent mechanism for storing binary files in an application. + + \keyword resource system + + The Qt resource system is a platform-independent mechanism for + storing binary files in the application's executable. This is + useful if your application always needs a certain set of files + (icons, translation files, etc.) and you don't want to run the + risk of losing the files. + + The resource system is based on tight cooperation between \l qmake, + \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's + \c qembed tool and the + \l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image + collection} mechanism. + + \section1 Resource Collection Files (\c{.qrc}) + + The resources associated with an application are specified in a + \c .qrc file, an XML-based file format that lists files on the + disk and optionally assigns them a resource name that the + application must use to access the resource. + + Here's an example \c .qrc file: + + \quotefile mainwindows/application/application.qrc + + The resource files listed in the \c .qrc file are files that are + part of the application's source tree. The specified paths are + relative to the directory containing the \c .qrc file. Note that + the listed resource files must be located in the same directory as + the \c .qrc file, or one of its subdirectories. + + Resource data can either be compiled into the binary and thus accessed + immediately in application code, or a binary resource can be created + and at a later point in application code registered with the resource + system. + + By default, resources are accessible in the application under the + same file name as they have in the source tree, with a \c :/ prefix, + or by a \link QUrl URL\endlink with a \c qrc scheme. + + For example, the file path \c :/images/cut.png or the URL + \c qrc:///images/cut.png would give access to the + \c cut.png file, whose location in the application's source tree + is \c images/cut.png. This can be changed using the \c file tag's + \c alias attribute: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 0 + + The file is then accessible as \c :/cut-img.png from the + application. It is also possible to specify a path prefix for all + files in the \c .qrc file using the \c qresource tag's \c prefix + attribute: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 1 + + In this case, the file is accessible as \c + :/myresources/cut-img.png. + + Some resources, such as translation files and icons, many need to + change based on the user's locale. This is done by adding a \c lang + attribute to the \c qresource tag, specifying a suitable locale + string. For example: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 2 + + If the user's locale is French (i.e., QLocale::system().name() returns + "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg + image. For other locales, \c cut.jpg is used. + + See the QLocale documentation for a description of the format to use + for locale strings. + + + \section2 External Binary Resources + + For an external binary resource to be created you must create the resource + data (commonly given the \c .rcc extension) by passing the -binary switch to + \l rcc. Once the binary resource is created you can register the resource + with the QResource API. + + For example, a set of resource data specified in a \c .qrc file can be + compiled in the following way: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 3 + + In the application, this resource would be registered with code like this: + + \snippet doc/src/snippets/code/doc_src_resources.cpp 4 + + \section2 Compiled-In Resources + + For a resource to be compiled into the binary the \c .qrc file must be + mentioned in the application's \c .pro file so that \c qmake knows + about it. For example: + + \snippet examples/mainwindows/application/application.pro 0 + + \c qmake will produce make rules to generate a file called \c + qrc_application.cpp that is linked into the application. This + file contains all the data for the images and other resources as + static C++ arrays of compressed binary data. The \c + qrc_application.cpp file is automatically regenerated whenever + the \c .qrc file changes or one of the files that it refers to + changes. If you don't use \c .pro files, you can either invoke + \c rcc manually or add build rules to your build system. + + \image resources.png Building resources into an application + + Currently, Qt always stores the data directly in the executable, + even on Windows and Mac OS X, where the operating system provides + native support for resources. This might change in a future Qt + release. + + \section1 Compression + + Resources are compressed by default (in the \c ZIP format). It is + possible to turn off compression. This can be useful if your + resources already contain a compressed format, such as \c .png + files. You do this by giving the \c {-no-compress} command line + argument. + + \code + rcc -no-compress myresources.qrc + \endcode + + \c rcc also gives you some control over the compression. You can + specify the compression level and the threshold level to consider + while compressing files, for example: + + \code + rcc -compress 2 -threshold 3 myresources.qrc + \endcode + + \section1 Using Resources in the Application + + In the application, resource paths can be used in most places + instead of ordinary file system paths. In particular, you can + pass a resource path instead of a file name to the QIcon, QImage, + or QPixmap constructor: + + \snippet examples/mainwindows/application/mainwindow.cpp 21 + + See the \l{mainwindows/application}{Application} example for an + actual application that uses Qt's resource system to store its + icons. + + In memory, resources are represented by a tree of resource + objects. The tree is automatically built at startup and used by + QFile for resolving paths to resources. You can use a QDir initialized + with ":/" to navigate through the resource tree from the root. + + Qt's resources support the concept of a search path list. If you then + refer to a resource with \c : instead of \c :/ as the prefix, the + resource will be looked up using the search path list. The search + path list is empty at startup; call QDir::addSearchPath() to + add paths to it. + + If you have resources in a static library, you might need to + force initialization of your resources by calling \l + Q_INIT_RESOURCE() with the base name of the \c .qrc file. For + example: + + \snippet doc/src/snippets/code/doc_src_resources.cpp 5 + + Similarly, if you must unload a set of resources explicitly + (because a plugin is being unloaded or the resources are not valid + any longer), you can force removal of your resources by calling + Q_CLEANUP_RESOURCE() with the same base name as above. +*/ diff --git a/doc/src/network/network-programming/bearermanagement.qdoc b/doc/src/network/network-programming/bearermanagement.qdoc new file mode 100644 index 0000000000..3d0262aa95 --- /dev/null +++ b/doc/src/network/network-programming/bearermanagement.qdoc @@ -0,0 +1,271 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE: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 \o Interface management \o Session management +\row \o QNetworkSession::stop() \o QNetworkSession::open() +\row \o QNetworkSession::interface() \o QNetworkSession::close() +\row \o QNetworkSession::state() \o QNetworkSession::isOpen() +\row \o QNetworkSession::bytesWritten() \o QNetworkSession::migrate() +\row \o QNetworkSession::bytesReceived() \o QNetworkSession::ignore() +\row \o QNetworkSession::activeTime() \o QNetworkSession::accept() +\row \o QNetworkSession::stateChanged() \o QNetworkSession::reject() +\row \o \o QNetworkSession::opened() +\row \o \o 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 + \o Platform + \o Backend capabilities + \row + \o Linux\unicode{0xAE} + \o Linux uses the \l {http://projects.gnome.org/NetworkManager}{NetworkManager API} which supports interface notifications and starting and stopping of network interfaces. + \row + \o Windows\unicode{0xAE} XP + \o This platform supports interface notifications without active polling. + \row + \o Windows XP SP2+Hotfixes, Windows XP SP3, Windows Vista, Windows 7 + \o 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 + \o Symbian\unicode{0xAE} Platform & S60 3.1 + \o Symbian support is based on Symbian platforms RConnection. In addition to interface notifications, starting and stopping of network it provides system wide session support and direct connection routing. + \row + \o Symbian Platform & S60 3.2+ + \o This platform enjoys the most comprehensive feature set. In addition to the features support by the S60 3.1 Network roaming is supported. + \row + \o Mac OS\unicode{0xAE} + \o 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 + \o All other platforms (*nix, Windows Mobile) + \o This backend is the fallback for all platforms supports network interface notifications via active polling only. +\endtable + +*/ diff --git a/doc/src/network/network-programming/qtnetwork.qdoc b/doc/src/network/network-programming/qtnetwork.qdoc new file mode 100644 index 0000000000..93ba24815d --- /dev/null +++ b/doc/src/network/network-programming/qtnetwork.qdoc @@ -0,0 +1,350 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE: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 classes such as QFtp that implement specific + application-level protocols, lower-level classes such as QTcpSocket, + QTcpServer and QUdpSocket that represent low level network concepts, + and high level classes such as QNetworkRequest, QNetworkReply and + QNetworkAccessManager to perform network operations using common protocols. + 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 Writing FTP Clients with QFtp + + FTP (File Transfer Protocol) is a protocol used almost exclusively + for browsing remote directories and for transferring files. + + \image httpstack.png FTP Client and Server + + FTP uses two network connections, one for sending + commands and one for transferring data. The + FTP protocol has a state and requires the client to send several + commands before a file transfer takes place. + FTP clients establish a connection + and keeps it open throughout the session. In each session, multiple + transfers can occur. + + The QFtp class provides client-side support for FTP. + It has the following characteristics: + \list + + \o \e{Non-blocking behavior.} QFtp is asynchronous. + You can schedule a series of commands which are executed later, + when control returns to Qt's event loop. + + \o \e{Command IDs.} Each command has a unique ID number that you + can use to follow the execution of the command. For example, QFtp + emits the \l{QFtp::commandStarted()}{commandStarted()} and + \l{QFtp::commandFinished()}{commandFinished()} signal with the + command ID for each command that is executed. + + \o \e{Data transfer progress indicators.} QFtp emits signals + whenever data is transferred (QFtp::dataTransferProgress(), + QNetworkReply::downloadProgress(), and + QNetworkReply::uploadProgress()). You could connect these signals + to QProgressBar::setProgress() or QProgressDialog::setProgress(), + for example. + + \o \e{QIODevice support.} The class supports convenient + uploading from and downloading to \l{QIODevice}s, in addition to a + QByteArray-based API. + + \endlist + + There are two main ways of using QFtp. The most common + approach is to keep track of the command IDs and follow the + execution of every command by connecting to the appropriate + signals. The other approach is to schedule all commands at once + and only connect to the done() signal, which is emitted when all + scheduled commands have been executed. The first approach + requires more work, but it gives you more control over the + execution of individual commands and allows you to initiate new + commands based on the result of a previous command. It also + enables you to provide detailed feedback to the user. + + The \l{network/qftp}{FTP} example + illustrates how to write an FTP client. + Writing your own FTP (or HTTP) server is possible using the + lower-level classes QTcpSocket and QTcpServer. + + \section1 Using TCP with QTcpSocket and QTcpServer + + TCP (Transmission Control Protocol) is a low-level network + protocol used by most Internet protocols, including HTTP and FTP, + for data transfer. It is a reliable, stream-oriented, + connection-oriented transport protocol. It is particularly well + suited to the continuous transmission of data. + + \image tcpstream.png A TCP Stream + + The QTcpSocket class provides an interface for TCP. You can use + QTcpSocket to implement standard network protocols such as POP3, + SMTP, and NNTP, as well as custom protocols. + + A TCP connection must be established to a remote host and port + before any data transfer can begin. Once the connection has been + established, the IP address and port of the peer are available + through QTcpSocket::peerAddress() and QTcpSocket::peerPort(). At + any time, the peer can close the connection, and data transfer + will then stop immediately. + + QTcpSocket works asynchronously and emits signals to report status + changes and errors, just like QNetworkAccessManager and QFtp. It + relies on the event loop to detect incoming data and to + automatically flush outgoing data. You can write data to the + socket using QTcpSocket::write(), and read data using + QTcpSocket::read(). QTcpSocket represents two independent streams + of data: one for reading and one for writing. + + Since QTcpSocket inherits QIODevice, you can use it with + QTextStream and QDataStream. When reading from a QTcpSocket, you + must make sure that enough data is available by calling + QTcpSocket::bytesAvailable() beforehand. + + If you need to handle incoming TCP connections (e.g., in a server + application), use the QTcpServer class. Call QTcpServer::listen() + to set up the server, and connect to the + QTcpServer::newConnection() signal, which is emitted once for + every client that connects. In your slot, call + QTcpServer::nextPendingConnection() to accept the connection and + use the returned QTcpSocket to communicate with the client. + + Although most of its functions work asynchronously, it's possible + to use QTcpSocket synchronously (i.e., blocking). To get blocking + behavior, call QTcpSocket's waitFor...() functions; these suspend + the calling thread until a signal has been emitted. For example, + after calling the non-blocking QTcpSocket::connectToHost() + function, call QTcpSocket::waitForConnected() to block the thread + until the \l{QTcpSocket::connected()}{connected()} signal has + been emitted. + + Synchronous sockets often lead to code with a simpler flow of + control. The main disadvantage of the waitFor...() approach is + that events won't be processed while a waitFor...() function is + blocking. If used in the GUI thread, this might freeze the + application's user interface. For this reason, we recommend that + you use synchronous sockets only in non-GUI threads. When used + synchronously, QTcpSocket doesn't require an event loop. + + The \l{network/fortuneclient}{Fortune Client} and + \l{network/fortuneserver}{Fortune Server} examples show how to use + QTcpSocket and QTcpServer to write TCP client-server + applications. See also \l{network/blockingfortuneclient}{Blocking + Fortune Client} for an example on how to use a synchronous + QTcpSocket in a separate thread (without using an event loop), + and \l{network/threadedfortuneserver}{Threaded Fortune Server} + for an example of a multithreaded TCP server with one thread per + active client. + + \section1 Using UDP with QUdpSocket + + UDP (User Datagram Protocol) is a lightweight, unreliable, + datagram-oriented, connectionless protocol. It can be used when + reliability isn't important. For example, a server that reports + the time of day could choose UDP. If a datagram with the time of + day is lost, the client can simply make another request. + + \image udppackets.png UDP Packets + + The QUdpSocket class allows you to send and receive UDP + datagrams. It inherits QAbstractSocket, and it therefore shares + most of QTcpSocket's interface. The main difference is that + QUdpSocket transfers data as datagrams instead of as a continuous + stream of data. In short, a datagram is a data packet of limited + size (normally smaller than 512 bytes), containing the IP address + and port of the datagram's sender and receiver in addition to the + data being transferred. + + QUdpSocket supports IPv4 broadcasting. Broadcasting is often used + to implement network discovery protocols, such as finding which + host on the network has the most free hard disk space. One host + broadcasts a datagram to the network that all other hosts + receive. Each host that receives a request then sends a reply + back to the sender with its current amount of free disk space. + The originator waits until it has received replies from all + hosts, and can then choose the server with most free space to + store data. To broadcast a datagram, simply send it to the + special address QHostAddress::Broadcast (255.255.255.255), or + to your local network's broadcast address. + + QUdpSocket::bind() prepares the socket for accepting incoming + datagrams, much like QTcpServer::listen() for TCP servers. + Whenever one or more datagrams arrive, QUdpSocket emits the + \l{QUdpSocket::readyRead()}{readyRead()} signal. Call + QUdpSocket::readDatagram() to read the datagram. + + The \l{network/broadcastsender}{Broadcast Sender} and + \l{network/broadcastreceiver}{Broadcast Receiver} examples show how to + write a UDP sender and a UDP receiver using Qt. + + 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/doc/src/network/network-programming/ssl.qdoc b/doc/src/network/network-programming/ssl.qdoc new file mode 100644 index 0000000000..0bbcd8afb7 --- /dev/null +++ b/doc/src/network/network-programming/ssl.qdoc @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE: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/doc/src/network/qtnetwork.qdoc b/doc/src/network/qtnetwork.qdoc new file mode 100644 index 0000000000..084cebd497 --- /dev/null +++ b/doc/src/network/qtnetwork.qdoc @@ -0,0 +1,18 @@ +/*! + \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 doc/src/snippets/code/doc_src_qtnetwork.cpp 1 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtnetwork.pro 0 +*/ -- cgit v1.2.3