From a21233c7abde5572bc40494d1cb9b38976bf8f1c Mon Sep 17 00:00:00 2001
From: Aleksander Morgado <aleksander@aleksander.es>
Date: Mon, 22 Mar 2021 15:07:26 +0100
Subject: api: define bearer settings only in the 'Properties' property

Avoid defining them multiple times in the Modem.CreateBearer(),
Simple.Connect() and Modem3gpp.SetInitialEpsBearerSettings() methods.
---
 .../org.freedesktop.ModemManager1.Bearer.xml       | 90 +++++++++++++++++++++-
 ...g.freedesktop.ModemManager1.Modem.Modem3gpp.xml | 18 ++---
 .../org.freedesktop.ModemManager1.Modem.Simple.xml | 78 ++++---------------
 .../org.freedesktop.ModemManager1.Modem.xml        | 27 +------
 4 files changed, 109 insertions(+), 104 deletions(-)

(limited to 'introspection')

diff --git a/introspection/org.freedesktop.ModemManager1.Bearer.xml b/introspection/org.freedesktop.ModemManager1.Bearer.xml
index 94332215..d76f8a0c 100644
--- a/introspection/org.freedesktop.ModemManager1.Bearer.xml
+++ b/introspection/org.freedesktop.ModemManager1.Bearer.xml
@@ -340,7 +340,95 @@
     <!--
         Properties:
 
-        List of properties used when creating the bearer.
+        List of settings used to create the bearer.
+
+        Bearers may be implicitly created (e.g. the default initial EPS bearer
+        created during the network registration process in 4G and 5G networks)
+        or explicitly created by the user (e.g. via the
+        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem.CreateBearer">CreateBearer()</link>
+        or <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Connect">Connect()</link>
+        calls).
+
+        The following settings apply to 3GPP (GSM/UMTS/LTE/5GNR) devices:
+
+        <variablelist>
+          <varlistentry><term><literal>"apn"</literal></term>
+            <listitem><para>
+              The Access Point Name to use in the connection, given as a string
+              value (signature <literal>"s"</literal>).
+            </para></listitem>
+          </varlistentry>
+          <varlistentry><term><literal>"ip-type"</literal></term>
+            <listitem>
+              The IP addressing type to use, given as a
+<link linkend="MMBearerIpFamily">MMBearerIpFamily</link>
+              value (signature <literal>"u"</literal>).
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><literal>"allowed-auth"</literal></term>
+            <listitem>
+              The authentication method to use, given as a
+              <link linkend="MMBearerAllowedAuth">MMBearerAllowedAuth</link>
+              value (signature <literal>"u"</literal>).
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><literal>"user"</literal></term>
+            <listitem>
+              The user name (if any) required by the network, given as a string
+              value (signature <literal>"s"</literal>).
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><literal>"password"</literal></term>
+            <listitem>
+              The password (if any) required by the network, given as a string
+              value (signature <literal>"s"</literal>).
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        The following settings apply to 3GPP2 (CDMA/EVDO) devices:
+
+        <variablelist>
+          <varlistentry><term><literal>"rm-protocol"</literal></term>
+            <listitem>
+              The protocol of the Rm interface, given as a
+              <link linkend="MMModemCdmaRmProtocol">MMModemCdmaRmProtocol</link>
+              value (signature <literal>"u"</literal>).
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        The following settings apply to all devices types:
+
+        <variablelist>
+          <varlistentry><term><literal>"allow-roaming"</literal></term>
+            <listitem>
+              Specifies whether the connections are allowed even when the device
+              is registered in a roaming network, given as a boolean value (signature
+              <literal>"b"</literal>).
+            </listitem>
+          </varlistentry>
+          <varlistentry><term><literal>"multiplex"</literal></term>
+            <listitem>
+              The multiplex support requested by the user, given as a
+              <link linkend="MMBearerMultiplexSupport">MMBearerMultiplexSupport</link>
+              value (signature <literal>"u"</literal>). Since 1.18.
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        The following settings are no longer supported, but they are kept on the
+        interface for compatibility purposes:
+
+        <variablelist>
+          <varlistentry><term><literal>"number"</literal></term>
+            <listitem>
+              Number to dial for the data connection, given as a string value
+              (signature <literal>"s"</literal>).
+              Deprecated since version 1.10.0.
+            </listitem>
+          </varlistentry>
+        </variablelist>
     -->
     <property name="Properties" type="a{sv}" access="read" />
 
