agama-project · imobachgs · Jul 4, 2023 · Jul 4, 2023 · Jul 4, 2023
diff --git a/doc/dbus/bus/org.opensuse.Agama.Network1.Connection.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Network1.Connection.bus.xml
@@ -2,14 +2,79 @@
 <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg type="s" direction="out"/>
+    </method>
+  </interface>
+  <interface name="org.opensuse.Agama.Network1.Connection">
+    <!--
+     Connection ID.
+
+     Unique identifier of the network connection. It may or not be the same that the used by the
+     backend. For instance, when using NetworkManager (which is the only supported backend by
+     now), it uses the original ID but appending a number in case the ID is duplicated.
+     -->
+    <property name="Id" type="s" access="read"/>
+  </interface>
+  <interface name="org.opensuse.Agama.Network1.Connection.IPv4">
+    <!--
+     List of IP addresses.
+
+     When the method is 'auto', these addresses are used as additional addresses.
+     -->
+    <property name="Addresses" type="as" access="readwrite"/>
+    <!--
+     Network gateway.
+
+     An empty string removes the current value. It is not possible to set a gateway if the
+     Addresses property is empty.
+     -->
+    <property name="Gateway" type="s" access="readwrite"/>
+    <!--
+     IP configuration method.
+
+     Possible values: "disabled", "auto", "manual" or "link-local".
+
+     See [crate::model::IpMethod].
+     -->
+    <property name="Method" type="s" access="readwrite"/>
+    <!--
+     Name server addresses.
+     -->
+    <property name="Nameservers" type="as" access="readwrite"/>
+  </interface>
   <interface name="org.opensuse.Agama.Network1.Connection.Wireless">
-    <property name="Mode" type="y" access="readwrite"/>
+    <!--
+     Wireless connection mode.
+
+     Possible values: "unknown", "adhoc", "infrastructure", "ap" or "mesh".
+
+     See [crate::model::WirelessMode].
+     -->
+    <property name="Mode" type="s" access="readwrite"/>
+    <!--
+     Password to connect to the wireless network.
+     -->
     <property name="Password" type="s" access="readwrite"/>
+    <!--
+     Network SSID.
+     -->
     <property name="SSID" type="ay" access="readwrite"/>
-    <property name="Security" type="y" access="readwrite"/>
+    <!--
+     Wireless security protocol.
+
+     Possible values: "none", "owe", "ieee8021x", "wpa-psk", "sae", "wpa-eap",
+     "wpa-eap-suite-b192".
+
+     See [crate::model::WirelessMode].
+     -->
+    <property name="Security" type="s" access="readwrite"/>
   </interface>
-  <interface name="org.freedesktop.DBus.Introspectable">
-    <method name="Introspect">
+  <interface name="org.freedesktop.DBus.Peer">
+    <method name="Ping">
+    </method>
+    <method name="GetMachineId">
       <arg type="s" direction="out"/>
     </method>
   </interface>
@@ -37,22 +102,5 @@
       <arg name="invalidated_properties" type="as"/>
     </signal>
   </interface>
-  <interface name="org.freedesktop.DBus.Peer">
-    <method name="Ping">
-    </method>
-    <method name="GetMachineId">
-      <arg type="s" direction="out"/>
-    </method>
-  </interface>
-  <interface name="org.opensuse.Agama.Network1.Connection">
-    <property name="Id" type="s" access="read"/>
-    <property name="UUID" type="s" access="read"/>
-  </interface>
-  <interface name="org.opensuse.Agama.Network1.Connection.IPv4">
-    <property name="Addresses" type="a(su)" access="readwrite"/>
-    <property name="Gateway" type="s" access="readwrite"/>
-    <property name="Method" type="y" access="readwrite"/>
-    <property name="Nameservers" type="as" access="readwrite"/>
-  </interface>
 </node>
 
diff --git a/doc/dbus/bus/org.opensuse.Agama.Network1.Connections.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Network1.Connections.bus.xml
@@ -47,16 +47,25 @@
      * `ty`: connection type (see [crate::model::DeviceType]).
      -->
     <method name="AddConnection">
