From 18231c9f8df809aacd4534d0a081125e8d6569df Mon Sep 17 00:00:00 2001
From: Dan Williams <dcbw@redhat.com>
Date: Mon, 1 Aug 2011 17:47:38 -0500
Subject: [PATCH] api: refine new API based on suggestions from Eric Shienbrood

---
 ...freedesktop.ModemManager1.Modem.Bearer.xml |  6 ++-
 ...eedesktop.ModemManager1.Modem.Contacts.xml | 45 +++++++++++++++++--
 new/org.freedesktop.ModemManager1.Modem.xml   | 26 ++++++++---
 new/org.freedesktop.ModemManager1.Sim.xml     | 15 ++++++-
 4 files changed, 80 insertions(+), 12 deletions(-)

diff --git a/new/org.freedesktop.ModemManager1.Modem.Bearer.xml b/new/org.freedesktop.ModemManager1.Modem.Bearer.xml
index 180641d8..a441840a 100644
--- a/new/org.freedesktop.ModemManager1.Modem.Bearer.xml
+++ b/new/org.freedesktop.ModemManager1.Modem.Bearer.xml
@@ -20,7 +20,11 @@
       <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_bearer_connect"/>
       <arg name="number" type="s" direction="in">
 	<tp:docstring>
-	  The number to use for dialing.
+	  The number to use for dialing (optional).  Usually not required, in
+	  which case it should be an empty (zero-length) string.  Only required
+	  for POTS connections or in certain special circumstances.  If a number
+	  is given for 3GPP (GSM/UMTS/LTE) based devices, it is always ignored,
+	  as the number is generated internally if one is required at all.
       </tp:docstring>
       </arg>
     </method>
diff --git a/new/org.freedesktop.ModemManager1.Modem.Contacts.xml b/new/org.freedesktop.ModemManager1.Modem.Contacts.xml
index 7ddab3c4..8e3c85f0 100644
--- a/new/org.freedesktop.ModemManager1.Modem.Contacts.xml
+++ b/new/org.freedesktop.ModemManager1.Modem.Contacts.xml
@@ -3,6 +3,15 @@
 <node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   <interface name="org.freedesktop.ModemManager1.Modem.Contacts">
 
+    <tp:docstring>
+      This interface provides access to contacts stored in various locations,
+      including SIM cards, device storage, and other locations. Operations
+      generally operate on all contacts regardless of their actual storage
+      location.  Contacts are referred to by index numbers, which are internal
+      to ModemManager and do not represent indexs of SIM cards or the device.
+      Indexes may not be contiguous.
+    </tp:docstring>
+
     <method name="Add">
       <tp:docstring>
 	Add a new contact.
@@ -50,7 +59,7 @@
 
     <method name="Get">
       <tp:docstring>
-	Retrieve a contact from the SIM card.
+	Retrieve a contact.
       </tp:docstring>
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
       <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_contacts_get"/>
@@ -82,7 +91,7 @@
 
     <method name="Find">
       <tp:docstring>
-	Find a contact from the SIM card.
+	Find a contact.
       </tp:docstring>
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
       <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_contacts_find"/>
@@ -101,7 +110,7 @@
 
     <method name="GetCount">
       <tp:docstring>
-	Get the number of contacts stored on the SIM card.
+	Get the number of contacts.
       </tp:docstring>
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
       <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_contacts_count"/>
@@ -112,6 +121,36 @@
       </arg>
     </method>
 
+    <!-- SIGNALS -->
+
+    <signal name="Added">
+      <tp:docstring>
+        Emitted when a new contact is added.
+      </tp:docstring>
+      <arg name="index" type="u">
+        <tp:docstring>
+          The index number of the new contact.
+        </tp:docstring>
+      </arg>
+      <arg name="properties" type="a{sv}">
+	<tp:docstring>
+	  The properties of the contact including those properties defined by
+	  the Add method.
+	</tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="Deleted">
+      <tp:docstring>
+        Emitted when a contact has been deleted.
+      </tp:docstring>
+      <arg name="index" type="u">
+        <tp:docstring>
+          Index number of the now deleted contact.
+        </tp:docstring>
+      </arg>
+    </signal>
+
     <!-- ENUMS -->
 
     <tp:enum name="MM_MODEM_CONTACTS_STORAGE" type="u">
