File indexing completed on 2024-12-01 09:58:16

0001 /*
0002     SPDX-FileCopyrightText: 2008, 2011 Will Stephenson <wstephenson@kde.org>
0003     SPDX-FileCopyrightText: 2011-2013 Lamarque V. Souza <lamarque@kde.org>
0004     SPDX-FileCopyrightText: 2013 Daniel Nicoletti <dantti12@gmail.com>
0005     SPDX-FileCopyrightText: 2013 Jan Grulich <jgrulich@redhat.com>
0006 
0007     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0008 */
0009 
0010 #ifndef NETWORKMANAGERQT_DEVICE_H
0011 #define NETWORKMANAGERQT_DEVICE_H
0012 
0013 #include <QObject>
0014 #include <QSharedPointer>
0015 
0016 #include "activeconnection.h"
0017 #include "devicestatistics.h"
0018 #include "dhcp4config.h"
0019 #include "dhcp6config.h"
0020 #include "generictypes.h"
0021 #include "ipconfig.h"
0022 #include <networkmanagerqt/networkmanagerqt_export.h>
0023 
0024 namespace NetworkManager
0025 {
0026 class DevicePrivate;
0027 class DeviceStateReason;
0028 class DeviceStateReasonPrivate;
0029 
0030 /**
0031  * This class represents a common device interface
0032  */
0033 class NETWORKMANAGERQT_EXPORT Device : public QObject
0034 {
0035     Q_OBJECT
0036 
0037     Q_PROPERTY(QString uni READ uni)
0038     Q_PROPERTY(QString interfaceName READ interfaceName)
0039     Q_PROPERTY(QString ipInterfaceName READ ipInterfaceName)
0040     Q_PROPERTY(QString driver READ driver)
0041     Q_PROPERTY(QString driverVersion READ driverVersion)
0042     Q_PROPERTY(QString firmwareVersion READ firmwareVersion)
0043     Q_PROPERTY(QVariant genericCapabilities READ capabilitiesV)
0044     Q_PROPERTY(QHostAddress ipV4Address READ ipV4Address)
0045     Q_PROPERTY(bool managed READ managed)
0046     Q_PROPERTY(uint mtu READ mtu)
0047     Q_PROPERTY(bool nmPluginMissing READ nmPluginMissing)
0048     Q_PROPERTY(MeteredStatus metered READ metered)
0049     Q_PROPERTY(QString udi READ udi)
0050     Q_PROPERTY(bool firmwareMissing READ firmwareMissing)
0051     Q_PROPERTY(bool autoconnect READ autoconnect WRITE setAutoconnect)
0052     Q_PROPERTY(DeviceStateReason stateReason READ stateReason)
0053     Q_PROPERTY(State state READ state)
0054     Q_PROPERTY(NetworkManager::DeviceStatistics::Ptr deviceStatistics READ deviceStatistics)
0055 
0056 public:
0057     typedef QSharedPointer<Device> Ptr;
0058     typedef QList<Ptr> List;
0059     /**
0060      * Device connection states describe the possible states of a
0061      * network connection from the user's point of view.  For
0062      * simplicity, states from several different layers are present -
0063      * this is a high level view
0064      */
0065     enum State {
0066         UnknownState = 0, /**< The device is in an unknown state */
0067         Unmanaged = 10, /**< The device is recognized but not managed by NetworkManager */
0068         Unavailable = 20, /**< The device cannot be used (carrier off, rfkill, etc) */
0069         Disconnected = 30, /**< The device is not connected */
0070         Preparing = 40, /**< The device is preparing to connect */
0071         ConfiguringHardware = 50, /**< The device is being configured */
0072         NeedAuth = 60, /**< The device is awaiting secrets necessary to continue connection */
0073         ConfiguringIp = 70, /**< The IP settings of the device are being requested and configured */
0074         CheckingIp = 80, /**< The device's IP connectivity ability is being determined */
0075         WaitingForSecondaries = 90, /**< The device is waiting for secondary connections to be activated */
0076         Activated = 100, /**< The device is active */
0077         Deactivating = 110, /**< The device's network connection is being torn down */
0078         Failed = 120, /**< The device is in a failure state following an attempt to activate it */
0079     };
0080     Q_ENUM(State)
0081 
0082     /**
0083      * Enums describing the reason for a connection state change
0084      * @note StateChangeReasons NewActivation, ParentChanged, ParentManagedChanged are available in runtime NM >= 1.0.4
0085      */
0086     enum StateChangeReason {
0087         UnknownReason = 0,
0088         NoReason = 1,
0089         NowManagedReason = 2,
0090         NowUnmanagedReason = 3,
0091         ConfigFailedReason = 4,
0092         ConfigUnavailableReason = 5,
0093         ConfigExpiredReason = 6,
0094         NoSecretsReason = 7,
0095         AuthSupplicantDisconnectReason = 8,
0096         AuthSupplicantConfigFailedReason = 9,
0097         AuthSupplicantFailedReason = 10,
0098         AuthSupplicantTimeoutReason = 11,
0099         PppStartFailedReason = 12,
0100         PppDisconnectReason = 13,
0101         PppFailedReason = 14,
0102         DhcpStartFailedReason = 15,
0103         DhcpErrorReason = 16,
0104         DhcpFailedReason = 17,
0105         SharedStartFailedReason = 18,
0106         SharedFailedReason = 19,
0107         AutoIpStartFailedReason = 20,
0108         AutoIpErrorReason = 21,
0109         AutoIpFailedReason = 22,
0110         ModemBusyReason = 23,
0111         ModemNoDialToneReason = 24,
0112         ModemNoCarrierReason = 25,
0113         ModemDialTimeoutReason = 26,
0114         ModemDialFailedReason = 27,
0115         ModemInitFailedReason = 28,
0116         GsmApnSelectFailedReason = 29,
0117         GsmNotSearchingReason = 30,
0118         GsmRegistrationDeniedReason = 31,
0119         GsmRegistrationTimeoutReason = 32,
0120         GsmRegistrationFailedReason = 33,
0121         GsmPinCheckFailedReason = 34,
0122         FirmwareMissingReason = 35,
0123         DeviceRemovedReason = 36,
0124         SleepingReason = 37,
0125         ConnectionRemovedReason = 38,
0126         UserRequestedReason = 39,
0127         CarrierReason = 40,
0128         ConnectionAssumedReason = 41,
0129         SupplicantAvailableReason = 42,
0130         ModemNotFoundReason = 43,
0131         BluetoothFailedReason = 44,
0132         GsmSimNotInserted = 45,
0133         GsmSimPinRequired = 46,
0134         GsmSimPukRequired = 47,
0135         GsmSimWrong = 48,
0136         InfiniBandMode = 49,
0137         DependencyFailed = 50,
0138         Br2684Failed = 51,
0139         ModemManagerUnavailable = 52,
0140         SsidNotFound = 53,
0141         SecondaryConnectionFailed = 54,
0142         DcbFcoeFailed = 55,
0143         TeamdControlFailed = 56,
0144         ModemFailed = 57,
0145         ModemAvailable = 58,
0146         SimPinIncorrect = 59,
0147         NewActivation = 60,
0148         ParentChanged = 61,
0149         ParentManagedChanged = 62,
0150         Reserved = 65536,
0151     };
0152     Q_ENUM(StateChangeReason)
0153 
0154     enum MeteredStatus {
0155         UnknownStatus = 0, /**< The device metered status is unknown. */
0156         Yes = 1, /**< The device is metered and the value was statically set. */
0157         No = 2, /**< The device is not metered and the value was statically set. */
0158         GuessYes = 3, /**< The device is metered and the value was guessed. */
0159         GuessNo = 4, /**< The device is not metered and the value was guessed. */
0160     };
0161     Q_ENUM(MeteredStatus)
0162 
0163     /**
0164      * Possible device capabilities
0165      */
0166     enum Capability {
0167         IsManageable = 0x1, /**< denotes that the device can be controlled by this API */
0168         SupportsCarrierDetect = 0x2, /**< the device informs us when it is plugged in to the medium */
0169     };
0170     Q_ENUM(Capability)
0171     Q_DECLARE_FLAGS(Capabilities, Capability)
0172     Q_FLAG(Capabilities)
0173 
0174     /**
0175      * Device type
0176      */
0177     enum Type {
0178         UnknownType = NM_DEVICE_TYPE_UNKNOWN, /**< Unknown device type */
0179         Ethernet = NM_DEVICE_TYPE_ETHERNET, /**< Ieee8023 wired ethernet */
0180         Wifi = NM_DEVICE_TYPE_WIFI, /**< the Ieee80211 family of wireless networks */
0181         Unused1 = NM_DEVICE_TYPE_UNUSED1, /**< Currently unused */
0182         Unused2 = NM_DEVICE_TYPE_UNUSED2, /**< Currently unused */
0183         Bluetooth = NM_DEVICE_TYPE_BT, /**< network bluetooth device (usually a cell phone) */
0184         OlpcMesh = NM_DEVICE_TYPE_OLPC_MESH, /**< OLPC Mesh networking device */
0185         Wimax = NM_DEVICE_TYPE_WIMAX, /**< WiMax WWAN technology */
0186         Modem = NM_DEVICE_TYPE_MODEM, /**< POTS, GSM, CDMA or LTE modems */
0187         InfiniBand = NM_DEVICE_TYPE_INFINIBAND, /**< Infiniband network device */
0188         Bond = NM_DEVICE_TYPE_BOND, /**< Bond virtual device */
0189         Vlan = NM_DEVICE_TYPE_VLAN, /**< Vlan virtual device */
0190         Adsl = NM_DEVICE_TYPE_ADSL, /**< ADSL modem device */
0191         Bridge = NM_DEVICE_TYPE_BRIDGE, /**< Bridge virtual device */
0192         Generic = NM_DEVICE_TYPE_GENERIC, /**< Generic device @since 1.0.0 */
0193         Team = NM_DEVICE_TYPE_TEAM, /**< Team master device @since 1.0.0 */
0194         Gre, /**< Gre virtual device @since 1.2.0, @deprecated use IpTunnel instead*/
0195         MacVlan, /**< MacVlan virtual device @since 1.2.0 */
0196         Tun, /**< Tun virtual device @since 1.2.0 */
0197         Veth, /**< Veth virtual device @since 1.2.0 */
0198         IpTunnel, /**< IP Tunneling Device @since 1.2.0 */
0199         VxLan, /**< Vxlan Device @since 1.2.0 */
0200         MacSec, /**< MacSec Device @since 1.6.0 */
0201         Dummy, /**< Dummy Device @since 1.8.0 */
0202         Ppp, /**< Ppp Device @since 1.10 */
0203         OvsInterface, /**< OvsInterface Device @since 1.10 */
0204         OvsPort, /**< OvsPort Device @since 1.10 */
0205         OvsBridge, /**< OvsBridge Device @since 1.10 */
0206         Wpan, /**< Wpan Device @since 1.14 */
0207         Lowpan, /**< Lowpan Device @since 1.14 */
0208         WireGuard, /**< WireGuard Device @since 1.14 */
0209         WifiP2P, /**< WifiP2P Device @since 1.16 */
0210     };
0211     Q_ENUM(Type)
0212     Q_DECLARE_FLAGS(Types, Type)
0213     Q_FLAG(Types)
0214 
0215     /**
0216      * Creates a new device object.
0217      *
0218      * @param path UNI of the device
0219      */
0220     explicit Device(const QString &path, QObject *parent = nullptr);
0221     /**
0222      * Destroys a device object.
0223      */
0224     ~Device() override;
0225     /**
0226      * Retrieves the interface type.  This is a virtual function that will return the
0227      * proper type of all sub-classes.
0228      *
0229      * @returns the NetworkManager::Device::Type that corresponds to this device.
0230      */
0231     virtual Type type() const;
0232     /**
0233      * Retrieves the Unique Network Identifier (UNI) of the device.
0234      * This identifier is unique for each network and network interface in the system.
0235      *
0236      * @returns the Unique Network Identifier of the current device
0237      */
0238     QString uni() const;
0239     /**
0240      * The current active connection for this device
0241      *
0242      * @returns A valid ActiveConnection object or NULL if no active connection was found
0243      */
0244     NetworkManager::ActiveConnection::Ptr activeConnection() const;
0245     /**
0246      * Returns available connections for this device
0247      *
0248      * @returns List of availables connection
0249      */
0250     Connection::List availableConnections();
0251     /**
0252      * The system name for the network device
0253      */
0254     QString interfaceName() const;
0255     /**
0256      * The name of the device's data interface when available. This property
0257      * may not refer to the actual data interface until the device has
0258      * successfully established a data connection, indicated by the device's
0259      * state() becoming ACTIVATED.
0260      */
0261     QString ipInterfaceName() const;
0262     /**
0263      * Handle for the system driver controlling this network interface
0264      */
0265     QString driver() const;
0266     /**
0267      * The driver version.
0268      */
0269     QString driverVersion() const;
0270     /**
0271      * The firmware version.
0272      */
0273     QString firmwareVersion() const;
0274     /**
0275      * Reapplies connection settings on the interface.
0276      */
0277     QDBusPendingReply<> reapplyConnection(const NMVariantMapMap &connection, qulonglong version_id, uint flags);
0278     /**
0279      * Disconnects a device and prevents the device from automatically
0280      * activating further connections without user intervention.
0281      */
0282     QDBusPendingReply<> disconnectInterface();
0283     /**
0284      * Deletes a software device from NetworkManager and removes the interface from the system.
0285      * The method returns an error when called for a hardware device.
0286      *
0287      * @since 5.8.0
0288      *
0289      */
0290     QDBusPendingReply<> deleteInterface();
0291     /**
0292      * returns the current IPv4 address without the prefix
0293      * \sa ipV4Config()
0294      * \sa ipV6Config()
0295      * @deprecated
0296      */
0297     QHostAddress ipV4Address() const;
0298     /**
0299      * Get the current IPv4 configuration of this device.
0300      * Only valid when device is Activated.
0301      */
0302     IpConfig ipV4Config() const;
0303     /**
0304      * Get the current IPv6 configuration of this device.
0305      * Only valid when device is Activated.
0306      */
0307     IpConfig ipV6Config() const;
0308 
0309     /**
0310      * Get the DHCP options returned by the DHCP server
0311      * or a null pointer if the device is not Activated or does not
0312      * use DHCP configuration.
0313      */
0314     Dhcp4Config::Ptr dhcp4Config() const;
0315 
0316     /**
0317      * Get the DHCP options returned by the DHCP server
0318      * or a null pointer if the device is not Activated or does not
0319      * use DHCP configuration.
0320      */
0321     Dhcp6Config::Ptr dhcp6Config() const;
0322 
0323     /**
0324      * Retrieves the activation status of this network interface.
0325      *
0326      * @return true if this network interface is active, false otherwise
0327      */
0328     bool isActive() const;
0329 
0330     /**
0331      * Retrieves the device is valid.
0332      *
0333      * @return true if this device interface is valid, false otherwise
0334      */
0335     bool isValid() const;
0336 
0337     /**
0338      * Retrieves the current state of the device.
0339      * This is a high level view of the device. It is user oriented, so
0340      * actually it provides state coming from different layers.
0341      *
0342      * @return the current connection state
0343      * @see Device::State
0344      */
0345     State state() const;
0346     /**
0347      * Retrieves the maximum speed as reported by the device.
0348      * Note that this is only a design related piece of information, and that
0349      * the device might not reach this maximum.
0350      *
0351      * @return the device's maximum speed
0352      */
0353     int designSpeed() const;
0354     /**
0355      * Retrieves the capabilities supported by this device.
0356      *
0357      * @return the capabilities of the device
0358      */
0359     Capabilities capabilities() const;
0360     QVariant capabilitiesV() const;
0361     /**
0362      * Is the device currently being managed by NetworkManager?
0363      */
0364     bool managed() const;
0365     /**
0366      * Is the firmware needed by the device missing?
0367      */
0368     bool firmwareMissing() const;
0369     /**
0370      * If the device is allowed to autoconnect.
0371      */
0372     bool autoconnect() const;
0373     /**
0374      * The current state and reason for changing to that state.
0375      */
0376     DeviceStateReason stateReason() const;
0377     /**
0378      * Retrieves the Unique Device Identifier (UDI) of the device.
0379      * This identifier is unique for each device in the system.
0380      */
0381     QString udi() const;
0382 
0383     /**
0384      * @return If non-empty, an (opaque) indicator of the physical network
0385      * port associated with the device. This can be used to recognize
0386      * when two seemingly-separate hardware devices are actually just
0387      * different virtual interfaces to the same physical port.
0388      *
0389      * @since 0.9.9.0
0390      */
0391     QString physicalPortId() const;
0392     /**
0393      * The device MTU (maximum transmission unit)
0394      * @since 0.9.9.0
0395      *
0396      */
0397     uint mtu() const;
0398 
0399     /**
0400      * @return If TRUE, indicates the NetworkManager plugin for the device is likely
0401      * missing or misconfigured.
0402      * @since 5.14.0
0403      */
0404     bool nmPluginMissing() const;
0405 
0406     /**
0407      * @return Whether the amount of traffic flowing through the device is
0408      * subject to limitations, for example set by service providers.
0409      * @since 5.14.0
0410      */
0411     MeteredStatus metered() const;
0412 
0413     /**
0414      * If true, indicates the device is allowed to autoconnect.
0415      * If false, manual intervention is required before the device
0416      * will automatically connect to a known network, such as activating
0417      * a connection using the device, or setting this property to @p true.
0418      */
0419     void setAutoconnect(bool autoconnect);
0420 
0421     /**
0422      * Returns Device Statistics interface
0423      */
0424     DeviceStatistics::Ptr deviceStatistics() const;
0425 
0426     /**
0427      * Retrieves a specialized interface to interact with the device corresponding
0428      * to a given device interface.
0429      *
0430      * @returns a pointer to the device interface if it exists, @p 0 otherwise
0431      */
0432     template<class DevIface>
0433     DevIface *as()
0434     {
0435         return qobject_cast<DevIface *>(this);
0436     }
0437 
0438     /**
0439      * Retrieves a specialized interface to interact with the device corresponding
0440      * to a given device interface.
0441      *
0442      * @returns a pointer to the device interface if it exists, 0 otherwise
0443      */
0444     template<class DevIface>
0445     const DevIface *as() const
0446     {
0447         return qobject_cast<const DevIface *>(this);
0448     }
0449 
0450 Q_SIGNALS:
0451     /**
0452      * This signal is emitted when the device's link status changed.
0453      *
0454      * @param newstate the new state of the connection
0455      * @param oldstate the previous state of the connection
0456      * @param reason the reason for the state change, if any.  ReasonNone where the backend
0457      * provides no reason.
0458      * @see Device::State
0459      * @see Device::StateChangeReason
0460      */
0461     void stateChanged(NetworkManager::Device::State newstate, NetworkManager::Device::State oldstate, NetworkManager::Device::StateChangeReason reason);
0462 
0463     /**
0464      * Emitted when the autoconnect of this network has changed.
0465      */
0466     void activeConnectionChanged();
0467 
0468     /**
0469      * Emitted when the autoconnect of this network has changed.
0470      */
0471     void autoconnectChanged();
0472 
0473     /**
0474      * Emitted when the list of avaiable connections of this network has changed.
0475      */
0476     void availableConnectionChanged();
0477 
0478     /**
0479      * Emitted when a new connection is available
0480      */
0481     void availableConnectionAppeared(const QString &connection);
0482 
0483     /**
0484      * Emitted when the connection is no longer available
0485      */
0486     void availableConnectionDisappeared(const QString &connection);
0487 
0488     /**
0489      * Emitted when the capabilities of this network has changed.
0490      */
0491     void capabilitiesChanged();
0492 
0493     /**
0494      * Emitted when the DHCP configuration for IPv4 of this network has changed.
0495      */
0496     void dhcp4ConfigChanged();
0497 
0498     /**
0499      * Emitted when the DHCP configuration for IPv6 of this network has changed.
0500      */
0501     void dhcp6ConfigChanged();
0502 
0503     /**
0504      * Emitted when the driver of this network has changed.
0505      */
0506     void driverChanged();
0507 
0508     /**
0509      * Emitted when the driver version of this network has changed.
0510      */
0511     void driverVersionChanged();
0512 
0513     /**
0514      * Emitted when the firmware missing state of this network has changed.
0515      */
0516     void firmwareMissingChanged();
0517 
0518     /**
0519      * Emitted when the firmware version of this network has changed.
0520      */
0521     void firmwareVersionChanged();
0522 
0523     /**
0524      * Emitted when the interface name of this network has changed.
0525      */
0526     void interfaceNameChanged();
0527 
0528     /**
0529      * Emitted when the IPv4 address of this network has changed.
0530      */
0531     void ipV4AddressChanged();
0532 
0533     /**
0534      * Emitted when the IPv4 configuration of this network has changed.
0535      */
0536     void ipV4ConfigChanged();
0537 
0538     /**
0539      * Emitted when the IPv6 configuration of this network has changed.
0540      */
0541     void ipV6ConfigChanged();
0542 
0543     /**
0544      * Emitted when the ip interface name of this network has changed.
0545      */
0546     void ipInterfaceChanged();
0547 
0548     /**
0549      * Emitted when the managed state of this network has changed.
0550      */
0551     void managedChanged();
0552 
0553     /**
0554      * Emitted when the physical port ID changes.
0555      * @see physicalPortId()
0556      * @since 0.9.9.0
0557      */
0558     void physicalPortIdChanged();
0559 
0560     /**
0561      * Emitted when the maximum transmission unit has changed
0562      * @since 0.9.9.0
0563      */
0564     void mtuChanged();
0565 
0566     /**
0567      * Emitted when NmPluginMissing property has changed
0568      * @since 5.14.0
0569      * @see nmPluginMissing
0570      */
0571     void nmPluginMissingChanged(bool nmPluginMissing);
0572 
0573     /**
0574      * Emitted when metered property has changed
0575      * @since 5.14.0
0576      * @see metered
0577      */
0578     void meteredChanged(MeteredStatus metered);
0579 
0580     /**
0581      * Emitted when the connection state of this network has changed.
0582      */
0583     void connectionStateChanged();
0584 
0585     /**
0586      * Emitted when the state reason of this network has changed.
0587      */
0588     void stateReasonChanged();
0589 
0590     /**
0591      * Emitted when the Unique Device Identifier of this device has changed.
0592      */
0593     void udiChanged();
0594 
0595 protected:
0596     NETWORKMANAGERQT_NO_EXPORT Device(DevicePrivate &dd, QObject *parent);
0597 
0598     DevicePrivate *const d_ptr;
0599 
0600 private:
0601     Q_DECLARE_PRIVATE(Device)
0602 };
0603 
0604 Q_DECLARE_OPERATORS_FOR_FLAGS(Device::Capabilities)
0605 Q_DECLARE_OPERATORS_FOR_FLAGS(Device::Types)
0606 
0607 class NETWORKMANAGERQT_EXPORT DeviceStateReason
0608 {
0609 public:
0610     DeviceStateReason(Device::State state, Device::StateChangeReason reason);
0611     DeviceStateReason(const DeviceStateReason &);
0612     ~DeviceStateReason();
0613     Device::State state() const;
0614     Device::StateChangeReason reason() const;
0615     DeviceStateReason &operator=(const DeviceStateReason &);
0616 
0617 private:
0618     Q_DECLARE_PRIVATE(DeviceStateReason)
0619 
0620     DeviceStateReasonPrivate *const d_ptr;
0621 };
0622 
0623 }
0624 
0625 #endif