-      <arg name="name" type="s" direction="in"/>
+      <arg name="id" type="s" direction="in"/>
       <arg name="ty" type="y" direction="in"/>
     </method>
+    <!--
+     Returns the D-Bus path of the network connection.
+
+     * `id`: connection ID.
+     -->
+    <method name="GetConnection">
+      <arg name="id" type="s" direction="in"/>
+      <arg type="o" direction="out"/>
+    </method>
     <!--
      Removes a network connection.
 
      * `uuid`: connection UUID..
      -->
     <method name="RemoveConnection">
-      <arg name="uuid" type="s" direction="in"/>
+      <arg name="id" type="s" direction="in"/>
     </method>
     <!--
      Applies the network configuration.

diff --git a/doc/dbus/bus/org.opensuse.Agama.Network1.Device.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Network1.Device.bus.xml
@@ -39,7 +39,19 @@
     </signal>
   </interface>
   <interface name="org.opensuse.Agama.Network1.Device">
+    <!--
+     Device name.
+
+     Kernel device name, e.g., eth0, enp1s0, etc.
+     -->
     <property name="Name" type="s" access="read"/>
+    <!--
+     Device type.
+
+     Possible values: 0 = loopback, 1 = ethernet, 2 = wireless.
+
+     See [crate::model::DeviceType].
+     -->
     <property name="Type" type="y" access="read"/>
   </interface>
 </node>

diff --git a/doc/dbus/bus/org.opensuse.Agama.Network1.Devices.bus.xml b/doc/dbus/bus/org.opensuse.Agama.Network1.Devices.bus.xml
@@ -17,6 +17,11 @@
       <arg type="s" direction="out"/>
     </method>
   </interface>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg type="s" direction="out"/>
+    </method>
+  </interface>
   <interface name="org.freedesktop.DBus.Properties">
     <method name="Get">
       <arg name="interface_name" type="s" direction="in"/>
@@ -41,10 +46,5 @@
       <arg name="invalidated_properties" type="as"/>
     </signal>
   </interface>
-  <interface name="org.freedesktop.DBus.Introspectable">
-    <method name="Introspect">
-      <arg type="s" direction="out"/>
-    </method>
-  </interface>
 </node>
 
diff --git a/doc/dbus/org.opensuse.Agama.Network1.Connection.IPv4.doc.xml b/doc/dbus/org.opensuse.Agama.Network1.Connection.IPv4.doc.xml
@@ -3,9 +3,30 @@
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <interface name="org.opensuse.Agama.Network1.Connection.IPv4">
-    <property name="Addresses" type="a(su)" access="readwrite"/>
+    <!--
+     List of IP addresses.
+
+     When the method is 'auto', these addresses are used as additional addresses.
+     -->
+    <property name="Addresses" type="as" access="readwrite"/>
+    <!--
+     Network gateway.
+
+     An empty string removes the current value. It is not possible to set a gateway if the
+     Addresses property is empty.
+     -->
     <property name="Gateway" type="s" access="readwrite"/>
-    <property name="Method" type="y" access="readwrite"/>
+    <!--
+     IP configuration method.
+
+     Possible values: "disabled", "auto", "manual" or "link-local".
+
+     See [crate::model::IpMethod].
+     -->
+    <property name="Method" type="s" access="readwrite"/>
+    <!--
+     Name server addresses.
+     -->
     <property name="Nameservers" type="as" access="readwrite"/>
   </interface>
 </node>

diff --git a/doc/dbus/org.opensuse.Agama.Network1.Connection.Wireless.doc.xml b/doc/dbus/org.opensuse.Agama.Network1.Connection.Wireless.doc.xml
@@ -3,10 +3,31 @@
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <interface name="org.opensuse.Agama.Network1.Connection.Wireless">
-    <property name="Mode" type="y" access="readwrite"/>
+    <!--
+     Wireless connection mode.
+
+     Possible values: "unknown", "adhoc", "infrastructure", "ap" or "mesh".
+
+     See [crate::model::WirelessMode].
+     -->
+    <property name="Mode" type="s" access="readwrite"/>
+    <!--
+     Password to connect to the wireless network.
+     -->
     <property name="Password" type="s" access="readwrite"/>