diff --git a/new/org.freedesktop.ModemManager1.Modem.xml b/new/org.freedesktop.ModemManager1.Modem.xml
index 32a6a93f..15eb1b9c 100644
--- a/new/org.freedesktop.ModemManager1.Modem.xml
+++ b/new/org.freedesktop.ModemManager1.Modem.xml
@@ -60,6 +60,11 @@
           ** FIXME: how about QoS?
         </tp:docstring>
       </arg>
+      <arg name="path" type="o" direction="out">
+	<tp:docstring>
+	  On success, the object path of the newly created bearer.
+        </tp:docstring>
+      </arg>
     </method>
 
     <method name="DeleteBearer">
@@ -252,28 +257,30 @@
     <property name="AllowedMode" type="u" access="readwrite" tp:type="MM_MODEM_ALLOWED_MODE">
       <tp:docstring>
         The allowed access technologies (eg 2G/3G/4G preference) the device is
-        allowed to use when connecting to a network.  For POTS devices, only
-        the "any" mode is supported.
+        currently allowed to use when connecting to a network.  For POTS
+        devices, only the "any" mode is supported.
       </tp:docstring>
     </property>
 
     <property name="SupportedModes" type="u" access="read" tp:type="MM_MODEM_ALLOWED_MODE">
       <tp:docstring>
-        Access technology selection modes supported by the device.
+        Access technology selection modes supported by the device.  For POTS
+        devices, only the "any" mode will be returned.
       </tp:docstring>
     </property>
 
     <property name="AllowedBands" type="t" access="readwrite" tp:type="MM_MODEM_BAND">
       <tp:docstring>
-        The allowed radio frequency and technology bands the device may use when
+        The allowed radio frequency and technology bands the device is currently
         allowed to use when connecting to a network.  For POTS devices, only
-        the "any" mode is supported.
+        the "any" value is supported.
       </tp:docstring>
     </property>
 
     <property name="SupportedBands" type="t" access="read" tp:type="MM_MODEM_BAND">
       <tp:docstring>
-        Radio frequency and technology bands supported by the device.
+        Radio frequency and technology bands supported by the device.  For POTS
+        devices, only the "any" value will be returned.
       </tp:docstring>
     </property>
 
@@ -307,7 +314,12 @@
       </tp:flag>
       <tp:flag suffix="LTE" value="0x8">
         <tp:docstring>
-          Modem has at LTE data capability.
+          Modem has LTE data capability.
+        </tp:docstring>
+      </tp:flag>
+      <tp:flag suffix="LTE_ADVANCED" value="0x10">
+        <tp:docstring>
+          Modem has LTE Advanced data capability.
         </tp:docstring>
       </tp:flag>
     </tp:flags>
diff --git a/new/org.freedesktop.ModemManager1.Sim.xml b/new/org.freedesktop.ModemManager1.Sim.xml
index 14c34aea..77724f03 100644
--- a/new/org.freedesktop.ModemManager1.Sim.xml
+++ b/new/org.freedesktop.ModemManager1.Sim.xml
@@ -27,13 +27,26 @@
       </tp:docstring>
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
       <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_sim_get_operator_id"/>
-      <arg name="imsi" type="s" direction="out">
+      <arg name="operator_id" type="s" direction="out">
 	<tp:docstring>
 	  The operator ID formatted as an MCC/MNC code.
 	</tp:docstring>
       </arg>
     </method>
 
+    <method name="GetOperatorName">
+      <tp:docstring>
+        Returns the name of the operator as given by the SIM card, if known.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_sim_get_operator_name"/>
+      <arg name="operator_name" type="s" direction="out">
+	<tp:docstring>
+	  The operator name.
+	</tp:docstring>
+      </arg>
+    </method>
+
     <method name="SendPuk">
       <tp:docstring>
 	Send the PUK and a new PIN to unlock the SIM card.