diff --git a/introspection/org.freedesktop.ModemManager1.Modem.Modem3gpp.xml b/introspection/org.freedesktop.ModemManager1.Modem.Modem3gpp.xml
index e741ae91..c2ef8b02 100644
--- a/introspection/org.freedesktop.ModemManager1.Modem.Modem3gpp.xml
+++ b/introspection/org.freedesktop.ModemManager1.Modem.Modem3gpp.xml
@@ -106,19 +106,11 @@
 
         Updates the default settings to be used in the initial default EPS bearer when registering to the LTE network.
 
-        Allowed properties are:
-        <variablelist>
-        <varlistentry><term><literal>"apn"</literal></term>
-          <listitem><para>Access Point Name, given as a string value (signature <literal>"s"</literal>).</para></listitem></varlistentry>
-        <varlistentry><term><literal>"ip-type"</literal></term>
-          <listitem><para>Addressing type, given as a <link linkend="MMBearerIpFamily">MMBearerIpFamily</link> value (signature <literal>"u"</literal>).</para></listitem></varlistentry>
-        <varlistentry><term><literal>"allowed-auth"</literal></term>
-          <listitem><para>The authentication method to use, given as a <link linkend="MMBearerAllowedAuth">MMBearerAllowedAuth</link> value (signature <literal>"u"</literal>).</para></listitem></varlistentry>
-        <varlistentry><term><literal>"user"</literal></term>
-          <listitem><para>User name (if any) required by the network, given as a string value (signature <literal>"s"</literal>).</para></listitem></varlistentry>
-        <varlistentry><term><literal>"password"</literal></term>
-          <listitem><para>Password (if any) required by the network, given as a string value (signature <literal>"s"</literal>).</para></listitem></varlistentry>
-        </variablelist>
+        The allowed properties in this method are all the 3GPP-specific ones specified
+        in the <link linkend="gdbus-property-org-freedesktop-ModemManager1-Bearer.Properties">bearer properties</link>;
+        i.e.: <literal>"apn"</literal>, <literal>"ip-type"</literal>,
+        <literal>"allowed-auth"</literal>, <literal>"user"</literal>, and
+        <literal>"password"</literal>.
     -->
     <method name="SetInitialEpsBearerSettings">
       <arg name="settings" type="a{sv}" direction="in" />
diff --git a/introspection/org.freedesktop.ModemManager1.Modem.Simple.xml b/introspection/org.freedesktop.ModemManager1.Modem.Simple.xml
index e40c6b0c..78f108dc 100644
--- a/introspection/org.freedesktop.ModemManager1.Modem.Simple.xml
+++ b/introspection/org.freedesktop.ModemManager1.Modem.Simple.xml
@@ -39,16 +39,20 @@
 
         This call may make a large number of changes to modem configuration
         based on properties passed in. For example, given a PIN-locked, disabled
-        GSM/UMTS modem, this call may unlock the SIM PIN, alter the access
-        technology preference, wait for network registration (or force
-        registration to a specific provider), create a new packet data bearer
-        using the given "apn", and connect that bearer.
+        GSM/UMTS modem, this call may unlock the SIM PIN, wait for network
+        registration (or force registration to a specific provider), create a
+        new packet data bearer using the given "apn", and connect that bearer.
+
+        The list of allowed properties includes all the ones defined in the
+        <link linkend="gdbus-property-org-freedesktop-ModemManager1-Bearer.Properties">bearer properties</link>
+        plus these additional ones that are only applicable to this method,
+        and only to 3GPP (GSM/UMTS/LTE/5GNR) devices:
 
-        Allowed key/value pairs in @properties are:
         <variablelist>
           <varlistentry><term><literal>"pin"</literal></term>
             <listitem>
-              SIM-PIN unlock code, given as a string value (signature <literal>"s"</literal>).
+              SIM-PIN unlock code, given as a string value (signature
+              <literal>"s"</literal>).
             </listitem>
           </varlistentry>
           <varlistentry><term><literal>"operator-id"</literal></term>
@@ -57,66 +61,10 @@
               given as a string value (signature <literal>"s"</literal>).
             </listitem>
           </varlistentry>
