1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt Mobility Components.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qnetworkconfigmanager.h"

    43 

    44 #ifdef Q_OS_SYMBIAN

    45 #include "qnetworkconfigmanager_s60_p.h"

    46 #elif Q_WS_MAEMO_6

    47 #include "qnetworkconfigmanager_maemo_p.h"

    48 #else

    49 #include "qnetworkconfigmanager_p.h"

    50 #endif

    51 

    52 QTM_BEGIN_NAMESPACE

    53 

    54 Q_GLOBAL_STATIC(QNetworkConfigurationManagerPrivate, connManager);

    55 

    56 /*!

    57     \class QNetworkConfigurationManager

    58 

    59     \brief The QNetworkConfigurationManager class manages the network configurations provided

    60     by the system.

    61 

    62     \inmodule QtNetwork

    63     \ingroup bearer

    64 

    65     QNetworkConfigurationManager provides access to the network configurations known to the system and

    66     enables applications to detect the system capabilities (with regards to network sessions) at runtime.

    67 

    68     A QNetworkConfiguration abstracts a set of configuration options describing how a

    69     network interface has to be configured to connect to a particular target network.

    70     QNetworkConfigurationManager maintains and updates the global list of

    71     QNetworkConfigurations. Applications can access and filter this list via

    72     allConfigurations(). If a new configuration is added or an existing one is removed or changed

    73     the configurationAdded(), configurationRemoved() and configurationChanged() signals are emitted

    74     respectively.

    75 

    76     The defaultConfiguration() can be used when intending to immediately create a new

    77     network session without caring about the particular configuration. It returns

    78     a \l QNetworkConfiguration::Discovered configuration. If there are not any

    79     discovered ones an invalid configuration is returned.

    80 

    81     Some configuration updates may require some time to perform updates. A WLAN scan is

    82     such an example. Unless the platform performs internal updates it may be required to

    83     manually trigger configuration updates via QNetworkConfigurationManager::updateConfigurations().

    84     The completion of the update process is indicted by emitting the updateCompleted()

    85     signal. The update process ensures that every existing QNetworkConfiguration instance

    86     is updated. There is no need to ask for a renewed configuration list via allConfigurations().

    87 

    88     \sa QNetworkConfiguration

    89 */

    90 

    91 /*! 

    92     \fn void QNetworkConfigurationManager::configurationAdded(const QNetworkConfiguration& config)

    93 

    94     This signal is emitted whenever a new network configuration is added to the system. The new

    95     configuration is specified by \a config.

    96 */

    97 

    98 /*!

    99     \fn void QNetworkConfigurationManager::configurationRemoved(const QNetworkConfiguration& configuration)

   100 

   101     This signal is emitted when a configuration is about to be removed from the system. The removed

   102     \a configuration is invalid but retains name and identifier.

   103 */

   104 

   105 /*!

   106     \fn void QNetworkConfigurationManager::updateCompleted()

   107 

   108     This signal is emitted when the configuration update has been completed. Such an update can

   109     be initiated via \l updateConfigurations().

   110 */

   111 

   112 /*! \fn void QNetworkConfigurationManager::configurationChanged(const QNetworkConfiguration& config)

   113 

   114     This signal is emitted when the \l {QNetworkConfiguration::state()}{state} of \a config changes.

   115 */

   116 

   117 /*!

   118     \fn void QNetworkConfigurationManager::onlineStateChanged(bool isOnline)

   119 

   120     This signal is emitted when the device changes from online to offline mode or vice versa.

   121     \a isOnline represents the new state of the device.

   122 

   123     The state is considered to be online for as long as

   124     \l{allConfigurations()}{allConfigurations}(QNetworkConfiguration::Active) returns a list with

   125     at least one entry.

   126 */

   127 

   128 /*!

   129     \enum QNetworkConfigurationManager::Capability

   130 

   131     Specifies the system capabilities of the bearer API. The possible values are:

   132 

   133     \value CanStartAndStopInterfaces Network sessions and their underlying access points can be

   134                                      started and stopped. If this flag is not set QNetworkSession

   135                                      can only monitor but not influence the state of access points.

   136                                      On some platforms this feature may require elevated user

   137                                      permissions. This option is platform specific and may not

   138                                      always be available.

   139     \value DirectConnectionRouting   Network sessions and their sockets can be bound to a

   140                                      particular network interface. Any packet that passes through

   141                                      the socket goes to the specified network interface and thus

   142                                      disregards standard routing table entries. This may be useful

   143                                      when two interfaces can reach overlapping IP ranges or an

   144                                      application has specific needs in regards to target networks.

   145                                      This option is platform specific and may not always be

   146                                      available.

   147     \value SystemSessionSupport      If this flag is set the underlying platform ensures that a

   148                                      network interface is not shut down until the last network

   149                                      session has been \l{QNetworkSession::close()}{closed()}. This

   150                                      works across multiple processes. If the platform session

   151                                      support is missing this API can only ensure the above behavior

   152                                      for network sessions within the same process.

   153                                      In general mobile platforms (such as Symbian/S60) have such

   154                                      support whereas most desktop platform lack this capability.

   155     \value ApplicationLevelRoaming   The system gives applications control over the systems roaming

   156                                      behavior. Applications can initiate roaming (in case the

   157                                      current link is not suitable) and are consulted if the system

   158                                      has identified a more suitable access point.

   159     \value ForcedRoaming             The system disconnects an existing access point and reconnects

   160                                      via a more suitable one. The application does not have any

   161                                      control over this process and has to reconnect its active

   162                                      sockets.

   163     \value DataStatistics            If this flag is set QNetworkSession can provide statistics

   164                                      about transmitted and received data.

   165 */

   166 

   167 /*!

   168     Constructs a QNetworkConfigurationManager with the given \a parent.

   169 */

   170 QNetworkConfigurationManager::QNetworkConfigurationManager( QObject* parent )

   171     : QObject(parent)

   172 {

   173     QNetworkConfigurationManagerPrivate* priv = connManager();

   174     connect(priv, SIGNAL(configurationAdded(QNetworkConfiguration)),

   175             this, SIGNAL(configurationAdded(QNetworkConfiguration)));

   176     connect(priv, SIGNAL(configurationRemoved(QNetworkConfiguration)),

   177             this, SIGNAL(configurationRemoved(QNetworkConfiguration)));

   178     connect(priv, SIGNAL(configurationUpdateComplete()),

   179             this, SIGNAL(updateCompleted()));

   180     connect(priv, SIGNAL(onlineStateChanged(bool)), 

   181             this, SIGNAL(onlineStateChanged(bool)));

   182     connect(priv, SIGNAL(configurationChanged(QNetworkConfiguration)),

   183             this, SIGNAL(configurationChanged(QNetworkConfiguration)));

   184 }

   185 

   186 /*!

   187     Frees the resources associated with the QNetworkConfigurationManager object.

   188 */

   189 QNetworkConfigurationManager::~QNetworkConfigurationManager()

   190 {

   191 }

   192 

   193 

   194 /*!

   195     Returns the default configuration to be used. This function always returns a discovered

   196     configuration; otherwise an invalid configuration.

   197 

   198     In some cases it may be required to call updateConfigurations() and wait for the

   199     updateCompleted() signal before calling this function.

   200 

   201     \sa allConfigurations()

   202 */

   203 QNetworkConfiguration QNetworkConfigurationManager::defaultConfiguration() const

   204 {

   205     return connManager()->defaultConfiguration();

   206 }

   207 

   208 /*!

   209     Returns the list of configurations which comply with the given \a filter.

   210 

   211     By default this function returns all (defined and undefined) configurations.

   212 

   213     A wireless network with a particular SSID may only be accessible in a

   214     certain area despite the fact that the system has a valid configuration

   215     for it. Therefore the filter flag may be used to limit the list to

   216     discovered and possibly connected configurations only.

   217 

   218     If \a filter is set to zero this function returns all possible configurations.

   219 

   220     Note that this function returns the states for all configurations as they are known at

   221     the time of this function call. If for instance a configuration of type WLAN is defined

   222     the system may have to perform a WLAN scan in order to determine whether it is

   223     actually available. To obtain the most accurate state updateConfigurations() should

   224     be used to update each configuration's state. Note that such an update may require

   225     some time. It's completion is signalled by updateCompleted(). In the absence of a

   226     configuration update this function returns the best estimate at the time of the call.

   227     Therefore, if WLAN configurations are of interest, it is recommended that

   228     updateConfigurations() is called once after QNetworkConfigurationManager

   229     instantiation (WLAN scans are too time consuming to perform in constructor).

   230     After this the data is kept automatically up-to-date as the system reports

   231     any changes.

   232 */

   233 QList<QNetworkConfiguration> QNetworkConfigurationManager::allConfigurations(QNetworkConfiguration::StateFlags filter) const

   234 {

   235     QList<QNetworkConfiguration> result;

   236     QNetworkConfigurationManagerPrivate* conPriv = connManager();

   237     QList<QString> cpsIdents = conPriv->accessPointConfigurations.keys();

   238 

   239     //find all InternetAccessPoints

   240     foreach( QString ii, cpsIdents) {

   241         QExplicitlySharedDataPointer<QNetworkConfigurationPrivate> p = 

   242             conPriv->accessPointConfigurations.value(ii);

   243         if ( (p->state & filter) == filter ) {

   244             QNetworkConfiguration pt;

   245             pt.d = conPriv->accessPointConfigurations.value(ii);

   246             result << pt;

   247         }

   248     }

   249 

   250     //find all service networks

   251     cpsIdents = conPriv->snapConfigurations.keys();

   252     foreach( QString ii, cpsIdents) {

   253         QExplicitlySharedDataPointer<QNetworkConfigurationPrivate> p = 

   254             conPriv->snapConfigurations.value(ii);

   255         if ( (p->state & filter) == filter ) {

   256             QNetworkConfiguration pt;

   257             pt.d = conPriv->snapConfigurations.value(ii);

   258             result << pt;

   259         }

   260     }

   261 

   262     return result;

   263 }

   264 

   265 /*!

   266     Returns the QNetworkConfiguration for \a identifier; otherwise returns an

   267     invalid QNetworkConfiguration.

   268 

   269     \sa QNetworkConfiguration::identifier()

   270 */

   271 QNetworkConfiguration QNetworkConfigurationManager::configurationFromIdentifier(const QString& identifier) const

   272 {

   273     QNetworkConfigurationManagerPrivate* conPriv = connManager();

   274     QNetworkConfiguration item;

   275     if (conPriv->accessPointConfigurations.contains(identifier))

   276         item.d = conPriv->accessPointConfigurations.value(identifier);

   277     else if (conPriv->snapConfigurations.contains(identifier))

   278         item.d = conPriv->snapConfigurations.value(identifier);

   279     else if (conPriv->userChoiceConfigurations.contains(identifier))

   280         item.d = conPriv->userChoiceConfigurations.value(identifier);

   281     return item;

   282 

   283 }

   284 

   285 /*!

   286     Returns true if the system is considered to be connected to another device via an active

   287     network interface; otherwise returns false.

   288 

   289     This is equivalent to the following code snippet:

   290 

   291     \code

   292         QNetworkConfigurationManager mgr;

   293         QList<QNetworkConfiguration> activeConfigs = mgr.allConfigurations(QNetworkConfiguration::Active)

   294         if (activeConfigs.count() > 0)

   295             Q_ASSERT(mgr.isOnline())

   296         else

   297             Q_ASSERT(!mgr.isOnline())

   298     \endcode

   299 

   300     \sa onlineStateChanged()

   301 */

   302 bool QNetworkConfigurationManager::isOnline() const

   303 {

   304     QNetworkConfigurationManagerPrivate* conPriv = connManager();

   305     Q_UNUSED(conPriv);

   306     QList<QNetworkConfiguration> activeConfigs = allConfigurations(QNetworkConfiguration::Active);

   307     return activeConfigs.count() > 0;

   308 }

   309 

   310 /*!

   311     Returns the capabilities supported by the current platform.

   312 */

   313 QNetworkConfigurationManager::Capabilities QNetworkConfigurationManager::capabilities() const

   314 {

   315     return connManager()->capFlags;

   316 }

   317 

   318 /*!

   319     Initiates an update of all configurations. This may be used to initiate WLAN scans or other

   320     time consuming updates which may be required to obtain the correct state for configurations.

   321 

   322     This call is asynchronous. On completion of this update the updateCompleted() signal is

   323     emitted. If new configurations are discovered or old ones were removed or changed the update

   324     process may trigger the emission of one or multiple configurationAdded(),

   325     configurationRemoved() and configurationChanged() signals.

   326 

   327     If a configuration state changes as a result of this update all existing QNetworkConfiguration

   328     instances are updated automatically.

   329 

   330     \sa allConfigurations()

   331 */

   332 void QNetworkConfigurationManager::updateConfigurations()

   333 {

   334     connManager()->performAsyncConfigurationUpdate();

   335 }

   336 

   337 #include "moc_qnetworkconfigmanager.cpp"

   338 

   339 QTM_END_NAMESPACE

   340