Skip to content

quickstart.rst

Latest commit

 

History

History
134 lines (96 loc) · 4.54 KB

quickstart.rst

File metadata and controls

134 lines (96 loc) · 4.54 KB

NetworkManager D-Bus API quickstart

This is a tutorial to understand the structure of the NetworkManager D-Bus API and how to use it.

Note

NetworkManager usually uses the system D-Bus, however, sdbus uses the session D-Bus by default. It is recommend to call sdbus.set_default_bus(sdbus.sd_bus_open_system()) to set the system bus as default bus.

NetworkManager main object

This is a static object that contains information about entire state of NetworkManager. The Python class :py:class:`NetworkManager <sdbus_async.networkmanager.NetworkManager>` has a predefined service name and object path.

import sdbus
from sdbus_block.networkmanager import NetworkManager

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

Devices

Every device object represents a network device. Device object has a generic methods and properties that are universal across all device types and a type specific methods. The :py:class:`NetworkDeviceGeneric <sdbus_async.networkmanager.NetworkDeviceGeneric>` implements generic methods and, for example, :py:class:`NetworkDeviceWireless <sdbus_async.networkmanager.NetworkDeviceWireless>` adds Wi-Fi specific methods.

The :py:attr:`device_type <sdbus_async.networkmanager.NetworkManagerDeviceInterfaceAsync.device_type>` property and enum :py:class:`DeviceType <sdbus_async.networkmanager.enums.DeviceType>` can be used to determine particular type of a device.

import sdbus

from sdbus_block.networkmanager import (
    NetworkDeviceGeneric,
    NetworkDeviceWireless,
    NetworkManager,
)
from sdbus_block.networkmanager.enums import DeviceType

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

all_devices = {path: NetworkDeviceGeneric(path) for path in network_manager.devices}

wifi_devices = [
    NetworkDeviceWireless(path)
    for path, device in all_devices.items()
    if device.device_type == DeviceType.WIFI
]

Connection

Connection represents a configuration containing an IP address, Wifi password, proxy settings and etc... The main object to access connections is the :py:class:`NetworkManagerSettings <sdbus_async.networkmanager.NetworkManagerSettings>` which has predefined object path.

Each individual connection has a separate path which can be accessed with :py:class:`NetworkConnectionSettings <sdbus_async.networkmanager.NetworkConnectionSettings>` class.

import sdbus

from sdbus_block.networkmanager import (
    NetworkConnectionSettings,
    NetworkManager,
    NetworkManagerSettings,
)

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

networwork_manager_settings = NetworkManagerSettings()

all_connections = [
    NetworkConnectionSettings(x) for x in networwork_manager_settings.connections
]

The actual connection settings are represented by a complex double nested dictionary of D-Bus variants. For convenience a dataclass based helper is provided.

The :py:meth:`get_profile <sdbus_async.networkmanager.NetworkManagerSettingsConnectionInterfaceAsync.get_profile>` and :py:meth:`update_profile <sdbus_async.networkmanager.NetworkManagerSettingsConnectionInterfaceAsync.update_profile>` are two main methods to interact with connection settings helper.

import sdbus

from sdbus_block.networkmanager import (
    NetworkConnectionSettings,
    NetworkManager,
    NetworkManagerSettings,
)

sdbus.set_default_bus(sdbus.sd_bus_open_system())
network_manager = NetworkManager()

networwork_manager_settings = NetworkManagerSettings()


connection = NetworkConnectionSettings(networwork_manager_settings.connections[0])
setting_dataclass = connection.get_profile()
print("uuid:", setting_dataclass.connection.uuid)

Active Connection

:py:class:`ActiveConnection <sdbus_async.networkmanager.ActiveConnection>` is a product of a Connection being applied to a Device.

For example, :py:meth:`activate_connection <sdbus_async.networkmanager.NetworkManagerInterfaceAsync.activate_connection>` of the main NetworkManager object will create new Active Connection (therefore configuring network on a device) and return its path. The :py:meth:`deactivate_connection <sdbus_async.networkmanager.NetworkManagerInterfaceAsync.deactivate_connection>` will remove the active connection and remove the device's network configuration.