1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtNetwork module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include <QtNetwork/private/qtnetworkglobal_p.h>
41
42#include "qnetworkconfiguration.h"
43#include "qnetworkconfiguration_p.h"
44#include <QDebug>
45
46#ifndef QT_NO_BEARERMANAGEMENT
47
48QT_BEGIN_NAMESPACE
49
50/*!
51 \class QNetworkConfiguration
52 \obsolete
53
54 \brief The QNetworkConfiguration class provides an abstraction of one or more access point configurations.
55
56 \since 4.7
57
58 \inmodule QtNetwork
59 \ingroup network
60 \ingroup shared
61
62 QNetworkConfiguration encapsulates a single access point or service network.
63 In most cases a single access point configuration can be mapped to one network
64 interface. However a single network interface may not always map to only one
65 access point configuration. Multiple configurations for the same
66 network device may enable multiple access points. An example
67 device that could exhibit such a configuration might be a
68 Smartphone which allows the user to manage multiple WLAN
69 configurations while the device itself has only one WLAN network device.
70
71 The QNetworkConfiguration also supports the concept of service networks.
72 This concept allows the grouping of multiple access point configurations
73 into one entity. Such a group is called service network and can be
74 beneficial in cases whereby a network session to a
75 particular destination network is required (e.g. a company network).
76 When using a service network the user doesn't usually care which one of the
77 connectivity options is chosen (e.g. corporate WLAN or VPN via GPRS)
78 as long as he can reach the company's target server. Depending
79 on the current position and time some of the access points that make
80 up the service network may not even be available. Furthermore
81 automated access point roaming can be enabled which enables the device
82 to change the network interface configuration dynamically while maintaining
83 the applications connection to the target network. It allows adaption
84 to the changing environment and may enable optimization with regards to
85 cost, speed or other network parameters.
86
87 Special configurations of type UserChoice provide a placeholder configuration which is
88 resolved to an actual network configuration by the platform when a
89 \l {QNetworkSession}{session} is \l {QNetworkSession::open()}{opened}. Not all platforms
90 support the concept of a user choice configuration.
91
92 \section1 Configuration States
93
94 The list of available configurations can be obtained via
95 QNetworkConfigurationManager::allConfigurations(). A configuration can have
96 multiple states. The \l Defined configuration state indicates that the configuration
97 is stored on the device. However the configuration is not yet ready to be activated
98 as e.g. a WLAN may not be available at the current time.
99
100 The \l Discovered state implies that the configuration is \l Defined and
101 the outside conditions are such that the configuration can be used immediately
102 to open a new network session. An example of such an outside condition may be
103 that the Ethernet cable is actually connected to the device or that the WLAN
104 with the specified SSID is in range.
105
106 The \l Active state implies that the configuration is \l Discovered. A configuration
107 in this state is currently being used by an application. The underlying network
108 interface has a valid IP configuration and can transfer IP packets between the
109 device and the target network.
110
111 The \l Undefined state indicates that the system has knowledge of possible target
112 networks but cannot actually use that knowledge to connect to it. An example
113 for such a state could be an encrypted WLAN that has been discovered
114 but the user hasn't actually saved a configuration including the required password
115 which would allow the device to connect to it.
116
117 Depending on the type of configuration some states are transient in nature. A GPRS/UMTS
118 connection may almost always be \l Discovered if the GSM/UMTS network is available.
119 However if the GSM/UMTS network loses the connection the associated configuration may change its state
120 from \l Discovered to \l Defined as well. A similar use case might be triggered by
121 WLAN availability. QNetworkConfigurationManager::updateConfigurations() can be used to
122 manually trigger updates of states. Note that some platforms do not require such updates
123 as they implicitly change the state once it has been discovered. If the state of a
124 configuration changes all related QNetworkConfiguration instances change their state automatically.
125
126 \sa QNetworkSession, QNetworkConfigurationManager
127*/
128
129/*!
130 \enum QNetworkConfiguration::Type
131
132 This enum describes the type of configuration.
133
134 \value InternetAccessPoint The configuration specifies the details for a single access point.
135 Note that configurations of type InternetAccessPoint may be part
136 of other QNetworkConfigurations of type ServiceNetwork.
137 \value ServiceNetwork The configuration is based on a group of QNetworkConfigurations of
138 type InternetAccessPoint. All group members can reach the same
139 target network. This type of configuration is a mandatory
140 requirement for roaming enabled network sessions. On some
141 platforms this form of configuration may also be called Service
142 Network Access Point (SNAP).
143 \value UserChoice The configuration is a placeholder which will be resolved to an
144 actual configuration by the platform when a session is opened. Depending
145 on the platform the selection may generate a popup dialog asking the user
146 for his preferred choice.
147 \value Invalid The configuration is invalid.
148*/
149
150/*!
151 \enum QNetworkConfiguration::StateFlag
152
153 Specifies the configuration states.
154
155 \value Undefined This state is used for transient configurations such as newly discovered
156 WLANs for which the user has not actually created a configuration yet.
157 \value Defined Defined configurations are known to the system but are not immediately
158 usable (e.g. a configured WLAN is not within range or the Ethernet cable
159 is currently not plugged into the machine).
160 \value Discovered A discovered configuration can be immediately used to create a new
161 QNetworkSession. An example of a discovered configuration could be a WLAN
162 which is within in range. If the device moves out of range the discovered
163 flag is dropped. A second example is a GPRS configuration which generally
164 remains discovered for as long as the device has network coverage. A
165 configuration that has this state is also in state
166 QNetworkConfiguration::Defined. If the configuration is a service network
167 this flag is set if at least one of the underlying access points
168 configurations has the Discovered state.
169 \value Active The configuration is currently used by an open network session
170 (see \l QNetworkSession::isOpen()). However this does not mean that the
171 current process is the entity that created the open session. It merely
172 indicates that if a new QNetworkSession were to be constructed based on
173 this configuration \l QNetworkSession::state() would return
174 \l QNetworkSession::Connected. This state implies the
175 QNetworkConfiguration::Discovered state.
176*/
177
178/*!
179 \enum QNetworkConfiguration::Purpose
180
181 Specifies the purpose of the configuration.
182
183 \value UnknownPurpose The configuration doesn't specify any purpose. This is the default value.
184 \value PublicPurpose The configuration can be used for general purpose internet access.
185 \value PrivatePurpose The configuration is suitable to access a private network such as an office Intranet.
186 \value ServiceSpecificPurpose The configuration can be used for operator specific services (e.g.
187 receiving MMS messages or content streaming).
188*/
189
190/*!
191 \enum QNetworkConfiguration::BearerType
192
193 Specifies the type of bearer used by a configuration.
194
195 \value BearerUnknown The type of bearer is unknown or unspecified. The bearerTypeName()
196 function may return additional information.
197 \value BearerEthernet The configuration is for an Ethernet interfaces.
198 \value BearerWLAN The configuration is for a Wireless LAN interface.
199 \value Bearer2G The configuration is for a CSD, GPRS, HSCSD, EDGE or cdmaOne interface.
200 \value Bearer3G The configuration is for a 3G interface.
201 \value Bearer4G The configuration is for a 4G interface.
202 \value BearerCDMA2000 The configuration is for CDMA interface.
203 \value BearerWCDMA The configuration is for W-CDMA/UMTS interface.
204 \value BearerHSPA The configuration is for High Speed Packet Access (HSPA) interface.
205 \value BearerBluetooth The configuration is for a Bluetooth interface.
206 \value BearerWiMAX The configuration is for a WiMAX interface.
207 \value BearerEVDO The configuration is for an EVDO (3G) interface.
208 \value BearerLTE The configuration is for a LTE (4G) interface.
209*/
210
211/*!
212 Constructs an invalid configuration object.
213
214 \sa isValid()
215*/
216QNetworkConfiguration::QNetworkConfiguration()
217 : d(nullptr)
218{
219}
220
221/*!
222 Creates a copy of the QNetworkConfiguration object contained in \a other.
223*/
224QNetworkConfiguration::QNetworkConfiguration(const QNetworkConfiguration &other)
225 : d(other.d)
226{
227}
228
229/*!
230 Frees the resources associated with the QNetworkConfiguration object.
231*/
232QNetworkConfiguration::~QNetworkConfiguration()
233{
234}
235
236/*!
237 Copies the content of the QNetworkConfiguration object contained in \a other into this one.
238*/
239QNetworkConfiguration &QNetworkConfiguration::operator=(const QNetworkConfiguration &other)
240{
241 d = other.d;
242 return *this;
243}
244
245/*!
246 \fn void QNetworkConfiguration::swap(QNetworkConfiguration &other)
247 \since 5.0
248
249 Swaps this network configuration with \a other. This function is
250 very fast and never fails.
251*/
252
253/*!
254 Returns \c true, if this configuration is the same as the \a other
255 configuration given; otherwise returns \c false.
256*/
257bool QNetworkConfiguration::operator==(const QNetworkConfiguration &other) const
258{
259 return (d == other.d);
260}
261
262/*!
263 \fn bool QNetworkConfiguration::operator!=(const QNetworkConfiguration &other) const
264
265 Returns \c true if this configuration is not the same as the \a other
266 configuration given; otherwise returns \c false.
267*/
268
269/*!
270 Returns the user visible name of this configuration.
271
272 The name may either be the name of the underlying access point or the
273 name for service network that this configuration represents.
274*/
275QString QNetworkConfiguration::name() const
276{
277 if (!d)
278 return QString();
279
280 QMutexLocker locker(&d->mutex);
281 return d->name;
282}
283
284/*!
285 Returns the unique and platform specific identifier for this network configuration;
286 otherwise an empty string.
287*/
288QString QNetworkConfiguration::identifier() const
289{
290 if (!d)
291 return QString();
292
293 QMutexLocker locker(&d->mutex);
294 return d->id;
295}
296
297/*!
298 Returns the type of the configuration.
299
300 A configuration can represent a single access point configuration or
301 a set of access point configurations. Such a set is called service network.
302 A configuration that is based on a service network can potentially support
303 roaming of network sessions.
304*/
305QNetworkConfiguration::Type QNetworkConfiguration::type() const
306{
307 if (!d)
308 return QNetworkConfiguration::Invalid;
309
310 QMutexLocker locker(&d->mutex);
311 return d->type;
312}
313
314/*!
315 Returns \c true if this QNetworkConfiguration object is valid.
316 A configuration may become invalid if the user deletes the configuration or
317 the configuration was default-constructed.
318
319 The addition and removal of configurations can be monitored via the
320 QNetworkConfigurationManager.
321
322 \sa QNetworkConfigurationManager
323*/
324bool QNetworkConfiguration::isValid() const
325{
326 if (!d)
327 return false;
328
329 QMutexLocker locker(&d->mutex);
330 return d->isValid;
331}
332
333/*!
334 \since 5.9
335
336 Returns the connect timeout of this configuration.
337
338 \sa setConnectTimeout
339*/
340int QNetworkConfiguration::connectTimeout() const
341{
342 if (!d)
343 return QNetworkConfigurationPrivate::DefaultTimeout;
344 QMutexLocker locker(&d->mutex);
345 return d->timeout;
346}
347
348/*!
349 \since 5.9
350
351 Sets the connect timeout of this configuration to \a timeout.
352 This allows control of the timeout used by \c QAbstractSocket
353 to establish a connection.
354
355 \note \a timeout is in millisecond.
356
357 \warning This will have no effect if the bearer plugin doesn't have
358 the CanStartAndStopInterfaces capability.
359
360 Returns true if succeeded.
361
362 \sa connectTimeout
363*/
364bool QNetworkConfiguration::setConnectTimeout(int timeout)
365{
366 if (!d)
367 return false;
368 QMutexLocker locker(&d->mutex);
369 d->timeout = timeout;
370 return true;
371}
372
373/*!
374 Returns the current state of the configuration.
375*/
376QNetworkConfiguration::StateFlags QNetworkConfiguration::state() const
377{
378 if (!d)
379 return QNetworkConfiguration::Undefined;
380
381 QMutexLocker locker(&d->mutex);
382 return d->state;
383}
384
385/*!
386 Returns the purpose of this configuration.
387
388 The purpose field may be used to programmatically determine the
389 purpose of a configuration. Such information is usually part of the
390 access point or service network meta data.
391*/
392QNetworkConfiguration::Purpose QNetworkConfiguration::purpose() const
393{
394 if (!d)
395 return QNetworkConfiguration::UnknownPurpose;
396
397 QMutexLocker locker(&d->mutex);
398 return d->purpose;
399}
400
401/*!
402 Returns \c true if this configuration supports roaming; otherwise false.
403*/
404bool QNetworkConfiguration::isRoamingAvailable() const
405{
406 if (!d)
407 return false;
408
409 QMutexLocker locker(&d->mutex);
410 return d->roamingSupported;
411}
412
413/*!
414 Returns all sub configurations of this network configuration in priority order. The first sub
415 configuration in the list has the highest priority.
416
417 Only network configurations of type \l ServiceNetwork can have children. Otherwise this
418 function returns an empty list.
419*/
420QList<QNetworkConfiguration> QNetworkConfiguration::children() const
421{
422 return {};
423}
424
425/*!
426 Returns the type of bearer used by this network configuration.
427
428 If the bearer type is \l {QNetworkConfiguration::BearerUnknown}{unknown} the bearerTypeName()
429 function can be used to retrieve a textural type name for the bearer.
430
431 An invalid network configuration always returns the BearerUnknown value.
432
433 \sa bearerTypeName(), bearerTypeFamily()
434*/
435QNetworkConfiguration::BearerType QNetworkConfiguration::bearerType() const
436{
437 if (!isValid())
438 return BearerUnknown;
439
440 QMutexLocker locker(&d->mutex);
441 return d->bearerType;
442}
443
444/*!
445 \since 5.2
446
447 Returns the bearer type family used by this network configuration.
448 The following table lists how bearerType() values map to
449 bearerTypeFamily() values:
450
451 \table
452 \header
453 \li bearer type
454 \li bearer type family
455 \row
456 \li BearerUnknown, Bearer2G, BearerEthernet, BearerWLAN,
457 BearerBluetooth
458 \li (same type)
459 \row
460 \li BearerCDMA2000, BearerEVDO, BearerWCDMA, BearerHSPA, Bearer3G
461 \li Bearer3G
462 \row
463 \li BearerWiMAX, BearerLTE, Bearer4G
464 \li Bearer4G
465 \endtable
466
467 An invalid network configuration always returns the BearerUnknown value.
468
469 \sa bearerType(), bearerTypeName()
470*/
471QNetworkConfiguration::BearerType QNetworkConfiguration::bearerTypeFamily() const
472{
473 QNetworkConfiguration::BearerType type = bearerType();
474 switch (type) {
475 case QNetworkConfiguration::BearerUnknown: // fallthrough
476 case QNetworkConfiguration::Bearer2G: // fallthrough
477 case QNetworkConfiguration::BearerEthernet: // fallthrough
478 case QNetworkConfiguration::BearerWLAN: // fallthrough
479 case QNetworkConfiguration::BearerBluetooth:
480 return type;
481 case QNetworkConfiguration::BearerCDMA2000: // fallthrough
482 case QNetworkConfiguration::BearerEVDO: // fallthrough
483 case QNetworkConfiguration::BearerWCDMA: // fallthrough
484 case QNetworkConfiguration::BearerHSPA: // fallthrough
485 case QNetworkConfiguration::Bearer3G:
486 return QNetworkConfiguration::Bearer3G;
487 case QNetworkConfiguration::BearerWiMAX: // fallthrough
488 case QNetworkConfiguration::BearerLTE: // fallthrough
489 case QNetworkConfiguration::Bearer4G:
490 return QNetworkConfiguration::Bearer4G;
491 default:
492 qWarning() << "unknown bearer type" << type;
493 return QNetworkConfiguration::BearerUnknown;
494 }
495}
496/*!
497 Returns the type of bearer used by this network configuration as a string.
498
499 The string is not translated and therefore cannot be shown to the user. The subsequent table
500 shows the fixed mappings between BearerType and the bearer type name for known types. If the
501 BearerType is unknown this function may return additional information if it is available;
502 otherwise an empty string will be returned.
503
504 \table
505 \header
506 \li BearerType
507 \li Value
508 \row
509 \li BearerUnknown
510 \li The session is based on an unknown or unspecified bearer type. The value of the
511 string returned describes the bearer type.
512 \row
513 \li BearerEthernet
514 \li Ethernet
515 \row
516 \li BearerWLAN
517 \li WLAN
518 \row
519 \li Bearer2G
520 \li 2G
521 \row
522 \li Bearer3G
523 \li 3G
524 \row
525 \li Bearer4G
526 \li 4G
527 \row
528 \li BearerCDMA2000
529 \li CDMA2000
530 \row
531 \li BearerWCDMA
532 \li WCDMA
533 \row
534 \li BearerHSPA
535 \li HSPA
536 \row
537 \li BearerBluetooth
538 \li Bluetooth
539 \row
540 \li BearerWiMAX
541 \li WiMAX
542 \row
543 \li BearerEVDO
544 \li EVDO
545 \row
546 \li BearerLTE
547 \li LTE
548 \endtable
549
550 This function returns an empty string if this is an invalid configuration, a network
551 configuration of type \l QNetworkConfiguration::ServiceNetwork or
552 \l QNetworkConfiguration::UserChoice.
553
554 \sa bearerType(), bearerTypeFamily()
555*/
556QString QNetworkConfiguration::bearerTypeName() const
557{
558 if (!isValid())
559 return QString();
560
561 QMutexLocker locker(&d->mutex);
562
563 if (d->type == QNetworkConfiguration::ServiceNetwork ||
564 d->type == QNetworkConfiguration::UserChoice)
565 return QString();
566
567 switch (d->bearerType) {
568 case BearerEthernet:
569 return QStringLiteral("Ethernet");
570 case BearerWLAN:
571 return QStringLiteral("WLAN");
572 case Bearer2G:
573 return QStringLiteral("2G");
574 case Bearer3G:
575 return QStringLiteral("3G");
576 case Bearer4G:
577 return QStringLiteral("4G");
578 case BearerCDMA2000:
579 return QStringLiteral("CDMA2000");
580 case BearerWCDMA:
581 return QStringLiteral("WCDMA");
582 case BearerHSPA:
583 return QStringLiteral("HSPA");
584 case BearerBluetooth:
585 return QStringLiteral("Bluetooth");
586 case BearerWiMAX:
587 return QStringLiteral("WiMAX");
588 case BearerEVDO:
589 return QStringLiteral("EVDO");
590 case BearerLTE:
591 return QStringLiteral("LTE");
592 case BearerUnknown:
593 break;
594 }
595 return QStringLiteral("Unknown");
596}
597
598QT_END_NAMESPACE
599
600#endif
601

source code of qtbase/src/network/bearer/qnetworkconfiguration.cpp