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

     2 **

     3 ** Copyright (C) 2010 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 QtNetwork module of the Qt Toolkit.

     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 "qnetworkconfiguration.h"

    43 #include "qnetworkconfiguration_p.h"

    44 

    45 QT_BEGIN_NAMESPACE

    46 

    47 /*!

    48     \class QNetworkConfiguration

    49 

    50     \brief The QNetworkConfiguration class provides an abstraction of one or more access point configurations.

    51 

    52     \since 4.7

    53 

    54     \inmodule QtNetwork

    55     \ingroup network

    56 

    57     QNetworkConfiguration encapsulates a single access point or service network.

    58     In most cases a single access point configuration can be mapped to one network

    59     interface. However a single network interface may not always map to only one

    60     access point configuration. Multiple configurations for the same

    61     network device may enable multiple access points. An example

    62     device that could exhibit such a configuration might be a

    63     Smartphone which allows the user to manage multiple WLAN

    64     configurations while the device itself has only one WLAN network device.

    65 

    66     The QNetworkConfiguration also supports the concept of service networks.

    67     This concept allows the grouping of multiple access point configurations

    68     into one entity. Such a group is called service network and can be

    69     beneficial in cases whereby a network session to a

    70     particular destination network is required (e.g. a company network).

    71     When using a service network the user doesn't usually care which one of the

    72     connectivity options is chosen (e.g. corporate WLAN or VPN via GPRS)

    73     as long as he can reach the company's target server. Depending

    74     on the current position and time some of the access points that make

    75     up the service network may not even be available. Furthermore

    76     automated access point roaming can be enabled which enables the device

    77     to change the network interface configuration dynamically while maintaining

    78     the applications connection to the target network. It allows adaption

    79     to the changing environment and may enable optimization with regards to

    80     cost, speed or other network parameters.

    81 

    82     Special configurations of type UserChoice provide a placeholder configuration which is

    83     resolved to an actual network configuration by the platform when a

    84     \l {QNetworkSession}{session} is \l {QNetworkSession::open()}{opened}. Not all platforms

    85     support the concept of a user choice configuration.

    86 

    87     \section1 Configuration states

    88 

    89     The list of available configurations can be obtained via

    90     QNetworkConfigurationManager::allConfigurations(). A configuration can have

    91     multiple states. The \l Defined configuration state indicates that the configuration

    92     is stored on the device. However the configuration is not yet ready to be activated

    93     as e.g. a WLAN may not be available at the current time.

    94 

    95     The \l Discovered state implies that the configuration is \l Defined and

    96     the outside conditions are such that the configuration can be used immediately

    97     to open a new network session. An example of such an outside condition may be

    98     that the Ethernet cable is actually connected to the device or that the WLAN

    99     with the specified SSID is in range.

   100 

   101     The \l Active state implies that the configuration is \l Discovered. A configuration

   102     in this state is currently being used by an application. The underlying network

   103     interface has a valid IP configuration and can transfer IP packets between the

   104     device and the target network.

   105 

   106     The \l Undefined state indicates that the system has knowledge of possible target

   107     networks but cannot actually use that knowledge to connect to it. An example

   108     for such a state could be an encrypted WLAN that has been discovered

   109     but the user hasn't actually saved a configuration including the required password

   110     which would allow the device to connect to it.

   111 

   112     Depending on the type of configuration some states are transient in nature. A GPRS/UMTS

   113     connection may almost always be \l Discovered if the GSM/UMTS network is available.

   114     However if the GSM/UMTS network looses the connection the associated configuration may change its state

   115     from \l Discovered to \l Defined as well. A similar use case might be triggered by

   116     WLAN availability. QNetworkConfigurationManager::updateConfigurations() can be used to

   117     manually trigger updates of states. Note that some platforms do not require such updates

   118     as they implicitly change the state once it has been discovered. If the state of a

   119     configuration changes all related QNetworkConfiguration instances change their state automatically.

   120 

   121     \sa QNetworkSession, QNetworkConfigurationManager

   122 */

   123 

   124 /*!

   125     \enum QNetworkConfiguration::Type

   126 

   127     This enum describes the type of configuration.

   128 

   129     \value InternetAccessPoint  The configuration specifies the details for a single access point.

   130                                 Note that configurations of type InternetAccessPoint may be part

   131                                 of other QNetworkConfigurations of type ServiceNetwork.

   132     \value ServiceNetwork       The configuration is based on a group of QNetworkConfigurations of

   133                                 type InternetAccessPoint. All group members can reach the same

   134                                 target network. This type of configuration is a mandatory

   135                                 requirement for roaming enabled network sessions. On some

   136                                 platforms this form of configuration may also be called Service

   137                                 Network Access Point (SNAP).

   138     \value UserChoice           The configuration is a placeholder which will be resolved to an

   139                                 actual configuration by the platform when a session is opened. Depending

   140                                 on the platform the selection may generate a popup dialog asking the user

   141                                 for his preferred choice.

   142     \value Invalid              The configuration is invalid.

   143 */

   144 

   145 /*!

   146     \enum QNetworkConfiguration::StateFlag

   147 

   148     Specifies the configuration states.

   149 

   150     \value Undefined    This state is used for transient configurations such as newly discovered

   151                         WLANs for which the user has not actually created a configuration yet.

   152     \value Defined      Defined configurations are known to the system but are not immediately

   153                         usable (e.g. a configured WLAN is not within range or the Ethernet cable

   154                         is currently not plugged into the machine).

   155     \value Discovered   A discovered configuration can be immediately used to create a new

   156                         QNetworkSession. An example of a discovered configuration could be a WLAN

   157                         which is within in range. If the device moves out of range the discovered

   158                         flag is dropped. A second example is a GPRS configuration which generally

   159                         remains discovered for as long as the device has network coverage. A

   160                         configuration that has this state is also in state

   161                         QNetworkConfiguration::Defined. If the configuration is a service network

   162                         this flag is set if at least one of the underlying access points

   163                         configurations has the Discovered state.

   164     \value Active       The configuration is currently used by an open network session

   165                         (see \l QNetworkSession::isOpen()). However this does not mean that the

   166                         current process is the entity that created the open session. It merely

   167                         indicates that if a new QNetworkSession were to be constructed based on

   168                         this configuration \l QNetworkSession::state() would return

   169                         \l QNetworkSession::Connected. This state implies the

   170                         QNetworkConfiguration::Discovered state.

   171 */

   172 

   173 /*!

   174     \enum QNetworkConfiguration::Purpose

   175 

   176     Specifies the purpose of the configuration.

   177 

   178     \value UnknownPurpose           The configuration doesn't specify any purpose. This is the default value.

   179     \value PublicPurpose            The configuration can be used for general purpose internet access.

   180     \value PrivatePurpose           The configuration is suitable to access a private network such as an office Intranet.

   181     \value ServiceSpecificPurpose   The configuration can be used for operator specific services (e.g.

   182                                     receiving MMS messages or content streaming).

   183 */

   184 

   185 /*!

   186     Constructs an invalid configuration object.

   187 

   188     \sa isValid()

   189 */

   190 QNetworkConfiguration::QNetworkConfiguration()

   191     : d(0)

   192 {

   193 }

   194 

   195 /*!

   196     Creates a copy of the QNetworkConfiguration object contained in \a other.

   197 */

   198 QNetworkConfiguration::QNetworkConfiguration(const QNetworkConfiguration& other)

   199     : d(other.d)

   200 {

   201 }

   202 

   203 /*!

   204     Copies the content of the QNetworkConfiguration object contained in \a other into this one.

   205 */

   206 QNetworkConfiguration& QNetworkConfiguration::operator=(const QNetworkConfiguration& other)

   207 {

   208     d = other.d;

   209     return *this;

   210 }

   211 

   212 /*!

   213     Frees the resources associated with the QNetworkConfiguration object.

   214 */

   215 QNetworkConfiguration::~QNetworkConfiguration()

   216 {

   217 }

   218 

   219 /*!

   220     Returns true, if this configuration is the same as the \a other

   221     configuration given; otherwise returns false.

   222 */

   223 bool QNetworkConfiguration::operator==(const QNetworkConfiguration& other) const

   224 {

   225     if (!d)

   226         return !other.d;

   227 

   228     if (!other.d)

   229         return false;

   230 

   231     return (d == other.d);

   232 }

   233 

   234 /*!

   235     \fn bool QNetworkConfiguration::operator!=(const QNetworkConfiguration& other) const

   236 

   237     Returns true if this configuration is not the same as the \a other

   238     configuration given; otherwise returns false.

   239 */

   240 

   241 /*!

   242     Returns the user visible name of this configuration.

   243 

   244     The name may either be the name of the underlying access point or the

   245     name for service network that this configuration represents.

   246 */

   247 QString QNetworkConfiguration::name() const

   248 {

   249     if (!d)

   250         return QString();

   251 

   252     QMutexLocker locker(&d->mutex);

   253     return d->name;

   254 }

   255 

   256 /*!

   257     Returns the unique and platform specific identifier for this network configuration;

   258     otherwise an empty string.

   259 */

   260 QString QNetworkConfiguration::identifier() const

   261 {

   262     if (!d)

   263         return QString();

   264 

   265     QMutexLocker locker(&d->mutex);

   266     return d->id;

   267 }

   268 

   269 /*!

   270     Returns the type of the configuration.

   271 

   272     A configuration can represent a single access point configuration or

   273     a set of access point configurations. Such a set is called service network.

   274     A configuration that is based on a service network can potentially support

   275     roaming of network sessions.

   276 */

   277 QNetworkConfiguration::Type QNetworkConfiguration::type() const

   278 {

   279     if (!d)

   280         return QNetworkConfiguration::Invalid;

   281 

   282     QMutexLocker locker(&d->mutex);

   283     return d->type;

   284 }

   285 

   286 /*!

   287     Returns true if this QNetworkConfiguration object is valid.

   288     A configuration may become invalid if the user deletes the configuration or

   289     the configuration was default-constructed.

   290 

   291     The addition and removal of configurations can be monitored via the

   292     QNetworkConfigurationManager.

   293 

   294     \sa QNetworkConfigurationManager

   295 */

   296 bool QNetworkConfiguration::isValid() const

   297 {

   298     if (!d)

   299         return false;

   300 

   301     QMutexLocker locker(&d->mutex);

   302     return d->isValid;

   303 }

   304 

   305 /*!

   306     Returns the current state of the configuration.

   307 */

   308 QNetworkConfiguration::StateFlags QNetworkConfiguration::state() const

   309 {

   310     if (!d)

   311         return QNetworkConfiguration::Undefined;

   312 

   313     QMutexLocker locker(&d->mutex);

   314     return d->state;

   315 }

   316 

   317 /*!

   318     Returns the purpose of this configuration.

   319 

   320     The purpose field may be used to programmatically determine the

   321     purpose of a configuration. Such information is usually part of the

   322     access point or service network meta data.

   323 */

   324 QNetworkConfiguration::Purpose QNetworkConfiguration::purpose() const

   325 {

   326     if (!d)

   327         return QNetworkConfiguration::UnknownPurpose;

   328 

   329     QMutexLocker locker(&d->mutex);

   330     return d->purpose;

   331 }

   332 

   333 /*!

   334     Returns true if this configuration supports roaming; otherwise false.

   335 */

   336 bool QNetworkConfiguration::isRoamingAvailable() const

   337 {

   338     if (!d)

   339         return false;

   340 

   341     QMutexLocker locker(&d->mutex);

   342     return d->roamingSupported;

   343 }

   344 

   345 /*!

   346     Returns all sub configurations of this network configuration.

   347     Only network configurations of type \l ServiceNetwork can have children. Otherwise

   348     this function returns an empty list.

   349 */

   350 QList<QNetworkConfiguration> QNetworkConfiguration::children() const

   351 {

   352     QList<QNetworkConfiguration> results;

   353 

   354     if (type() != QNetworkConfiguration::ServiceNetwork || !isValid())

   355         return results;

   356 

   357     QMutexLocker locker(&d->mutex);

   358 

   359     QMutableListIterator<QNetworkConfigurationPrivatePointer> iter(d->serviceNetworkMembers);

   360     while (iter.hasNext()) {

   361         QNetworkConfigurationPrivatePointer p = iter.next();

   362 

   363         //if we have an invalid member get rid of it -> was deleted earlier on

   364         {

   365             QMutexLocker childLocker(&p->mutex);

   366 

   367             if (!p->isValid) {

   368                 iter.remove();

   369                 continue;

   370             }

   371         }

   372 

   373         QNetworkConfiguration item;

   374         item.d = p;

   375         results << item;

   376     }

   377 

   378     return results;

   379 }

   380 

   381 /*!

   382     Returns the type of bearer. The string is not translated and

   383     therefore can not be shown to the user. The subsequent table presents the currently known

   384     bearer types:

   385 

   386     \table

   387         \header 

   388             \o Value

   389             \o Description

   390         \row

   391             \o Unknown

   392             \o The session is based on an unknown or unspecified bearer type.

   393         \row

   394             \o Ethernet

   395             \o The session is based on Ethernet.

   396         \row

   397             \o WLAN

   398             \o The session is based on Wireless LAN.

   399         \row

   400             \o 2G

   401             \o The session uses CSD, GPRS, HSCSD, EDGE or cdmaOne.

   402         \row 

   403             \o CDMA2000

   404             \o The session uses CDMA.

   405         \row

   406             \o WCDMA

   407             \o The session uses W-CDMA/UMTS.

   408         \row

   409             \o HSPA

   410             \o The session uses High Speed Packet Access.

   411         \row

   412             \o Bluetooth

   413             \o The session uses Bluetooth.

   414         \row

   415             \o WiMAX

   416             \o The session uses WiMAX.

   417     \endtable

   418 

   419     This function returns an empty string if this is an invalid configuration,

   420     a network configuration of type \l QNetworkConfiguration::ServiceNetwork or

   421     \l QNetworkConfiguration::UserChoice.

   422 */

   423 QString QNetworkConfiguration::bearerName() const

   424 {

   425     if (!isValid())

   426         return QString();

   427 

   428     return d->bearerName();

   429 }

   430 

   431 

   432 QT_END_NAMESPACE

   433