NetworkManagerQt

device.h
1 /*
2  SPDX-FileCopyrightText: 2008, 2011 Will Stephenson <[email protected]>
3  SPDX-FileCopyrightText: 2011-2013 Lamarque V. Souza <[email protected]>
4  SPDX-FileCopyrightText: 2013 Daniel Nicoletti <[email protected]>
5  SPDX-FileCopyrightText: 2013 Jan Grulich <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
8 */
9 
10 #ifndef NETWORKMANAGERQT_DEVICE_H
11 #define NETWORKMANAGERQT_DEVICE_H
12 
13 #include <QObject>
14 #include <QSharedPointer>
15 
16 #include "activeconnection.h"
17 #include "devicestatistics.h"
18 #include "dhcp4config.h"
19 #include "dhcp6config.h"
20 #include "generictypes.h"
21 #include "ipconfig.h"
22 #include <networkmanagerqt/networkmanagerqt_export.h>
23 
24 namespace NetworkManager
25 {
26 class DevicePrivate;
27 class DeviceStateReason;
28 class DeviceStateReasonPrivate;
29 
30 /**
31  * This class represents a common device interface
32  */
33 class NETWORKMANAGERQT_EXPORT Device : public QObject
34 {
35  Q_OBJECT
36 
37  Q_PROPERTY(QString uni READ uni)
38  Q_PROPERTY(QString interfaceName READ interfaceName)
39  Q_PROPERTY(QString ipInterfaceName READ ipInterfaceName)
40  Q_PROPERTY(QString driver READ driver)
41  Q_PROPERTY(QString driverVersion READ driverVersion)
42  Q_PROPERTY(QString firmwareVersion READ firmwareVersion)
43  Q_PROPERTY(QVariant genericCapabilities READ capabilitiesV)
44  Q_PROPERTY(QHostAddress ipV4Address READ ipV4Address)
45  Q_PROPERTY(bool managed READ managed)
46  Q_PROPERTY(uint mtu READ mtu)
47  Q_PROPERTY(bool nmPluginMissing READ nmPluginMissing)
48  Q_PROPERTY(MeteredStatus metered READ metered)
49  Q_PROPERTY(QString udi READ udi)
50  Q_PROPERTY(bool firmwareMissing READ firmwareMissing)
51  Q_PROPERTY(bool autoconnect READ autoconnect WRITE setAutoconnect)
52  Q_PROPERTY(DeviceStateReason stateReason READ stateReason)
53  Q_PROPERTY(State state READ state)
54  Q_PROPERTY(NetworkManager::DeviceStatistics::Ptr deviceStatistics READ deviceStatistics)
55 
56 public:
58  typedef QList<Ptr> List;
59  /**
60  * Device connection states describe the possible states of a
61  * network connection from the user's point of view. For
62  * simplicity, states from several different layers are present -
63  * this is a high level view
64  */
65  enum State {
66  UnknownState = 0, /**< The device is in an unknown state */
67  Unmanaged = 10, /**< The device is recognized but not managed by NetworkManager */
68  Unavailable = 20, /**< The device cannot be used (carrier off, rfkill, etc) */
69  Disconnected = 30, /**< The device is not connected */
70  Preparing = 40, /**< The device is preparing to connect */
71  ConfiguringHardware = 50, /**< The device is being configured */
72  NeedAuth = 60, /**< The device is awaiting secrets necessary to continue connection */
73  ConfiguringIp = 70, /**< The IP settings of the device are being requested and configured */
74  CheckingIp = 80, /**< The device's IP connectivity ability is being determined */
75  WaitingForSecondaries = 90, /**< The device is waiting for secondary connections to be activated */
76  Activated = 100, /**< The device is active */
77  Deactivating = 110, /**< The device's network connection is being torn down */
78  Failed = 120, /**< The device is in a failure state following an attempt to activate it */
79  };
80  Q_ENUM(State)
81 
82  /**
83  * Enums describing the reason for a connection state change
84  * @note StateChangeReasons NewActivation, ParentChanged, ParentManagedChanged are available in runtime NM >= 1.0.4
85  */
87  UnknownReason = 0,
88  NoReason = 1,
89  NowManagedReason = 2,
90  NowUnmanagedReason = 3,
91  ConfigFailedReason = 4,
92  ConfigUnavailableReason = 5,
93  ConfigExpiredReason = 6,
94  NoSecretsReason = 7,
95  AuthSupplicantDisconnectReason = 8,
96  AuthSupplicantConfigFailedReason = 9,
97  AuthSupplicantFailedReason = 10,
98  AuthSupplicantTimeoutReason = 11,
99  PppStartFailedReason = 12,
100  PppDisconnectReason = 13,
101  PppFailedReason = 14,
102  DhcpStartFailedReason = 15,
103  DhcpErrorReason = 16,
104  DhcpFailedReason = 17,
105  SharedStartFailedReason = 18,
106  SharedFailedReason = 19,
107  AutoIpStartFailedReason = 20,
108  AutoIpErrorReason = 21,
109  AutoIpFailedReason = 22,
110  ModemBusyReason = 23,
111  ModemNoDialToneReason = 24,
112  ModemNoCarrierReason = 25,
113  ModemDialTimeoutReason = 26,
114  ModemDialFailedReason = 27,
115  ModemInitFailedReason = 28,
116  GsmApnSelectFailedReason = 29,
117  GsmNotSearchingReason = 30,
118  GsmRegistrationDeniedReason = 31,
119  GsmRegistrationTimeoutReason = 32,
120  GsmRegistrationFailedReason = 33,
121  GsmPinCheckFailedReason = 34,
122  FirmwareMissingReason = 35,
123  DeviceRemovedReason = 36,
124  SleepingReason = 37,
125  ConnectionRemovedReason = 38,
126  UserRequestedReason = 39,
127  CarrierReason = 40,
128  ConnectionAssumedReason = 41,
129  SupplicantAvailableReason = 42,
130  ModemNotFoundReason = 43,
131  BluetoothFailedReason = 44,
132  GsmSimNotInserted = 45,
133  GsmSimPinRequired = 46,
134  GsmSimPukRequired = 47,
135  GsmSimWrong = 48,
136  InfiniBandMode = 49,
137  DependencyFailed = 50,
138  Br2684Failed = 51,
139  ModemManagerUnavailable = 52,
140  SsidNotFound = 53,
141  SecondaryConnectionFailed = 54,
142  DcbFcoeFailed = 55,
143  TeamdControlFailed = 56,
144  ModemFailed = 57,
145  ModemAvailable = 58,
146  SimPinIncorrect = 59,
147  NewActivation = 60,
148  ParentChanged = 61,
149  ParentManagedChanged = 62,
150  Reserved = 65536,
151  };
152  Q_ENUM(StateChangeReason)
153 
155  UnknownStatus = 0, /**< The device metered status is unknown. */
156  Yes = 1, /**< The device is metered and the value was statically set. */
157  No = 2, /**< The device is not metered and the value was statically set. */
158  GuessYes = 3, /**< The device is metered and the value was guessed. */
159  GuessNo = 4, /**< The device is not metered and the value was guessed. */
160  };
161  Q_ENUM(MeteredStatus)
162 
163  /**
164  * Possible device capabilities
165  */
166  enum Capability {
167  IsManageable = 0x1, /**< denotes that the device can be controlled by this API */
168  SupportsCarrierDetect = 0x2, /**< the device informs us when it is plugged in to the medium */
169  };
170  Q_ENUM(Capability)
171  Q_DECLARE_FLAGS(Capabilities, Capability)
172  Q_FLAG(Capabilities)
173 
174  /**
175  * Device type
176  */
177  enum Type {
178  UnknownType = NM_DEVICE_TYPE_UNKNOWN, /**< Unknown device type */
179  Ethernet = NM_DEVICE_TYPE_ETHERNET, /**< Ieee8023 wired ethernet */
180  Wifi = NM_DEVICE_TYPE_WIFI, /**< the Ieee80211 family of wireless networks */
181  Unused1 = NM_DEVICE_TYPE_UNUSED1, /**< Currently unused */
182  Unused2 = NM_DEVICE_TYPE_UNUSED2, /**< Currently unused */
183  Bluetooth = NM_DEVICE_TYPE_BT, /**< network bluetooth device (usually a cell phone) */
184  OlpcMesh = NM_DEVICE_TYPE_OLPC_MESH, /**< OLPC Mesh networking device */
185  Wimax = NM_DEVICE_TYPE_WIMAX, /**< WiMax WWAN technology */
186  Modem = NM_DEVICE_TYPE_MODEM, /**< POTS, GSM, CDMA or LTE modems */
187  InfiniBand = NM_DEVICE_TYPE_INFINIBAND, /**< Infiniband network device */
188  Bond = NM_DEVICE_TYPE_BOND, /**< Bond virtual device */
189  Vlan = NM_DEVICE_TYPE_VLAN, /**< Vlan virtual device */
190  Adsl = NM_DEVICE_TYPE_ADSL, /**< ADSL modem device */
191  Bridge = NM_DEVICE_TYPE_BRIDGE, /**< Bridge virtual device */
192  Generic = NM_DEVICE_TYPE_GENERIC, /**< Generic device @since 1.0.0 */
193  Team = NM_DEVICE_TYPE_TEAM, /**< Team master device @since 1.0.0 */
194  Gre, /**< Gre virtual device @since 1.2.0, @deprecated use IpTunnel instead*/
195  MacVlan, /**< MacVlan virtual device @since 1.2.0 */
196  Tun, /**< Tun virtual device @since 1.2.0 */
197  Veth, /**< Veth virtual device @since 1.2.0 */
198  IpTunnel, /**< IP Tunneling Device @since 1.2.0 */
199  VxLan, /**< Vxlan Device @since 1.2.0 */
200  MacSec, /**< MacSec Device @since 1.6.0 */
201  Dummy, /**< Dummy Device @since 1.8.0 */
202  Ppp, /**< Ppp Device @since 1.10 */
203  OvsInterface, /**< OvsInterface Device @since 1.10 */
204  OvsPort, /**< OvsPort Device @since 1.10 */
205  OvsBridge, /**< OvsBridge Device @since 1.10 */
206  Wpan, /**< Wpan Device @since 1.14 */
207  Lowpan, /**< Lowpan Device @since 1.14 */
208  WireGuard, /**< WireGuard Device @since 1.14 */
209  WifiP2P, /**< WifiP2P Device @since 1.16 */
210  };
211  Q_ENUM(Type)
212  Q_DECLARE_FLAGS(Types, Type)
213  Q_FLAG(Types)
214 
215  /**
216  * Creates a new device object.
217  *
218  * @param path UNI of the device
219  */
220  explicit Device(const QString &path, QObject *parent = nullptr);
221  /**
222  * Destroys a device object.
223  */
224  ~Device() override;
225  /**
226  * Retrieves the interface type. This is a virtual function that will return the
227  * proper type of all sub-classes.
228  *
229  * @returns the NetworkManager::Device::Type that corresponds to this device.
230  */
231  virtual Type type() const;
232  /**
233  * Retrieves the Unique Network Identifier (UNI) of the device.
234  * This identifier is unique for each network and network interface in the system.
235  *
236  * @returns the Unique Network Identifier of the current device
237  */
238  QString uni() const;
239  /**
240  * The current active connection for this device
241  *
242  * @returns A valid ActiveConnection object or NULL if no active connection was found
243  */
244  NetworkManager::ActiveConnection::Ptr activeConnection() const;
245  /**
246  * Returns available connections for this device
247  *
248  * @returns List of availables connection
249  */
250  Connection::List availableConnections();
251  /**
252  * The system name for the network device
253  */
254  QString interfaceName() const;
255  /**
256  * The name of the device's data interface when available. This property
257  * may not refer to the actual data interface until the device has
258  * successfully established a data connection, indicated by the device's
259  * state() becoming ACTIVATED.
260  */
261  QString ipInterfaceName() const;
262  /**
263  * Handle for the system driver controlling this network interface
264  */
265  QString driver() const;
266  /**
267  * The driver version.
268  */
269  QString driverVersion() const;
270  /**
271  * The firmware version.
272  */
273  QString firmwareVersion() const;
274  /**
275  * Reapplies connection settings on the interface.
276  */
277  QDBusPendingReply<> reapplyConnection(const NMVariantMapMap &connection, qulonglong version_id, uint flags);
278  /**
279  * Disconnects a device and prevents the device from automatically
280  * activating further connections without user intervention.
281  */
282  QDBusPendingReply<> disconnectInterface();
283  /**
284  * Deletes a software device from NetworkManager and removes the interface from the system.
285  * The method returns an error when called for a hardware device.
286  *
287  * @since 5.8.0
288  *
289  */
290  QDBusPendingReply<> deleteInterface();
291  /**
292  * returns the current IPv4 address without the prefix
293  * \sa ipV4Config()
294  * \sa ipV6Config()
295  * @deprecated
296  */
297  QHostAddress ipV4Address() const;
298  /**
299  * Get the current IPv4 configuration of this device.
300  * Only valid when device is Activated.
301  */
302  IpConfig ipV4Config() const;
303  /**
304  * Get the current IPv6 configuration of this device.
305  * Only valid when device is Activated.
306  */
307  IpConfig ipV6Config() const;
308 
309  /**
310  * Get the DHCP options returned by the DHCP server
311  * or a null pointer if the device is not Activated or does not
312  * use DHCP configuration.
313  */
314  Dhcp4Config::Ptr dhcp4Config() const;
315 
316  /**
317  * Get the DHCP options returned by the DHCP server
318  * or a null pointer if the device is not Activated or does not
319  * use DHCP configuration.
320  */
321  Dhcp6Config::Ptr dhcp6Config() const;
322 
323  /**
324  * Retrieves the activation status of this network interface.
325  *
326  * @return true if this network interface is active, false otherwise
327  */
328  bool isActive() const;
329 
330  /**
331  * Retrieves the device is valid.
332  *
333  * @return true if this device interface is valid, false otherwise
334  */
335  bool isValid() const;
336 
337  /**
338  * Retrieves the current state of the device.
339  * This is a high level view of the device. It is user oriented, so
340  * actually it provides state coming from different layers.
341  *
342  * @return the current connection state
343  * @see Device::State
344  */
345  State state() const;
346  /**
347  * Retrieves the maximum speed as reported by the device.
348  * Note that this is only a design related piece of information, and that
349  * the device might not reach this maximum.
350  *
351  * @return the device's maximum speed
352  */
353  int designSpeed() const;
354  /**
355  * Retrieves the capabilities supported by this device.
356  *
357  * @return the capabilities of the device
358  */
359  Capabilities capabilities() const;
360  QVariant capabilitiesV() const;
361  /**
362  * Is the device currently being managed by NetworkManager?
363  */
364  bool managed() const;
365  /**
366  * Is the firmware needed by the device missing?
367  */
368  bool firmwareMissing() const;
369  /**
370  * If the device is allowed to autoconnect.
371  */
372  bool autoconnect() const;
373  /**
374  * The current state and reason for changing to that state.
375  */
376  DeviceStateReason stateReason() const;
377  /**
378  * Retrieves the Unique Device Identifier (UDI) of the device.
379  * This identifier is unique for each device in the system.
380  */
381  QString udi() const;
382 
383  /**
384  * @return If non-empty, an (opaque) indicator of the physical network
385  * port associated with the device. This can be used to recognize
386  * when two seemingly-separate hardware devices are actually just
387  * different virtual interfaces to the same physical port.
388  *
389  * @since 0.9.9.0
390  */
391  QString physicalPortId() const;
392  /**
393  * The device MTU (maximum transmission unit)
394  * @since 0.9.9.0
395  *
396  */
397  uint mtu() const;
398 
399  /**
400  * @return If TRUE, indicates the NetworkManager plugin for the device is likely
401  * missing or misconfigured.
402  * @since 5.14.0
403  */
404  bool nmPluginMissing() const;
405 
406  /**
407  * @return Whether the amount of traffic flowing through the device is
408  * subject to limitations, for example set by service providers.
409  * @since 5.14.0
410  */
411  MeteredStatus metered() const;
412 
413  /**
414  * If true, indicates the device is allowed to autoconnect.
415  * If false, manual intervention is required before the device
416  * will automatically connect to a known network, such as activating
417  * a connection using the device, or setting this property to @p true.
418  */
419  void setAutoconnect(bool autoconnect);
420 
421  /**
422  * Returns Device Statistics interface
423  */
424  DeviceStatistics::Ptr deviceStatistics() const;
425 
426  /**
427  * Retrieves a specialized interface to interact with the device corresponding
428  * to a given device interface.
429  *
430  * @returns a pointer to the device interface if it exists, @p 0 otherwise
431  */
432  template<class DevIface>
433  DevIface *as()
434  {
435  return qobject_cast<DevIface *>(this);
436  }
437 
438  /**
439  * Retrieves a specialized interface to interact with the device corresponding
440  * to a given device interface.
441  *
442  * @returns a pointer to the device interface if it exists, 0 otherwise
443  */
444  template<class DevIface>
445  const DevIface *as() const
446  {
447  return qobject_cast<const DevIface *>(this);
448  }
449 
450 Q_SIGNALS:
451  /**
452  * This signal is emitted when the device's link status changed.
453  *
454  * @param newstate the new state of the connection
455  * @param oldstate the previous state of the connection
456  * @param reason the reason for the state change, if any. ReasonNone where the backend
457  * provides no reason.
458  * @see Device::State
459  * @see Device::StateChangeReason
460  */
462 
463  /**
464  * Emitted when the autoconnect of this network has changed.
465  */
466  void activeConnectionChanged();
467 
468  /**
469  * Emitted when the autoconnect of this network has changed.
470  */
471  void autoconnectChanged();
472 
473  /**
474  * Emitted when the list of avaiable connections of this network has changed.
475  */
476  void availableConnectionChanged();
477 
478  /**
479  * Emitted when a new connection is available
480  */
481  void availableConnectionAppeared(const QString &connection);
482 
483  /**
484  * Emitted when the connection is no longer available
485  */
486  void availableConnectionDisappeared(const QString &connection);
487 
488  /**
489  * Emitted when the capabilities of this network has changed.
490  */
491  void capabilitiesChanged();
492 
493  /**
494  * Emitted when the DHCP configuration for IPv4 of this network has changed.
495  */
496  void dhcp4ConfigChanged();
497 
498  /**
499  * Emitted when the DHCP configuration for IPv6 of this network has changed.
500  */
501  void dhcp6ConfigChanged();
502 
503  /**
504  * Emitted when the driver of this network has changed.
505  */
506  void driverChanged();
507 
508  /**
509  * Emitted when the driver version of this network has changed.
510  */
511  void driverVersionChanged();
512 
513  /**
514  * Emitted when the firmware missing state of this network has changed.
515  */
516  void firmwareMissingChanged();
517 
518  /**
519  * Emitted when the firmware version of this network has changed.
520  */
521  void firmwareVersionChanged();
522 
523  /**
524  * Emitted when the interface name of this network has changed.
525  */
526  void interfaceNameChanged();
527 
528  /**
529  * Emitted when the IPv4 address of this network has changed.
530  */
531  void ipV4AddressChanged();
532 
533  /**
534  * Emitted when the IPv4 configuration of this network has changed.
535  */
536  void ipV4ConfigChanged();
537 
538  /**
539  * Emitted when the IPv6 configuration of this network has changed.
540  */
541  void ipV6ConfigChanged();
542 
543  /**
544  * Emitted when the ip interface name of this network has changed.
545  */
546  void ipInterfaceChanged();
547 
548  /**
549  * Emitted when the managed state of this network has changed.
550  */
551  void managedChanged();
552 
553  /**
554  * Emitted when the physical port ID changes.
555  * @see physicalPortId()
556  * @since 0.9.9.0
557  */
558  void physicalPortIdChanged();
559 
560  /**
561  * Emitted when the maximum transmission unit has changed
562  * @since 0.9.9.0
563  */
564  void mtuChanged();
565 
566  /**
567  * Emitted when NmPluginMissing property has changed
568  * @since 5.14.0
569  * @see nmPluginMissing
570  */
571  void nmPluginMissingChanged(bool nmPluginMissing);
572 
573  /**
574  * Emitted when metered property has changed
575  * @since 5.14.0
576  * @see metered
577  */
578  void meteredChanged(MeteredStatus metered);
579 
580  /**
581  * Emitted when the connection state of this network has changed.
582  */
583  void connectionStateChanged();
584 
585  /**
586  * Emitted when the state reason of this network has changed.
587  */
588  void stateReasonChanged();
589 
590  /**
591  * Emitted when the Unique Device Identifier of this device has changed.
592  */
593  void udiChanged();
594 
595 protected:
596  NETWORKMANAGERQT_NO_EXPORT Device(DevicePrivate &dd, QObject *parent);
597 
598  DevicePrivate *const d_ptr;
599 
600 private:
601  Q_DECLARE_PRIVATE(Device)
602 };
603 
604 Q_DECLARE_OPERATORS_FOR_FLAGS(Device::Capabilities)
605 Q_DECLARE_OPERATORS_FOR_FLAGS(Device::Types)
606 
607 class NETWORKMANAGERQT_EXPORT DeviceStateReason
608 {
609 public:
610  DeviceStateReason(Device::State state, Device::StateChangeReason reason);
611  DeviceStateReason(const DeviceStateReason &);
612  ~DeviceStateReason();
613  Device::State state() const;
614  Device::StateChangeReason reason() const;
615  DeviceStateReason &operator=(const DeviceStateReason &);
616 
617 private:
618  Q_DECLARE_PRIVATE(DeviceStateReason)
619 
620  DeviceStateReasonPrivate *const d_ptr;
621 };
622 
623 }
624 
625 #endif
State
Device connection states describe the possible states of a network connection from the user's point o...
Definition: device.h:65
@ Veth
Veth virtual device.
Definition: device.h:197
This class represents IP configuration.
Definition: ipconfig.h:27
This class represents a common device interface.
Definition: device.h:33
@ WifiP2P
WifiP2P Device.
Definition: device.h:209
StateChangeReason
Enums describing the reason for a connection state change.
Definition: device.h:86
@ VxLan
Vxlan Device.
Definition: device.h:199
@ Dummy
Dummy Device.
Definition: device.h:201
@ OvsPort
OvsPort Device.
Definition: device.h:204
Capability
Possible device capabilities.
Definition: device.h:166
This class allows querying the underlying system to discover the available network interfaces and rea...
Definition: accesspoint.h:20
@ Lowpan
Lowpan Device.
Definition: device.h:207
@ IpTunnel
IP Tunneling Device.
Definition: device.h:198
@ Wpan
Wpan Device.
Definition: device.h:206
@ Ppp
Ppp Device.
Definition: device.h:202
@ MacSec
MacSec Device.
Definition: device.h:200
NETWORKMANAGERQT_EXPORT NetworkManager::Device::MeteredStatus metered()
Definition: manager.cpp:1149
Type
Device type.
Definition: device.h:177
@ OvsInterface
OvsInterface Device.
Definition: device.h:203
DevIface * as()
Retrieves a specialized interface to interact with the device corresponding to a given device interfa...
Definition: device.h:433
const DevIface * as() const
Retrieves a specialized interface to interact with the device corresponding to a given device interfa...
Definition: device.h:445
@ Disconnected
the system is not connected to any network
Definition: manager.h:35
@ Tun
Tun virtual device.
Definition: device.h:196
@ OvsBridge
OvsBridge Device.
Definition: device.h:205
@ WireGuard
WireGuard Device.
Definition: device.h:208
@ MacVlan
MacVlan virtual device.
Definition: device.h:195
@ Gre
Gre virtual device.
Definition: device.h:194
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 04:03:51 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.