summaryrefslogtreecommitdiffstats
path: root/doc/src/network
diff options
context:
space:
mode:
authorCasper van Donderen <casper.vandonderen@nokia.com>2012-05-09 12:35:30 +0200
committerMarius Storm-Olsen <marius.storm-olsen@nokia.com>2012-05-09 22:43:31 +0200
commit47799adc0d1bfb9e0e592dbc9af3eb4680e0c81b (patch)
treea2518897dda5c9634ac2d9ff8a667743d08cb179 /doc/src/network
parenta4d07f6c0bc71b3e0abd109325b3be4683e0d243 (diff)
Doc: Move some remaining files over for modularization.
The files in this change were still in qtbase/doc/src or required for it. qtbase/doc/src should now only contain example documentation and images for the example documentation. Change-Id: Ia7ca8e7fd2b316e77c706a08df71303bc8294213 Reviewed-by: Marius Storm-Olsen <marius.storm-olsen@nokia.com>
Diffstat (limited to 'doc/src/network')
-rw-r--r--doc/src/network/files-and-resources/resources.qdoc214
-rw-r--r--doc/src/network/network-programming/bearermanagement.qdoc268
-rw-r--r--doc/src/network/network-programming/qtnetwork.qdoc291
-rw-r--r--doc/src/network/network-programming/ssl.qdoc79
4 files changed, 0 insertions, 852 deletions
diff --git a/doc/src/network/files-and-resources/resources.qdoc b/doc/src/network/files-and-resources/resources.qdoc
deleted file mode 100644
index 1d0fc51631..0000000000
--- a/doc/src/network/files-and-resources/resources.qdoc
+++ /dev/null
@@ -1,214 +0,0 @@
-/****************************************************************************
-**
-** 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 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 need to change based on the user's locale,
- such as translation files or icons. 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
deleted file mode 100644
index 91dc32c5a5..0000000000
--- a/doc/src/network/network-programming/bearermanagement.qdoc
+++ /dev/null
@@ -1,268 +0,0 @@
-/****************************************************************************
-**
-** 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/doc/src/network/network-programming/qtnetwork.qdoc b/doc/src/network/network-programming/qtnetwork.qdoc
deleted file mode 100644
index 0701b04f6f..0000000000
--- a/doc/src/network/network-programming/qtnetwork.qdoc
+++ /dev/null
@@ -1,291 +0,0 @@
-/****************************************************************************
-**
-** 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/doc/src/network/network-programming/ssl.qdoc b/doc/src/network/network-programming/ssl.qdoc
deleted file mode 100644
index 21828d7af9..0000000000
--- a/doc/src/network/network-programming/ssl.qdoc
+++ /dev/null
@@ -1,79 +0,0 @@
-/****************************************************************************
-**
-** 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.
-*/