path: root/doc/src/network/network-programming
diff options
authorCasper van Donderen <>2011-09-16 14:14:43 +0200
committerQt by Nokia <>2011-09-19 10:24:25 +0200
commitcd621c201ca637385c6e3409d5c84ecec5fb5418 (patch)
tree981b062e3bbc5c513498b18c10ad55f8252e8486 /doc/src/network/network-programming
parent20009ed797fb30952a889df5716aa2399102be58 (diff)
Move the module qdoc files from qtdoc and split up doc/src.
Change-Id: I7d992889379d78e07a0b7023facebd7421cf6d22 Reviewed-on: Reviewed-by: Qt Sanity Bot <> Reviewed-by: Jerome Pasion <>
Diffstat (limited to 'doc/src/network/network-programming')
3 files changed, 700 insertions, 0 deletions
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 (
+** This file is part of the documentation of the Qt Toolkit.
+** 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.
+\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.
+\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()
+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:
+ // 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);
+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
+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:
+ \header
+ \o Platform
+ \o Backend capabilities
+ \row
+ \o Linux\unicode{0xAE}
+ \o Linux uses the \l {}{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.
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 (
+** This file is part of the documentation of the Qt Toolkit.
+** 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.
+ \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 (, 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 (
+** This file is part of the documentation of the Qt Toolkit.
+** 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.
+ \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.