api: update proposed new SMS API

Finish most of the stuff here.

3 files changed, 243 insertions, 120 deletions

diff --git a/new/org.freedesktop.ModemManager.Modem.Gsm.SMS.xml b/new/org.freedesktop.ModemManager.Modem.Gsm.SMS.xml
deleted file mode 100644
index 9645462a..00000000
--- a/new/org.freedesktop.ModemManager.Modem.Gsm.SMS.xml
+++ /dev/null
@@ -1,120 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-
-<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <interface name="org.freedesktop.ModemManager1.Modem.SMS">
-
-    <!-- METHODS -->
-
-    <method name="Delete">
-      <tp:docstring>
-	Delete an SMS message.
-      </tp:docstring>
-      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_gsm_modem_sms_delete"/>
-      <arg name="index" type="u" direction="in">
-	<tp:docstring>
-	  The index of the SMS.
-	</tp:docstring>
-      </arg>
-    </method>
-
-    <method name="Get">
-      <tp:docstring>
-	Retrieve an SMS from the SIM card.
-      </tp:docstring>
-      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_gsm_modem_sms_get"/>
-      <arg name="index" type="u" direction="in">
-	<tp:docstring>
-	  The index of the SMS.
-	</tp:docstring>
-      </arg>
-      <arg name="sms" type="a{sv}" direction="out">
-        <tp:docstring>
-          A dictionary containing SMS properties of the SMS specified by the given index.  This dictionary may contain the following key/value pairs:
-
-          number   : string - Phone number (mandatory)
-          text     : string - SMS text (mandatory)
-          smsc     : string - SMS service center number (optional)
-          validity : uint (0..255) - Specifies when the SMS expires in SMSC (optional)
-          class    : uint (0..3) - Message importance and location (optional)
-          completed: boolean - Whether all message parts have been received or not (optional)
-          index    : uint - Index of message (for Get and Delete) (optional)
-        </tp:docstring>
-      </arg>
-    </method>
-
-    <method name="List">
-      <tp:docstring>
-        Retrieve all SMS messages.
-      </tp:docstring>
-      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_gsm_modem_sms_list"/>
-      <arg name="result" type="aa{sv}" direction="out">
-        <tp:docstring>
-          An array of dictionaries, each dictionary representing an SMS message.
-          Each dictionary contains key/value pairs as described by the Get
-          method.
-        </tp:docstring>
-      </arg>
-    </method>
-
-    <method name="Send">
-      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_gsm_modem_sms_send"/>
-      <arg name="properties" type="a{sv}" direction="in">
-	<tp:docstring>
-	  SMS properties to save with the following key values:
-
-	  number   : string - Phone number (mandatory)
-	  text     : string - SMS text (mandatory)
-	  smsc     : string - SMS service center number (optional)
-	  validity : uint (0..255) - Specifies when the SMS expires in SMSC (optional)
-	  class    : uint (0..3) - Message importance and location (optional)
-	</tp:docstring>
-      </arg>
-      <arg name="result" type="au" direction="out"/>
-    </method>
-
-    <!-- SIGNALS -->
-
-    <signal name="SmsReceived">
-      <tp:docstring>
-        Emitted when any part of a new SMS has been received (but not for
-        subsequent parts, if any).  Not all parts may have been received and the
-        message may not be complete; if it is, the 'complete' argument will be
-        TRUE.
-      </tp:docstring>
-      <arg name="index" type="u">
-        <tp:docstring>
-          Index of the new SMS.
-        </tp:docstring>
-      </arg>
-      <arg name="complete" type="b">
-        <tp:docstring>
-          TRUE if all message parts have been received, otherwise FALSE.
-        </tp:docstring>
-      </arg>
-    </signal>
-
-    <signal name="Completed">
-      <tp:docstring>
-        Emitted when the complete-ness status of an SMS message changes. An SMS
-        may not necessarily be complete when the first part is received; this
-        signal will be emitted when all parts have been received, even for
-        single-part messages.
-      </tp:docstring>
-      <arg name="index" type="u">
-        <tp:docstring>
-          The index of the SMS.
-        </tp:docstring>
-      </arg>
-      <arg name="completed" type="b">
-        <tp:docstring>
-          TRUE if all message parts have been received, otherwise FALSE.
-        </tp:docstring>
-      </arg>
-    </signal>
-
-  </interface>
-</node>
diff --git a/new/org.freedesktop.ModemManager1.Modem.Messaging.xml b/new/org.freedesktop.ModemManager1.Modem.Messaging.xml
new file mode 100644
index 00000000..165cedff
--- /dev/null
+++ b/new/org.freedesktop.ModemManager1.Modem.Messaging.xml
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <interface name="org.freedesktop.ModemManager1.Modem.Messaging">
+
+    <tp:docstring>
+      This interface handles sending SMS messages and notification of new
+      incoming messages.
+    </tp:docstring>
+
+    <!-- METHODS -->
+
+    <method name="List">
+      <tp:docstring>
+        Retrieve all SMS messages.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_messaging_list"/>
+      <arg name="result" type="a{oa{sv}}" direction="out">
+        <tp:docstring>
+          A dict of message object paths mapped to a dictionary containing that
+          message's properties as specified in the
+          org.freedesktop.ModemManager1.Modem.SMS D-Bus interface.  This method
+          should only be used once and subsequent information retreived either
+          by listening for the Received and Completed signals, or by querying
+          the specific SMS object of interest.
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <method name="Delete">
+      <tp:docstring>
+	Delete an SMS message.  Alternatively you may use the Delete() method
+	on the message object itself.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_messaging_delete"/>
+      <arg name="path" type="o" direction="in">
+	<tp:docstring>
+	  The object path of the SMS to delete.
+	</tp:docstring>
+      </arg>
+    </method>
+
+    <method name="Create">
+      <tp:docstring>
+        Creates a new message object and optionally queues it for delivery.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_messaging_create"/>
+      <arg name="properties" type="a{sv}" direction="in">
+	<tp:docstring>
+	  Message properties from the org.freedesktop.ModemManager1.Modem.SMS
+	  D-Bus interface.  The 'Number' and 'Text' properties are mandatory,
+	  others are optional.  If the SMSC is not specified and one is
+	  required, the default SMSC is used.
+	</tp:docstring>
+      </arg>
+      <arg name="send" type="b" direction="in">
+        <tp:docstring>
+          If TRUE, queue the message for immediate delivery.
+        </tp:docstring>
+      </arg>
+      <arg name="path" type="o" direction="out">
+        <tp:docstring>
+          The object path of the new message object.
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <!-- SIGNALS -->
+
+    <signal name="Added">
+      <tp:docstring>
+        Emitted when any part of a new SMS has been received or added (but not
+        for subsequent parts, if any).  For messages received from the network,
+        not all parts may have been received and the message may not be
+        complete.  The Completed signal will be emitted when the message is
+        complete.
+      </tp:docstring>
+      <arg name="path" type="o">
+        <tp:docstring>
+          Object path of the new SMS.
+        </tp:docstring>
+      </arg>
+      <arg name="received" type="b">
+        <tp:docstring>
+          TRUE if the message was received from the network, as opposed to being
+          added locally.
+        </tp:docstring>
+      </arg>
+      <arg name="properties" type="a{sv}">
+	<tp:docstring>
+	  Message properties from the org.freedesktop.ModemManager1.Modem.SMS
+	  D-Bus interface.  Check the 'State' property to determine if the
+	  message is complete.
+	</tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="Completed">
+      <tp:docstring>
+        Emitted when the complete-ness status of an SMS message changes. An SMS
+        may not necessarily be complete when the first part is received; this
+        signal will be emitted when all parts have been received, even for
+        single-part messages.
+      </tp:docstring>
+      <arg name="path" type="o">
+        <tp:docstring>
+          Object path of the new SMS.
+        </tp:docstring>
+      </arg>
+      <arg name="properties" type="a{sv}">
+	<tp:docstring>
+	  Message properties from the org.freedesktop.ModemManager1.Modem.SMS
+	  D-Bus interface.
+	</tp:docstring>
+      </arg>
+    </signal>
+
+    <signal name="Deleted">
+      <tp:docstring>
+        Emitted when a message has been deleted.
+      </tp:docstring>
+      <arg name="path" type="o">
+        <tp:docstring>
+          Object path of the now deleted SMS.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+  </interface>
+</node>
diff --git a/new/org.freedesktop.ModemManager1.Modem.SMS.xml b/new/org.freedesktop.ModemManager1.Modem.SMS.xml
new file mode 100644
index 00000000..17f9ddac
--- /dev/null
+++ b/new/org.freedesktop.ModemManager1.Modem.SMS.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <interface name="org.freedesktop.ModemManager1.Modem.SMS">
+
+    <tp:docstring>
+      Defines operations and properties of a single SMS message.
+    </tp:docstring>
+
+    <!-- METHODS -->
+
+    <method name="Delete">
+      <tp:docstring>
+        Deletes the message.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_sms_delete"/>
+    </method>
+
+    <method name="Send">
+      <tp:docstring>
+        If the message has not yet been sent, queue it for delivery.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_sms_send"/>
+    </method>
+
+    <!-- PROPERTIES -->
+
+    <property name="State" type="u" access="read" tp:type="MM_MODEM_SMS_STATE">
+      <tp:docstring>
+        Describes the state of the message.
+      </tp:docstring>
+    </property>
+
+    <property name="To" type="s" access="readwrite">
+      <tp:docstring>
+        Indicates the number to which the message is addressed.
+      </tp:docstring>
+    </property>
+
+    <property name="Text" type="s" access="readwrite">
+      <tp:docstring>
+        Message text.  When sending, if the text is larger than the limit of
+        the technology or modem, the message will be broken into multiple
+        parts or messages.
+      </tp:docstring>
+    </property>
+
+    <property name="Smsc" type="s" access="readwrite">
+      <tp:docstring>
+        Indicates the SMS service center number.  Always empty for 3GPP2/CDMA.
+      </tp:docstring>
+    </property>
+
+    <property name="Validity" type="u" access="readwrite">
+      <tp:docstring>
+        Specifies when the SMS expires in the SMSC.  Always 0 for 3GPP2/CDMA.
+      </tp:docstring>
+    </property>
+
+    <property name="Class" type="u" access="readwrite">
+      <tp:docstring>
+        3GPP message class (0..3).  Always 0 for 3GPP2/CDMA.
+      </tp:docstring>
+    </property>
+
+    <property name="Timestamp" type="s" access="read">
+      <tp:docstring>
+        Time message was received or was sent in ISO8601 format.
+      </tp:docstring>
+    </property>
+
+    <!-- ENUMS -->
+
+    <tp:enum name="MM_MODEM_SMS_STATE" type="u">
+      <tp:enumvalue suffix="UNKNOWN" value="0">
+        <tp:docstring>
+          State unknown or not reportable.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="STORED" value="0">
+        <tp:docstring>
+          The message has been neither received nor yet sent.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="RECEIVING" value="1">
+        <tp:docstring>
+          The message is being received but is not yet complete.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="RECEIVED" value="2">
+        <tp:docstring>
+          The message received and is complete.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="SENDING" value="3">
+        <tp:docstring>
+          The message is queued for delivery.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="SENT" value="4">
+        <tp:docstring>
+          The message was successfully sent.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+  </interface>
+</node>