qtmobility/src/bearer/qnetworkconfiguration.cpp
changeset 0 cfcbf08528c4
child 1 5822d84012fb
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/qtmobility/src/bearer/qnetworkconfiguration.cpp	Thu Apr 01 08:30:34 2010 +0300
@@ -0,0 +1,401 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Mobility Components.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qnetworkconfiguration.h"
+
+#ifdef Q_OS_SYMBIAN
+#include "qnetworkconfiguration_s60_p.h"
+#elif Q_WS_MAEMO_6
+#include "qnetworkconfiguration_maemo_p.h"
+#else
+#include "qnetworkconfiguration_p.h"
+#endif
+
+QTM_BEGIN_NAMESPACE
+
+/*!
+    \class QNetworkConfiguration
+
+    \brief The QNetworkConfiguration class provides an abstraction of one or more access point configurations.
+
+    \inmodule QtNetwork
+    \ingroup bearer
+
+    QNetworkConfiguration encapsulates a single access point or service network.
+    In most cases a single access point configuration can be mapped to one network
+    interface. However a single network interface may not always map to only one
+    access point configuration. Multiple configurations for the same
+    network device may enable multiple access points. An example
+    device that could exhibit such a configuration might be a
+    Smartphone which allows the user to manage multiple WLAN
+    configurations while the device itself has only one WLAN network device.
+
+    The QNetworkConfiguration also supports the concept of service networks.
+    This concept allows the grouping of multiple access point configurations
+    into one entity. Such a group is called service network and can be
+    beneficial in cases whereby a network session to a
+    particular destination network is required (e.g. a company network).
+    When using a service network the user doesn't usually care which one of the
+    connectivity options is chosen (e.g. corporate WLAN or VPN via GPRS)
+    as long as he can reach the company's target server. Depending
+    on the current position and time some of the access points that make
+    up the service network may not even be available. Furthermore
+    automated access point roaming can be enabled which enables the device
+    to change the network interface configuration dynamically while maintaining
+    the applications connection to the target network. It allows adaption
+    to the changing environment and may enable optimization with regards to
+    cost, speed or other network parameters.
+
+    Special configurations of type UserChoice provide a placeholder configuration which is
+    resolved to an actual network configuration by the platform when a
+    \l {QNetworkSession}{session} is \l {QNetworkSession::open()}{opened}. Not all platforms
+    support the concept of a user choice configuration.
+
+    \section1 Configuration states
+
+    The list of available configurations can be obtained via
+    QNetworkConfigurationManager::allConfigurations(). A configuration can have
+    multiple states. The \l Defined configuration state indicates that the configuration
+    is stored on the device. However the configuration is not yet ready to be activated
+    as e.g. a WLAN may not be available at the current time.
+
+    The \l Discovered state implies that the configuration is \l Defined and
+    the outside conditions are such that the configuration can be used immediately
+    to open a new network session. An example of such an outside condition may be
+    that the Ethernet cable is actually connected to the device or that the WLAN
+    with the specified SSID is in range.
+
+    The \l Active state implies that the configuration is \l Discovered. A configuration
+    in this state is currently being used by an application. The underlying network
+    interface has a valid IP configuration and can transfer IP packets between the
+    device and the target network.
+
+    The \l Undefined state indicates that the system has knowledge of possible target
+    networks but cannot actually use that knowledge to connect to it. An example
+    for such a state could be an encrypted WLAN that has been discovered
+    but the user hasn't actually saved a configuration including the required password
+    which would allow the device to connect to it.
+
+    Depending on the type of configuration some states are transient in nature. A GPRS/UMTS
+    connection may almost always be \l Discovered if the GSM/UMTS network is available.
+    However if the GSM/UMTS network looses the connection the associated configuration may change its state
+    from \l Discovered to \l Defined as well. A similar use case might be triggered by
+    WLAN availability. QNetworkConfigurationManager::updateConfigurations() can be used to
+    manually trigger updates of states. Note that some platforms do not require such updates
+    as they implicitly change the state once it has been discovered. If the state of a
+    configuration changes all related QNetworkConfiguration instances change their state automatically.
+
+    \sa QNetworkSession, QNetworkConfigurationManager
+*/
+
+/*!
+    \enum QNetworkConfiguration::Type
+
+    This enum describes the type of configuration.
+
+    \value InternetAccessPoint  The configuration specifies the details for a single access point.
+                                Note that configurations of type InternetAccessPoint may be part
+                                of other QNetworkConfigurations of type ServiceNetwork.
+    \value ServiceNetwork       The configuration is based on a group of QNetworkConfigurations of
+                                type InternetAccessPoint. All group members can reach the same
+                                target network. This type of configuration is a mandatory
+                                requirement for roaming enabled network sessions. On some
+                                platforms this form of configuration may also be called Service
+                                Network Access Point (SNAP).
+    \value UserChoice           The configuration is a placeholder which will be resolved to an
+                                actual configuration by the platform when a session is opened. Depending
+                                on the platform the selection may generate a popup dialog asking the user
+                                for his preferred choice.
+    \value Invalid              The configuration is invalid.
+*/
+
+/*!
+    \enum QNetworkConfiguration::StateFlag
+
+    Specifies the configuration states.
+
+    \value Undefined    This state is used for transient configurations such as newly discovered
+                        WLANs for which the user has not actually created a configuration yet.
+    \value Defined      Defined configurations are known to the system but are not immediately
+                        usable (e.g. a configured WLAN is not within range or the Ethernet cable
+                        is currently not plugged into the machine).
+    \value Discovered   A discovered configuration can be immediately used to create a new
+                        QNetworkSession. An example of a discovered configuration could be a WLAN
+                        which is within in range. If the device moves out of range the discovered
+                        flag is dropped. A second example is a GPRS configuration which generally
+                        remains discovered for as long as the phone has network coverage. A
+                        configuration that has this state is also in state
+                        QNetworkConfiguration::Defined. If the configuration is a service network
+                        this flag is set if at least one of the underlying access points
+                        configurations has the Discovered state.
+    \value Active       The configuration is currently used by an open network session
+                        (see \l QNetworkSession::isOpen()). However this does not mean that the
+                        current process is the entity that created the open session. It merely
+                        indicates that if a new QNetworkSession were to be constructed based on
+                        this configuration \l QNetworkSession::state() would return
+                        \l QNetworkSession::Connected. This state implies the
+                        QNetworkConfiguration::Discovered state.
+*/
+
+/*!
+    \enum QNetworkConfiguration::Purpose
+
+    Specifies the purpose of the configuration.
+
+    \value UnknownPurpose           The configuration doesn't specify any purpose. This is the default value.
+    \value PublicPurpose            The configuration can be used for general purpose internet access.
+    \value PrivatePurpose           The configuration is suitable to access a private network such as an office Intranet.
+    \value ServiceSpecificPurpose   The configuration can be used for operator specific services (e.g.
+                                    receiving MMS messages or content streaming).
+*/
+
+/*!
+    Constructs an invalid configuration object.
+
+    \sa isValid()
+*/
+QNetworkConfiguration::QNetworkConfiguration()
+    : d(0)
+{
+}
+
+/*!
+    Creates a copy of the QNetworkConfiguration object contained in \a other.
+*/
+QNetworkConfiguration::QNetworkConfiguration(const QNetworkConfiguration& other)
+    : d(other.d)
+{
+}
+
+/*!
+    Copies the content of the QNetworkConfiguration object contained in \a other into this one.
+*/
+QNetworkConfiguration& QNetworkConfiguration::operator=(const QNetworkConfiguration& other)
+{
+    d = other.d;
+    return *this;
+}
+
+/*!
+    Frees the resources associated with the QNetworkConfiguration object.
+*/
+QNetworkConfiguration::~QNetworkConfiguration()
+{
+}
+
+/*!
+    Returns true, if this configuration is the same as the \a other
+    configuration given; otherwise returns false.
+*/
+bool QNetworkConfiguration::operator==(const QNetworkConfiguration& other) const
+{
+    if (!d)
+        return !other.d;
+
+    if (!other.d)
+        return false;
+
+    return (d == other.d);
+}
+
+/*!
+    \fn bool QNetworkConfiguration::operator!=(const QNetworkConfiguration& other) const
+
+    Returns true if this configuration is not the same as the \a other
+    configuration given; otherwise returns false.
+*/
+
+/*!
+    Returns the user visible name of this configuration.
+
+    The name may either be the name of the underlying access point or the
+    name for service network that this configuration represents.
+*/
+QString QNetworkConfiguration::name() const
+{
+    return d ? d->name : QString();
+}
+
+/*!
+    Returns the unique and platform specific identifier for this network configuration;
+    otherwise an empty string.
+*/
+QString QNetworkConfiguration::identifier() const
+{
+    return d ? d->id : QString();
+}
+
+/*!
+    Returns the type of the configuration.
+
+    A configuration can represent a single access point configuration or
+    a set of access point configurations. Such a set is called service network.
+    A configuration that is based on a service network can potentially support
+    roaming of network sessions.
+*/
+QNetworkConfiguration::Type QNetworkConfiguration::type() const
+{
+    return d ? d->type : QNetworkConfiguration::Invalid;
+}
+
+/*!
+    Returns true if this QNetworkConfiguration object is valid.
+    A configuration may become invalid if the user deletes the configuration or
+    the configuration was default-constructed.
+
+    The addition and removal of configurations can be monitored via the
+    QNetworkConfigurationManager.
+
+    \sa QNetworkConfigurationManager
+*/
+bool QNetworkConfiguration::isValid() const
+{
+    return d ? d->isValid : false;
+}
+
+/*!
+    Returns the current state of the configuration.
+*/
+QNetworkConfiguration::StateFlags QNetworkConfiguration::state() const
+{
+    return d ? d->state : QNetworkConfiguration::Undefined;
+}
+
+/*!
+    Returns the purpose of this configuration.
+
+    The purpose field may be used to programmatically determine the
+    purpose of a configuration. Such information is usually part of the
+    access point or service network meta data.
+*/
+QNetworkConfiguration::Purpose QNetworkConfiguration::purpose() const
+{
+    return d ? d->purpose : QNetworkConfiguration::UnknownPurpose;
+}
+
+/*!
+    Returns true if this configuration supports roaming; otherwise false.
+*/
+bool QNetworkConfiguration::isRoamingAvailable() const
+{
+    return d ? d->roamingSupported : false;
+}
+
+/*!
+    Returns all sub configurations of this network configuration.
+    Only network configurations of type \l ServiceNetwork can have children. Otherwise
+    this function returns an empty list.
+*/
+QList<QNetworkConfiguration> QNetworkConfiguration::children() const
+{
+    QList<QNetworkConfiguration> results;
+    if (type() != QNetworkConfiguration::ServiceNetwork || !isValid() )
+        return results;
+
+    QMutableListIterator<QExplicitlySharedDataPointer<QNetworkConfigurationPrivate> > iter(d->serviceNetworkMembers);
+    QExplicitlySharedDataPointer<QNetworkConfigurationPrivate> p(0);
+    while(iter.hasNext()) {
+        p = iter.next();
+        //if we have an invalid member get rid of it -> was deleted earlier on
+        if (!p->isValid)
+            iter.remove();
+
+        QNetworkConfiguration item;
+        item.d = p;
+        results << item;
+    }
+
+    return results;
+}
+
+/*!
+    Returns the type of bearer. The string is not translated and
+    therefore can not be shown to the user. The subsequent table presents the currently known
+    bearer types:
+
+    \table
+        \header 
+            \o Value
+            \o Description
+        \row
+            \o Unknown
+            \o The session is based on an unknown or unspecified bearer type.
+        \row
+            \o Ethernet
+            \o The session is based on Ethernet.
+        \row
+            \o WLAN
+            \o The session is based on Wireless LAN.
+        \row
+            \o 2G
+            \o The session uses CSD, GPRS, HSCSD, EDGE or cdmaOne.
+        \row 
+            \o CDMA2000
+            \o The session uses CDMA.
+        \row
+            \o WCDMA
+            \o The session uses W-CDMA/UMTS.
+        \row
+            \o HSPA
+            \o The session uses High Speed Packet Access.
+        \row
+            \o Bluetooth
+            \o The session uses Bluetooth.
+        \row
+            \o WiMAX
+            \o The session uses WiMAX.
+    \endtable
+
+    This function returns an empty string if this is an invalid configuration,
+    a network configuration of type \l QNetworkConfiguration::ServiceNetwork or
+    \l QNetworkConfiguration::UserChoice.
+*/
+QString QNetworkConfiguration::bearerName() const
+{
+    if (!isValid())
+        return QString();
+
+    return d->bearerName();
+}
+
+
+QTM_END_NAMESPACE
+