File indexing completed on 2023-11-26 10:48:37

0001 /*
0002     SPDX-FileCopyrightText: 2008, 2010, 2011 Will Stephenson <wstephenson@kde.org>
0003     SPDX-FileCopyrightText: 2011-2013 Lamarque Souza <lamarque@kde.org>
0004     SPDX-FileCopyrightText: 2013 Jan Grulich <jgrulich@redhat.com>
0005 
0006     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0007 */
0008 
0009 #ifndef NETWORKMANAGERQT_NETWORKMANAGER_H
0010 #define NETWORKMANAGERQT_NETWORKMANAGER_H
0011 
0012 #include <networkmanagerqt/networkmanagerqt_export.h>
0013 
0014 #include "activeconnection.h"
0015 #include "device.h"
0016 #include "dnsconfiguration.h"
0017 
0018 /**
0019  * This class allows querying the underlying system to discover the available
0020  * network interfaces and reachable networks. It has also the
0021  * responsibility to notify when a network interface appears or disappears.
0022  *
0023  * It is the unique entry point for network management. Applications should use
0024  * it to find network interfaces, or to be notified about network related changes.
0025  *
0026  * Note that it is implemented as a singleton
0027  */
0028 namespace NetworkManager
0029 {
0030 Q_NAMESPACE_EXPORT(NETWORKMANAGERQT_EXPORT)
0031 
0032 enum Status {
0033     Unknown, /**< the networking system is not active or unable to report its status - proceed with caution */
0034     Asleep, /**< networking is inactive and all devices are disabled */
0035     Disconnected, /**< the system is not connected to any network */
0036     Disconnecting, /**< the system is breaking the connection */
0037     Connecting, /**< the system is not connected to any network */
0038     ConnectedLinkLocal, /**< a network device is connected, but there is only link-local connectivity */
0039     ConnectedSiteOnly, /**< a network device is connected, but there is only site-local connectivity */
0040     Connected, /**< the system is currently connected to a network */
0041 };
0042 Q_ENUM_NS(Status)
0043 
0044 enum LogLevel {
0045     Error,
0046     Warning,
0047     Info,
0048     Debug,
0049     Trace, /**< = Debug in runtime NM < 0.9.10*/
0050 };
0051 
0052 enum LogDomain {
0053     NoChange,
0054     None,
0055     Hardware,
0056     RFKill,
0057     Ethernet,
0058     WiFi,
0059     Bluetooth,
0060     MobileBroadBand,
0061     DHCP4,
0062     DHCP6,
0063     PPP,
0064     WiFiScan,
0065     IPv4,
0066     IPv6,
0067     AutoIPv4,
0068     DNS,
0069     VPN,
0070     Sharing,
0071     Supplicant,
0072     UserSet,
0073     SysSet,
0074     Suspend,
0075     Core,
0076     Devices,
0077     OLPC,
0078     Wimax /*TODO: mark it deprecated somehow?*/,
0079     Infiniband,
0080     Firewall,
0081     Adsl,
0082     Bond,
0083     Vlan,
0084     Agents,
0085     Settings,
0086     Bridge,
0087     DbusProps,
0088     Team,
0089     ConCheck,
0090     Dcb,
0091     Dispatch,
0092 };
0093 Q_DECLARE_FLAGS(LogDomains, LogDomain)
0094 Q_FLAGS(LogDomain)
0095 
0096 /**
0097  * Describes the network connectivity state.
0098  * @since 0.9.9.0
0099  */
0100 enum Connectivity {
0101     UnknownConnectivity = 0, /**< Network connectivity is unknown. */
0102     NoConnectivity = 1, /**< The host is not connected to any network. */
0103     Portal = 2, /**< The host is behind a captive portal and cannot reach the full Internet. */
0104     Limited = 3, /**< The host is connected to a network, but does not appear to be able to reach the full Internet. */
0105     Full = 4, /**< The host is connected to a network, and appears to be able to reach the full Internet. */
0106 };
0107 Q_ENUM_NS(Connectivity)
0108 
0109 class NETWORKMANAGERQT_EXPORT Notifier : public QObject
0110 {
0111     Q_OBJECT
0112 Q_SIGNALS:
0113     /**
0114      * This signal is emitted when the system's connection state changes
0115      */
0116     void statusChanged(NetworkManager::Status status);
0117     /**
0118      * This signal is emitted when a new network interface is available.
0119      *
0120      * @param uni the network interface identifier
0121      */
0122     void deviceAdded(const QString &uni);
0123     /**
0124      * This signal is emitted when a network interface is not available anymore.
0125      *
0126      * @param uni the network interface identifier
0127      */
0128     void deviceRemoved(const QString &uni);
0129     /**
0130      * This signal is emitted when the status of the wireless changed
0131      */
0132     void wirelessEnabledChanged(bool);
0133     /**
0134      * This signal is emitted when the status of the wireless changed
0135      */
0136     void wwanEnabledChanged(bool);
0137     /**
0138      * This signal is emitted when the status of the wimax changed
0139      *
0140      * @deprecated Wimax support was removed from NetworkManager 1.2
0141      * (never emitted in runtime NM >= 1.2.0).
0142      */
0143     void wimaxEnabledChanged(bool);
0144     /**
0145      * This signal is emitted when the status of the wireless changed
0146      */
0147     void wirelessHardwareEnabledChanged(bool);
0148     /**
0149      * This signal is emitted when the status of the wireless changed
0150      */
0151     void wwanHardwareEnabledChanged(bool);
0152     /**
0153      * This signal is emitted when the status of the wimax hardware changed
0154      *
0155      * @deprecated Wimax support was removed from NetworkManager 1.2
0156      * (never emitted in runtime NM >= 1.2.0).
0157      */
0158     void wimaxHardwareEnabledChanged(bool);
0159     /**
0160      * This signal is emitted when the status of overall networking changed
0161      */
0162     void networkingEnabledChanged(bool);
0163     /**
0164      * This signal is emitted when a new connection was made active
0165      *
0166      * @param path the path of the new connection
0167      */
0168     void activeConnectionAdded(const QString &path);
0169     /**
0170      * This signal is emitted when an active connection is no longer active
0171      *
0172      * @param path the path of the removed connection
0173      */
0174     void activeConnectionRemoved(const QString &path);
0175     /**
0176      * This signal is emitted when the set of active connections changes
0177      */
0178     void activeConnectionsChanged();
0179     /**
0180      * This signal is emitted when the NetworkManager DBus service goes away
0181      */
0182     void serviceDisappeared();
0183     /**
0184      * This signal is emitted when the NetworkManager DBus service appears
0185      */
0186     void serviceAppeared();
0187     /**
0188      * Emitted when the global connectivity changes.
0189      * @since 0.9.9.0
0190      */
0191     void connectivityChanged(NetworkManager::Connectivity connectivity);
0192     /**
0193      * Emitted when the primary connection changes.
0194      * @param uni path of the new primary connection
0195      * @since 0.9.9.0
0196      */
0197     void primaryConnectionChanged(const QString &uni);
0198     /**
0199      * Emitted when the activating connection changes.
0200      * @param uni path of the new activating connection
0201      * @since 0.9.9.0
0202      */
0203     void activatingConnectionChanged(const QString &uni);
0204     /**
0205      * Emitted when the primary connection type changes.
0206      * @param connection type of the new primary connection
0207      * @since 5.8.0
0208      */
0209     void primaryConnectionTypeChanged(NetworkManager::ConnectionSettings::ConnectionType type);
0210 
0211     /**
0212      * Emitted when NM has started/finished its startup sequence
0213      * @since 0.9.9.0
0214      */
0215     void isStartingUpChanged();
0216 
0217     /**
0218      * Emitted when metered property has changed
0219      * @since 5.14.0
0220      * @see metered
0221      */
0222     void meteredChanged(NetworkManager::Device::MeteredStatus metered);
0223 
0224     /**
0225      * Emitted when the global DNS configuration has changed
0226      * @since 5.45.0
0227      * @see globalDnsConfiguration
0228      */
0229     void globalDnsConfigurationChanged(const NetworkManager::DnsConfiguration &configuration);
0230 };
0231 
0232 /**
0233  * Get the NetworkManager version
0234  */
0235 NETWORKMANAGERQT_EXPORT QString version();
0236 /**
0237  * Compares NetworkManager's version to the parameter version.
0238  * returns 1, -1 or 0 if NetworkManager's version is greater, less or equal to parameter.
0239  */
0240 NETWORKMANAGERQT_EXPORT int compareVersion(const QString &version);
0241 /**
0242  * Compares NetworkManager version to x.y.z.
0243  * returns 1, -1 or 0 if NetworkManager's version is greater, less or equal to x.y.z.
0244  */
0245 NETWORKMANAGERQT_EXPORT int compareVersion(const int x, const int y, const int z);
0246 /**
0247  * Checks if NetworkManager version is at least x.y.z
0248  * @return true if NetworkManager's version is greater or equal, false otherwise
0249  **/
0250 NETWORKMANAGERQT_EXPORT bool checkVersion(const int x, const int y, const int z);
0251 /**
0252  * Get the manager connection state
0253  */
0254 NETWORKMANAGERQT_EXPORT NetworkManager::Status status();
0255 /**
0256  * Retrieves the list of all the network interfaces in the system.
0257  * It includes both hardware and virtual devices.
0258  *
0259  * @return the list of network interfaces available in this system
0260  */
0261 NETWORKMANAGERQT_EXPORT Device::List networkInterfaces();
0262 /**
0263  * Find a new NetworkInterface object given its UNI.  This pointer is owned by the Solid
0264  * infrastructure.
0265  *
0266  * @param uni the identifier of the network interface to find
0267  * @return a valid NetworkInterface object if there's a device having the given UNI, an invalid one otherwise
0268  */
0269 NETWORKMANAGERQT_EXPORT Device::Ptr findNetworkInterface(const QString &uni);
0270 /**
0271  * Return the network device referenced by its IP interface name.
0272  * This is not system independent so programs that will use this method will not be portable.
0273  */
0274 NETWORKMANAGERQT_EXPORT Device::Ptr findDeviceByIpFace(const QString &iface);
0275 /**
0276  * Retrieves the status of networking (as a whole) in the system.
0277  * This is distinct from whether the system's networking is online or offline.
0278  * To check that, see @ref status().
0279  *
0280  * @return true if this networking is enabled, false otherwise
0281  */
0282 NETWORKMANAGERQT_EXPORT bool isNetworkingEnabled();
0283 /**
0284  * Retrieves the activation status of wireless networking in the system.
0285  *
0286  * @return true if this wireless networking is enabled, false otherwise
0287  */
0288 NETWORKMANAGERQT_EXPORT bool isWirelessEnabled();
0289 /**
0290  * Retrieves the status of wireless hardware in the system. This is typically
0291  * controlled by a physical switch so there is no way to set this in software.
0292  *
0293  * @return true if this wireless networking is enabled, false otherwise
0294  */
0295 NETWORKMANAGERQT_EXPORT bool isWirelessHardwareEnabled();
0296 /**
0297  * Retrieves the status of wireless broadband (Wireless WAN) in the system.
0298  *
0299  * @return true if this type of wireless networking is enabled, false otherwise
0300  */
0301 NETWORKMANAGERQT_EXPORT bool isWwanEnabled();
0302 /**
0303  * Retrieves the status of wireless broadband (Wireless WAN) hardware in the system. This is typically
0304  * controlled by a physical switch so there is no way to set this in software.
0305  *
0306  * @return true if this broddband hardware is enabled, false otherwise
0307  */
0308 NETWORKMANAGERQT_EXPORT bool isWwanHardwareEnabled();
0309 
0310 /**
0311  * Retrieves the activation status of wimax networking in the system.
0312  *
0313  * @return true if this wimax networking is enabled, false otherwise
0314  *
0315  * @deprecated Wimax support was removed from NetworkManager 1.2
0316  * (always returns false in runtime NM >= 1.2.0).
0317  */
0318 NETWORKMANAGERQT_EXPORT bool isWimaxEnabled();
0319 /**
0320  * Retrieves the status of wimax hardware in the system. This is typically
0321  * controlled by a physical switch so there is no way to set this in software.
0322  *
0323  * @return true if wimax HW networking is enabled, false otherwise
0324  *
0325  * @deprecated Wimax support was removed from NetworkManager 1.2
0326  * (always returns false in runtime NM >= 1.2.0).
0327  */
0328 NETWORKMANAGERQT_EXPORT bool isWimaxHardwareEnabled();
0329 
0330 /**
0331  * Activate a connection using the supplied device.
0332  *
0333  * @param connectionUni unique identifier for the connection to be activated
0334  * @param interfaceUni unique identifier of the network interface to be activated
0335  * @param connectionParameter can be used to specify extra parameters not specific to the NetworkInterface or the connection, eg which AP to use when several
0336  * present with same ESSID in range (because ESSID does not guarantee that the AP is part of the network you want to join!)
0337  */
0338 NETWORKMANAGERQT_EXPORT QDBusPendingReply<QDBusObjectPath>
0339 activateConnection(const QString &connectionUni, const QString &interfaceUni, const QString &connectionParameter);
0340 /**
0341  * Adds a new connection using the given details (if any) as a template (automatically filling in missing settings with the capabilities of the given device and
0342  * specific object), then activate the new connection. Cannot be used for VPN connections at this time.
0343  *
0344  * @param connection connection definition to be added and activated
0345  * @param interfaceUni unique identifier of the network interface to be activated
0346  * @param connectionParameter can be used to specify extra parameters not specific to the NetworkInterface or the connection, eg which AP to use when several
0347  * present with same ESSID in range (because ESSID does not guarantee that the AP is part of the network you want to join!)
0348  */
0349 NETWORKMANAGERQT_EXPORT QDBusPendingReply<QDBusObjectPath, QDBusObjectPath>
0350 addAndActivateConnection(const NMVariantMapMap &connection, const QString &interfaceUni, const QString &connectionParameter);
0351 /**
0352  * Adds a new connection using the given details (if any) as a template (automatically filling in missing settings with the capabilities of the given device and
0353  * specific object), then activate the new connection. Cannot be used for VPN connections at this time.
0354  *
0355  * @param connection connection definition to be added and activated
0356  * @param interfaceUni unique identifier of the network interface to be activated
0357  * @param connectionParameter can be used to specify extra parameters not specific to the NetworkInterface or the connection, eg which AP to use when several
0358  * present with same ESSID in range (because ESSID does not guarantee that the AP is part of the network you want to join!)
0359  * @param options further options for the method call.
0360  *
0361  * This method extends AddAndActivateConnection to allow passing further
0362  * parameters. At this time the following options are supported:
0363  *
0364  *        * persist: A string value of either "disk" (default), "memory" or "volatile". If "memory" is passed, the connection will not be saved to disk. If
0365  * "volatile" is passed, the connection will not be saved to disk and will be destroyed when disconnected.
0366  *        * bind-activation: Bind the activation lifetime. Set to "dbus-name" to automatically disconnect when the requesting process disappears from the bus.
0367  * The default of "none" means the connection is kept activated normally.
0368  *
0369  * NOTE: will call AddAndActivateConnection(connection, interfaceUni, connectionParameter) instead when NetworkManager is older than 1.16, which means that the
0370  * options property is ignored
0371  */
0372 NETWORKMANAGERQT_EXPORT QDBusPendingReply<QDBusObjectPath, QDBusObjectPath, QVariantMap>
0373 addAndActivateConnection2(const NMVariantMapMap &connection, const QString &interfaceUni, const QString &connectionParameter, const QVariantMap &options);
0374 /**
0375  * Deactivate this network interface, if active
0376  *
0377  * @param activeConnection identifier of the connection to deactivate
0378  */
0379 NETWORKMANAGERQT_EXPORT QDBusPendingReply<> deactivateConnection(const QString &activeConnection);
0380 /**
0381  * Access the list of any active connections
0382  *
0383  * @return a list of valid ActiveConnection objects
0384  */
0385 NETWORKMANAGERQT_EXPORT ActiveConnection::List activeConnections();
0386 /**
0387  * Access the list of any active connections paths
0388  *
0389  * @return a list of valid ActiveConnection paths
0390  */
0391 NETWORKMANAGERQT_EXPORT QStringList activeConnectionsPaths();
0392 /**
0393  * Get current logging verbosity level and operations domains
0394  */
0395 NETWORKMANAGERQT_EXPORT QDBusPendingReply<QString, QString> getLogging();
0396 
0397 /**
0398  * @return the network connectivity state
0399  * @since 0.9.9.0
0400  */
0401 NETWORKMANAGERQT_EXPORT Connectivity connectivity();
0402 
0403 /**
0404  * Re-check the network connectivity state.
0405  * @see connectivity()
0406  * @since 0.9.9.0
0407  */
0408 NETWORKMANAGERQT_EXPORT QDBusPendingReply<uint> checkConnectivity();
0409 
0410 /**
0411  * @return the "primary" active connection being used
0412  * to access the network. In particular, if there is no VPN
0413  * active, or the VPN does not have the default route, then this
0414  * indicates the connection that has the default route. If there
0415  * is a VPN active with the default route, then this indicates
0416  * the connection that contains the route to the VPN endpoint.
0417  * @since 0.9.9.0
0418  */
0419 NETWORKMANAGERQT_EXPORT ActiveConnection::Ptr primaryConnection();
0420 
0421 /**
0422  * @return an active connection that is currently
0423  * being activated and which is expected to become the new
0424  * primaryConnection() when it finishes activating.
0425  * @since 0.9.9.0
0426  */
0427 NETWORKMANAGERQT_EXPORT ActiveConnection::Ptr activatingConnection();
0428 
0429 /**
0430  * @return The connection type of the "primary" active connection being
0431  * used to access the network. This is the same as the Type
0432  * property on the object indicated by PrimaryConnection.
0433  * @since 5.8.0
0434  */
0435 NETWORKMANAGERQT_EXPORT NetworkManager::ConnectionSettings::ConnectionType primaryConnectionType();
0436 
0437 /**
0438  * Indicates whether NM is still starting up; this becomes @p false
0439  * when NM has finished attempting to activate every connection
0440  * that it might be able to activate at startup.
0441  * @since 0.9.9.0
0442  */
0443 NETWORKMANAGERQT_EXPORT bool isStartingUp();
0444 
0445 /**
0446  * @return Indicates whether the connectivity is metered.
0447  * @since 5.14.0
0448  */
0449 NETWORKMANAGERQT_EXPORT NetworkManager::Device::MeteredStatus metered();
0450 
0451 /**
0452  * @return Gets the global DNS configuration.
0453  * @since 5.45.0
0454  */
0455 NETWORKMANAGERQT_EXPORT NetworkManager::DnsConfiguration globalDnsConfiguration();
0456 
0457 /**
0458  * @return Sets the global DNS configuration.
0459  * @since 5.45.0
0460  */
0461 NETWORKMANAGERQT_EXPORT void setGlobalDnsConfiguration(const NetworkManager::DnsConfiguration &configuration);
0462 
0463 /**
0464  * Find an ActiveConnection object for an active connection id
0465  *
0466  * @param uni the id of the ActiveConnection
0467  * @return a valid ActiveConnection object
0468  */
0469 NETWORKMANAGERQT_EXPORT ActiveConnection::Ptr findActiveConnection(const QString &uni);
0470 /**
0471  * Retrieves the interface types supported by this network manager.
0472  *
0473  * @return the interface types supported by the network manager
0474  */
0475 NETWORKMANAGERQT_EXPORT Device::Types supportedInterfaceTypes();
0476 NETWORKMANAGERQT_EXPORT void setNetworkingEnabled(bool enabled);
0477 // implemented in Notifier
0478 NETWORKMANAGERQT_EXPORT void setWirelessEnabled(bool enabled);
0479 NETWORKMANAGERQT_EXPORT void setWwanEnabled(bool enabled);
0480 /**
0481  * @deprecated Wimax support was removed from NetworkManager 1.2
0482  * (it is a noop in runtime NM >= 1.2.0).
0483  */
0484 NETWORKMANAGERQT_EXPORT void setWimaxEnabled(bool enabled);
0485 NETWORKMANAGERQT_EXPORT void sleep(bool sleep);
0486 NETWORKMANAGERQT_EXPORT void setLogging(LogLevel, LogDomains);
0487 NETWORKMANAGERQT_EXPORT NMStringMap permissions();
0488 NETWORKMANAGERQT_EXPORT Notifier *notifier();
0489 
0490 }
0491 
0492 #endif