From 07fc116d5a16b1f168c120c298b747b9d9bbe8d8 Mon Sep 17 00:00:00 2001
From: Dan Williams <dcbw@redhat.com>
Date: Tue, 9 Mar 2010 18:10:34 -0800
Subject: [PATCH] api: add USSD API proposal

Loosely based on oFono, from Pablo Marti.
---
 introspection/Makefile.am           |  3 +-
 introspection/all.xml               |  1 +
 introspection/mm-modem-gsm-ussd.xml | 73 +++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 introspection/mm-modem-gsm-ussd.xml

diff --git a/introspection/Makefile.am b/introspection/Makefile.am
index 175162cc..941c9244 100644
--- a/introspection/Makefile.am
+++ b/introspection/Makefile.am
@@ -14,4 +14,5 @@ EXTRA_DIST = \
 	mm-modem-gsm-sms.xml \
 	mm-modem-simple.xml \
 	mm-serial-error.xml \
-	mm-modem-location.xml
+	mm-modem-location.xml \
+	mm-modem-gsm-ussd.xml
diff --git a/introspection/all.xml b/introspection/all.xml
index 30725c73..967e90da 100644
--- a/introspection/all.xml
+++ b/introspection/all.xml
@@ -33,6 +33,7 @@
   <xi:include href="mm-modem-gsm-network.xml"/>
   <xi:include href="mm-modem-gsm-sms.xml"/>
   <xi:include href="mm-modem-gsm-hso.xml"/>
+  <xi:include href="mm-modem-gsm-ussd.xml"/>
 
   <xi:include href="mm-serial-error.xml"/>
   <xi:include href="mm-modem-error.xml"/>
diff --git a/introspection/mm-modem-gsm-ussd.xml b/introspection/mm-modem-gsm-ussd.xml
new file mode 100644
index 00000000..f1f99fb4
--- /dev/null
+++ b/introspection/mm-modem-gsm-ussd.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+  <interface name="org.freedesktop.ModemManager.Modem.Gsm.Ussd">
+    <method name="Initiate">
+      <tp:docstring>
+        Sends a USSD command string to the network initiating a USSD session.
+        When the request is handled by the network, the method returns the
+        response or an appropriate error.  The network may be awaiting further
+        response from the ME after returning from this method and no new command
+        can be initiated until this one is cancelled or ended.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_gsm_ussd_initiate"/>
+      <arg name="command" type="s" direction="in">
+        <tp:docstring>
+          The command to start the USSD session with.
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <method name="Respond">
+      <tp:docstring>
+        Respond to a USSD request that is either initiated by the mobile network,
+        or that is awaiting further input after Initiate() was called.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_gsm_ussd_respond"/>
+      <arg name="response" type="s" direction="in">
+        <tp:docstring>
+          The response to network-initiated USSD command, or a response to a 
+          request for further input.
+      </tp:docstring>
+      </arg>
+    </method>
+
+    <method name="Cancel">
+      <tp:docstring>
+        Cancel an ongoing USSD session, either mobile or network initiated.
+      </tp:docstring>
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_gsm_ussd_cancel"/>
+    </method>
+
+    <property name="State" type="s" access="read">
+      <tp:docstring>
+        Indicates the state of any ongoing USSD session.  Values may be one of
+        the following: "idle" (no active session), "active" (a session is active
+        and the mobile is waiting for a response), "user-response" (the network
+        is waiting for the client's response, which must be sent using Respond()).
+      </tp:docstring>
+    </property>
+
+    <property name="NetworkNotification" type="s" access="read">
+      <tp:docstring>
+        Contains any network-initiated request to which no USSD response is
+        required.  When no USSD session is active, or when there is no network-
+        initiated request, this property will be a zero-length string.
+      </tp:docstring>
+    </property>
+
+    <property name="NetworkRequest" type="s" access="read">
+      <tp:docstring>
+        Contains any pending network-initiated request for a response.  Client
+        should call Respond() with the appropriate response to this request.
+        When no USSD session is active, or when there is no pending
+        network-initiated request, this property will be a zero-length string.
+      </tp:docstring>
+    </property>
+
+  </interface>
+</node>