spec: added documentation of the D-Bus new protocol

4 files changed, 50 insertions, 1 deletions

diff --git a/spec/ContextKit.xml b/spec/ContextKit.xml
new file mode 100644
index 00000000..da6a70ba
--- /dev/null
+++ b/spec/ContextKit.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<node name="/org/maemo/contextkit/Some/Property"
+      xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <interface name="org.maemo.contextkit.Property">
+    <method name="Subscribe">
+      <tp:docstring>
+	Subscribes to the context property.
+      </tp:docstring>
+      <arg name="value" type="av" tp:type="Maybe_Variant" direction="out">
+	<tp:docstring>
+	  The actual value at the of subscription.
+	</tp:docstring>
+      </arg>
+      <arg name="timestamp" type="t" direction="out">
+	<tp:docstring>
+	  The timestamp of the value.
+	</tp:docstring>
+      </arg>
+    </method>
+    <method name="Unsubscribe">
+      <tp:docstring>
+	Unsubscribes from the property.
+      </tp:docstring>
+    </method>
+    <method name="Get">
+      <tp:docstring>
+	Returns the actual value from the provider without subscribing to it.
+      </tp:docstring>
+      <arg name="value" type="av" tp:type="Maybe_Variant" direction="out"/>
+      <arg name="timestamp" type="t" direction="out"/>
+    </method>
+    <signal name="Changed">
+      <tp:docstring>
+	Emitted when the value changed and there are at least one subscribed client.
+      </tp:docstring>
+      <arg name="value" type="av" tp:type="Maybe_Variant"/>
+      <arg name="timestamp" type="t"/>
+    </signal>
+  </interface>
+</node>
diff --git a/spec/Makefile.am b/spec/Makefile.am
index e22b2413..6450fcac 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -17,7 +17,8 @@ SPEC_TOOLS = spec-to-introspect.xsl \
 
 INTERFACES = \
 	Manager.xml \
-	Subscriber.xml
+	Subscriber.xml \
+	ContextKit.xml
 
 SPEC_FILES = \
 	$(INTERFACES) \
diff --git a/spec/all.xml b/spec/all.xml
index a73b1dcb..c2132a60 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -25,5 +25,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 
 <xi:include href="Manager.xml"/>
 <xi:include href="Subscriber.xml"/>
+<xi:include href="ContextKit.xml"/>
 <xi:include href="generic-types.xml"/>
 </tp:spec>
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index f2bd4940..f3ab3227 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -7,6 +7,12 @@
     <tp:member type="v" name="Value"/>
   </tp:mapping>
 
+  <tp:simple-type name="Maybe_Variant" type="av">
+    <tp:docstring>A list of variants where empty list represents
+    unknown, otherwise it represents the same variant as the contained
+    first variant.  This hack is needed because D-Bus doesn't support
+    null values on the wire.</tp:docstring>
+  </tp:simple-type>
 </tp:generic-types>