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 | |
48 | QT_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 | */ |
216 | QNetworkConfiguration::QNetworkConfiguration() |
217 | : d(nullptr) |
218 | { |
219 | } |
220 | |
221 | /*! |
222 | Creates a copy of the QNetworkConfiguration object contained in \a other. |
223 | */ |
224 | QNetworkConfiguration::QNetworkConfiguration(const QNetworkConfiguration &other) |
225 | : d(other.d) |
226 | { |
227 | } |
228 | |
229 | /*! |
230 | Frees the resources associated with the QNetworkConfiguration object. |
231 | */ |
232 | QNetworkConfiguration::~QNetworkConfiguration() |
233 | { |
234 | } |
235 | |
236 | /*! |
237 | Copies the content of the QNetworkConfiguration object contained in \a other into this one. |
238 | */ |
239 | QNetworkConfiguration &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 | */ |
257 | bool 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 | */ |
275 | QString 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 | */ |
288 | QString 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 | */ |
305 | QNetworkConfiguration::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 | */ |
324 | bool 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 | */ |
340 | int 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 | */ |
364 | bool 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 | */ |
376 | QNetworkConfiguration::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 | */ |
392 | QNetworkConfiguration::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 | */ |
404 | bool 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 | */ |
420 | QList<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 | */ |
435 | QNetworkConfiguration::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 | */ |
471 | QNetworkConfiguration::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 | */ |
556 | QString 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 | |
598 | QT_END_NAMESPACE |
599 | |
600 | #endif |
601 | |