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 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 "qnetworkconfiguration.h" |
|
43 |
|
44 #ifdef Q_OS_SYMBIAN |
|
45 #include "qnetworkconfiguration_s60_p.h" |
|
46 #elif defined(Q_WS_MAEMO_6) || defined(Q_WS_MAEMO_5) |
|
47 #include "qnetworkconfiguration_maemo_p.h" |
|
48 #else |
|
49 #include "qnetworkconfiguration_p.h" |
|
50 #endif |
|
51 |
|
52 QTM_BEGIN_NAMESPACE |
|
53 |
|
54 /*! |
|
55 \class QNetworkConfiguration |
|
56 |
|
57 \brief The QNetworkConfiguration class provides an abstraction of one or more access point configurations. |
|
58 |
|
59 \inmodule QtNetwork |
|
60 \ingroup bearer |
|
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 looses 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 phone 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 Constructs an invalid configuration object. |
|
192 |
|
193 \sa isValid() |
|
194 */ |
|
195 QNetworkConfiguration::QNetworkConfiguration() |
|
196 : d(0) |
|
197 { |
|
198 } |
|
199 |
|
200 /*! |
|
201 Creates a copy of the QNetworkConfiguration object contained in \a other. |
|
202 */ |
|
203 QNetworkConfiguration::QNetworkConfiguration(const QNetworkConfiguration& other) |
|
204 : d(other.d) |
|
205 { |
|
206 } |
|
207 |
|
208 /*! |
|
209 Copies the content of the QNetworkConfiguration object contained in \a other into this one. |
|
210 */ |
|
211 QNetworkConfiguration& QNetworkConfiguration::operator=(const QNetworkConfiguration& other) |
|
212 { |
|
213 d = other.d; |
|
214 return *this; |
|
215 } |
|
216 |
|
217 /*! |
|
218 Frees the resources associated with the QNetworkConfiguration object. |
|
219 */ |
|
220 QNetworkConfiguration::~QNetworkConfiguration() |
|
221 { |
|
222 } |
|
223 |
|
224 /*! |
|
225 Returns true, if this configuration is the same as the \a other |
|
226 configuration given; otherwise returns false. |
|
227 */ |
|
228 bool QNetworkConfiguration::operator==(const QNetworkConfiguration& other) const |
|
229 { |
|
230 if (!d) |
|
231 return !other.d; |
|
232 |
|
233 if (!other.d) |
|
234 return false; |
|
235 |
|
236 return (d == other.d); |
|
237 } |
|
238 |
|
239 /*! |
|
240 \fn bool QNetworkConfiguration::operator!=(const QNetworkConfiguration& other) const |
|
241 |
|
242 Returns true if this configuration is not the same as the \a other |
|
243 configuration given; otherwise returns false. |
|
244 */ |
|
245 |
|
246 /*! |
|
247 Returns the user visible name of this configuration. |
|
248 |
|
249 The name may either be the name of the underlying access point or the |
|
250 name for service network that this configuration represents. |
|
251 */ |
|
252 QString QNetworkConfiguration::name() const |
|
253 { |
|
254 return d ? d->name : QString(); |
|
255 } |
|
256 |
|
257 /*! |
|
258 Returns the unique and platform specific identifier for this network configuration; |
|
259 otherwise an empty string. |
|
260 */ |
|
261 QString QNetworkConfiguration::identifier() const |
|
262 { |
|
263 return d ? d->id : QString(); |
|
264 } |
|
265 |
|
266 /*! |
|
267 Returns the type of the configuration. |
|
268 |
|
269 A configuration can represent a single access point configuration or |
|
270 a set of access point configurations. Such a set is called service network. |
|
271 A configuration that is based on a service network can potentially support |
|
272 roaming of network sessions. |
|
273 */ |
|
274 QNetworkConfiguration::Type QNetworkConfiguration::type() const |
|
275 { |
|
276 return d ? d->type : QNetworkConfiguration::Invalid; |
|
277 } |
|
278 |
|
279 /*! |
|
280 Returns true if this QNetworkConfiguration object is valid. |
|
281 A configuration may become invalid if the user deletes the configuration or |
|
282 the configuration was default-constructed. |
|
283 |
|
284 The addition and removal of configurations can be monitored via the |
|
285 QNetworkConfigurationManager. |
|
286 |
|
287 \sa QNetworkConfigurationManager |
|
288 */ |
|
289 bool QNetworkConfiguration::isValid() const |
|
290 { |
|
291 return d ? d->isValid : false; |
|
292 } |
|
293 |
|
294 /*! |
|
295 Returns the current state of the configuration. |
|
296 */ |
|
297 QNetworkConfiguration::StateFlags QNetworkConfiguration::state() const |
|
298 { |
|
299 return d ? d->state : QNetworkConfiguration::Undefined; |
|
300 } |
|
301 |
|
302 /*! |
|
303 Returns the purpose of this configuration. |
|
304 |
|
305 The purpose field may be used to programmatically determine the |
|
306 purpose of a configuration. Such information is usually part of the |
|
307 access point or service network meta data. |
|
308 */ |
|
309 QNetworkConfiguration::Purpose QNetworkConfiguration::purpose() const |
|
310 { |
|
311 return d ? d->purpose : QNetworkConfiguration::UnknownPurpose; |
|
312 } |
|
313 |
|
314 /*! |
|
315 Returns true if this configuration supports roaming; otherwise false. |
|
316 */ |
|
317 bool QNetworkConfiguration::isRoamingAvailable() const |
|
318 { |
|
319 return d ? d->roamingSupported : false; |
|
320 } |
|
321 |
|
322 /*! |
|
323 Returns all sub configurations of this network configuration. |
|
324 Only network configurations of type \l ServiceNetwork can have children. Otherwise |
|
325 this function returns an empty list. |
|
326 */ |
|
327 QList<QNetworkConfiguration> QNetworkConfiguration::children() const |
|
328 { |
|
329 QList<QNetworkConfiguration> results; |
|
330 if (type() != QNetworkConfiguration::ServiceNetwork || !isValid() ) |
|
331 return results; |
|
332 |
|
333 QMutableListIterator<QExplicitlySharedDataPointer<QNetworkConfigurationPrivate> > iter(d->serviceNetworkMembers); |
|
334 QExplicitlySharedDataPointer<QNetworkConfigurationPrivate> p(0); |
|
335 while(iter.hasNext()) { |
|
336 p = iter.next(); |
|
337 //if we have an invalid member get rid of it -> was deleted earlier on |
|
338 if (!p->isValid) |
|
339 iter.remove(); |
|
340 |
|
341 QNetworkConfiguration item; |
|
342 item.d = p; |
|
343 results << item; |
|
344 } |
|
345 |
|
346 return results; |
|
347 } |
|
348 |
|
349 /*! |
|
350 Returns the type of bearer. The string is not translated and |
|
351 therefore can not be shown to the user. The subsequent table presents the currently known |
|
352 bearer types: |
|
353 |
|
354 \table |
|
355 \header |
|
356 \o Value |
|
357 \o Description |
|
358 \row |
|
359 \o Unknown |
|
360 \o The session is based on an unknown or unspecified bearer type. |
|
361 \row |
|
362 \o Ethernet |
|
363 \o The session is based on Ethernet. |
|
364 \row |
|
365 \o WLAN |
|
366 \o The session is based on Wireless LAN. |
|
367 \row |
|
368 \o 2G |
|
369 \o The session uses CSD, GPRS, HSCSD, EDGE or cdmaOne. |
|
370 \row |
|
371 \o CDMA2000 |
|
372 \o The session uses CDMA. |
|
373 \row |
|
374 \o WCDMA |
|
375 \o The session uses W-CDMA/UMTS. |
|
376 \row |
|
377 \o HSPA |
|
378 \o The session uses High Speed Packet Access. |
|
379 \row |
|
380 \o Bluetooth |
|
381 \o The session uses Bluetooth. |
|
382 \row |
|
383 \o WiMAX |
|
384 \o The session uses WiMAX. |
|
385 \endtable |
|
386 |
|
387 This function returns an empty string if this is an invalid configuration, |
|
388 a network configuration of type \l QNetworkConfiguration::ServiceNetwork or |
|
389 \l QNetworkConfiguration::UserChoice. |
|
390 */ |
|
391 QString QNetworkConfiguration::bearerName() const |
|
392 { |
|
393 if (!isValid()) |
|
394 return QString(); |
|
395 |
|
396 return d->bearerName(); |
|
397 } |
|
398 |
|
399 |
|
400 QTM_END_NAMESPACE |
|
401 |
|