all: avoid byte ordering issue for IP4Config's Nameservers/WinsServers on D-Bus

Some properties in NetworkManager's D-Bus API are IPv4 addresses
in network byte order (big endian). That is problematic.

It is no problem, when the NetworkManager client runs on the same
host. That is the case with libnm, which does not support to be used
remotely for the time being.

It is a problem for an application that wants to access the D-Bus
interface of NetworkManager remotely. Possibly, such an application
would be implemented in two layers:

 - one layer merely remotes D-Bus, without specific knowledge of
   NetworkManager's API.

 - a higher layer which accesses the remote D-Bus interface of NetworkManager.
   Preferably it does so in an agnostic way, regardless of whether it runs
   locally or remotely.

When using a D-Bus library, all accesses to 32 bit integers are in
native endianness (regardless of how the integer is actually encoded
on the lower layers). Likewise, D-Bus does not support annotating integer
types in non-native endianness. There is no way to annotate an integer
type "u" to be anything but native order.
That means, when remoting D-Bus at some point the endianness must be
corrected.
But by looking at the D-Bus introspection alone, it is not possible
to know which property need correction and which don't. One would need
to understand the meaning of the properties.

That makes it problematic, because the higher layer of the application,
which knows that the "Nameservers" property is supposed to be in network
order, might not easily know, whether it must correct for endianness.

Deprecate IP4Config properties that are only accessible with a particular
endianness, and add new properties that expose the same data in an
agnostic way.

Note that I added "WinsServerData" to be a plain "as", while
"NameserverData" is of type "aa{sv}". There is no particularly strong
reason for these choices, except that I could imagine that it could be
useful to expose additional information in the future about nameservers
(e.g. are they received via DHCP or manual configuration?). On the other
hand, WINS information likely won't get extended in the future.

Also note, libnm was not modified to use the new D-Bus fields. The
endianness issue is no problem for libnm, so there is little reason to
change it (at this point).

https://bugzilla.redhat.com/show_bug.cgi?id=1153559
https://bugzilla.redhat.com/show_bug.cgi?id=1584584

1 files changed, 21 insertions, 2 deletions

diff --git a/introspection/org.freedesktop.NetworkManager.IP4Config.xml b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
index 0b04af94e..e4388fd4f 100644
--- a/introspection/org.freedesktop.NetworkManager.IP4Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
@@ -55,11 +55,21 @@
     <!--
         Nameservers:
 
-        The nameservers in use.
+        The nameservers in use. Deprecated: use NameserverData
     -->
     <property name="Nameservers" type="au" access="read"/>
 
     <!--
+        NameserverData:
+
+        The nameservers in use. Currently only the value "address"
+        is recognized (with an IP address string).
+
+        Since: 1.14
+    -->
+    <property name="NameserverData" type="aa{sv}" access="read"/>
+
+    <!--
         Domains:
 
         A list of domains this address belongs to.
@@ -92,11 +102,20 @@
         WinsServers:
 
         The Windows Internet Name Service servers associated with the connection.
-        Each address is in network byte order.
+        Each address is in network byte order. Deprecated: use WinsServerData
     -->
     <property name="WinsServers" type="au" access="read"/>
 
     <!--
+        WinsServerData:
+
+        The Windows Internet Name Service servers associated with the connection.
+
+        Since: 1.14
+    -->
+    <property name="WinsServerData" type="as" access="read"/>
+
+    <!--
         PropertiesChanged:
         @properties: A dictionary mapping property names to variant boxed values