+    <!--
+     Network SSID.
+     -->
     <property name="SSID" type="ay" access="readwrite"/>
-    <property name="Security" type="y" access="readwrite"/>
+    <!--
+     Wireless security protocol.
+
+     Possible values: "none", "owe", "ieee8021x", "wpa-psk", "sae", "wpa-eap",
+     "wpa-eap-suite-b192".
+
+     See [crate::model::WirelessMode].
+     -->
+    <property name="Security" type="s" access="readwrite"/>
   </interface>
 </node>
 
diff --git a/doc/dbus/org.opensuse.Agama.Network1.Connection.doc.xml b/doc/dbus/org.opensuse.Agama.Network1.Connection.doc.xml
@@ -3,8 +3,14 @@
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <interface name="org.opensuse.Agama.Network1.Connection">
+    <!--
+     Connection ID.
+
+     Unique identifier of the network connection. It may or not be the same that the used by the
+     backend. For instance, when using NetworkManager (which is the only supported backend by
+     now), it uses the original ID but appending a number in case the ID is duplicated.
+     -->
     <property name="Id" type="s" access="read"/>
-    <property name="UUID" type="s" access="read"/>
   </interface>
 </node>
 
diff --git a/doc/dbus/org.opensuse.Agama.Network1.Connections.doc.xml b/doc/dbus/org.opensuse.Agama.Network1.Connections.doc.xml
@@ -14,22 +14,31 @@
      AddConnection:
      Adds a new network connection.
 
-     * `name`: connection name.
-
+     * `id`: connection name.
      * `ty`: connection type (see [crate::model::DeviceType]).
      -->
     <method name="AddConnection">
-      <arg name="name" type="s" direction="in"/>
+      <arg name="id" type="s" direction="in"/>
       <arg name="ty" type="y" direction="in"/>
     </method>
+    <!--
+     GetConnection:
+     Returns the D-Bus path of the network connection.
+
+     * `id`: connection ID.
+     -->
+    <method name="GetConnection">
+      <arg name="id" type="s" direction="in"/>
+      <arg type="o" direction="out"/>
+    </method>
     <!--
      RemoveConnection:
      Removes a network connection.
 
      * `uuid`: connection UUID..
      -->
     <method name="RemoveConnection">
-      <arg name="uuid" type="s" direction="in"/>
+      <arg name="id" type="s" direction="in"/>
     </method>
     <!--
      Apply:

diff --git a/doc/dbus/org.opensuse.Agama.Network1.Device.doc.xml b/doc/dbus/org.opensuse.Agama.Network1.Device.doc.xml
@@ -3,7 +3,19 @@
  "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 <node>
   <interface name="org.opensuse.Agama.Network1.Device">
+    <!--
+     Device name
+
+     Kernel device name, e.g., eth0, enp1s0, etc.
+     -->
     <property name="Name" type="s" access="read"/>
+    <!--
+     Device type
+
+     Possible values: 0 = loopback, 1 = ethernet, 2 = wireless.
+
+     See [crate::model::DeviceType].
+     -->
     <property name="Type" type="y" access="read"/>
   </interface>
 </node>

diff --git a/rust/agama-dbus-server/src/network/dbus/interfaces.rs b/rust/agama-dbus-server/src/network/dbus/interfaces.rs
@@ -316,7 +316,7 @@ impl Ipv4 {
     /// Network gateway.
     ///
     /// An empty string removes the current value. It is not possible to set a gateway if the
-    /// addresses property is empty.
+    /// Addresses property is empty.
     #[dbus_interface(property)]
     pub fn gateway(&self) -> String {
         let connection = self.get_connection();