-          <varlistentry><term><literal>"apn"</literal></term>
-            <listitem>
-              For GSM/UMTS and LTE devices the APN to use,
-              given as a string value (signature <literal>"s"</literal>).
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"ip-type"</literal></term>
-            <listitem>
-              For GSM/UMTS and LTE devices the IP addressing type to use,
-              given as a <link linkend="MMBearerIpFamily">MMBearerIpFamily</link>
-              value (signature <literal>"u"</literal>).
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"allowed-auth"</literal></term>
-            <listitem>
-              The authentication method to use, given as a
-              <link linkend="MMBearerAllowedAuth">MMBearerAllowedAuth</link>
-              value (signature <literal>"u"</literal>). Optional in 3GPP.
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"user"</literal></term>
-            <listitem>
-              User name (if any) required by the network, given as a string
-              value (signature <literal>"s"</literal>). Optional in 3GPP.
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"password"</literal></term>
-            <listitem>
-              Password (if any) required by the network, given as a string value
-              (signature <literal>"s"</literal>). Optional in 3GPP.
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"number"</literal></term>
-            <listitem>
-              Number to dial for the data connection,
-              given as a string value (signature <literal>"s"</literal>).
-              Deprecated since version 1.10.0.
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"allow-roaming"</literal></term>
-            <listitem>
-              %FALSE to allow only connections to home networks,
-              given as a boolean value (signature <literal>"b"</literal>).
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"rm-protocol"</literal></term>
-            <listitem>
-              For CDMA devices, the protocol of the Rm interface, given as a
-              <link linkend="MMModemCdmaRmProtocol">MMModemCdmaRmProtocol</link>
-              value (signature <literal>"u"</literal>).
-            </listitem>
-          </varlistentry>
-          <varlistentry><term><literal>"multiplex"</literal></term>
-            <listitem>
-              Multiplex support requested by the user, given as a
-              <link linkend="MMBearerMultiplexSupport">MMBearerMultiplexSupport</link>
-              value (signature <literal>"u"</literal>). Since 1.18.
-            </listitem>
-          </varlistentry>
         </variablelist>
+
+        There are no settings specific to this call that would apply to 3GPP2
+        (CDMA/EVDO) devices.
     -->
     <method name="Connect">
       <arg name="properties" type="a{sv}" direction="in"  />
diff --git a/introspection/org.freedesktop.ModemManager1.Modem.xml b/introspection/org.freedesktop.ModemManager1.Modem.xml
index 6accaf29..7d6e3603 100644
--- a/introspection/org.freedesktop.ModemManager1.Modem.xml
+++ b/introspection/org.freedesktop.ModemManager1.Modem.xml
@@ -63,31 +63,8 @@
         This request may fail if the modem does not support additional bearers,
         if too many bearers are already defined, or if properties are invalid.
 
-        Allowed properties are:
-        <variablelist>
-        <varlistentry><term><literal>"apn"</literal></term>
-          <listitem><para>Access Point Name, given as a string value (signature <literal>"s"</literal>). Required in 3GPP.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"ip-type"</literal></term>
-          <listitem><para>Addressing type, given as a <link linkend="MMBearerIpFamily">MMBearerIpFamily</link> value (signature <literal>"u"</literal>). Optional in 3GPP and CDMA.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"allowed-auth"</literal></term>
-          <listitem><para>The authentication method to use, given as a <link linkend="MMBearerAllowedAuth">MMBearerAllowedAuth</link> value (signature <literal>"u"</literal>). Optional in 3GPP.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"user"</literal></term>
-          <listitem><para>User name (if any) required by the network, given as a string value (signature <literal>"s"</literal>). Optional in 3GPP.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"password"</literal></term>
-          <listitem><para>Password (if any) required by the network, given as a string value (signature <literal>"s"</literal>). Optional in 3GPP.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"allow-roaming"</literal></term>
-          <listitem><para>Flag to tell whether connection is allowed during roaming, given as a boolean value (signature <literal>"b"</literal>). Optional in 3GPP.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"rm-protocol"</literal></term>
-          <listitem><para>Protocol of the Rm interface, given as a <link linkend="MMModemCdmaRmProtocol">MMModemCdmaRmProtocol</link> value (signature <literal>"u"</literal>). Optional in CDMA.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"number"</literal></term>
-          <listitem><para>Number to dial for the data connection, given as a string value (signature <literal>"s"</literal>). Deprecated since version 1.10.0.</para></listitem></varlistentry>
-        <varlistentry><term><literal>"multiplex"</literal></term>
-          <listitem><para>Multiplex support requested by the user, given as a <link linkend="MMBearerMultiplexSupport">MMBearerMultiplexSupport</link> value (signature <literal>"u"</literal>). Since 1.18.</para></listitem></varlistentry>
-        </variablelist>
-
-        Some properties are only applicable to a bearer of certain access
-        technologies, for example the <literal>"apn"</literal> property is not
-        applicable to CDMA2000 Packet Data Session bearers.
+        The properties allowed are any of the ones defined in the
+        <link linkend="gdbus-property-org-freedesktop-ModemManager1-Bearer.Properties">bearer properties</link>.
     -->
     <method name="CreateBearer">
       <arg name="properties" type="a{sv}" direction="in"  />
-- 
cgit v1.2.3-70-g09d2