In examples, generate extended interfaces in their own subdirectory (more like what you'd do in practice), combining client and service code

20071219141037-53eee-18dfe05d6d64447a53831aa28ce585f447896039.gz

8 files changed, 355 insertions, 0 deletions

diff --git a/examples/extensions/.git-darcs-dir b/examples/extensions/.git-darcs-dir
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/examples/extensions/.git-darcs-dir
diff --git a/examples/extensions/Connection_Interface_Hats.xml b/examples/extensions/Connection_Interface_Hats.xml
new file mode 100644
index 000000000..efaca6a3e
--- /dev/null
+++ b/examples/extensions/Connection_Interface_Hats.xml
@@ -0,0 +1,138 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Hats"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright> Copyright (C) 2007 Collabora Ltd.</tp:copyright>
+  <tp:copyright> Copyright (C) 2007 Nokia Corporation</tp:copyright>
+  <tp:license>
+    Copying and distribution of this file, with or without modification,
+    are permitted in any medium without royalty provided the copyright
+    notice and this notice are preserved.
+  </tp:license>
+  <interface name="com.example.Telepathy.Connection.Interface.Hats"
+    tp:causes-havoc='a silly example'>
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      This interface is an example of how Telepathy can be extended.
+      For the purposes of this example, we pretend we're an organisation
+      example.com that's adding a proprietary extension to Telepathy,
+      so the extension is not in the main Telepathy namespace.
+    </tp:docstring>
+
+    <tp:struct name="Contact_Hat" array-name="Contact_Hat_List">
+      <tp:docstring>A data structure representing a contact and their
+        hat.</tp:docstring>
+      <tp:member type="u" name="Contact" tp:type="Contact_Handle">
+        <tp:docstring>The contact wearing the hat.</tp:docstring>
+      </tp:member>
+      <tp:member type="s" name="Color">
+        <tp:docstring>The color of the hat</tp:docstring>
+      </tp:member>
+      <tp:member type="u" name="Style" tp:type="Hat_Style">
+        <tp:docstring>The style of the hat</tp:docstring>
+      </tp:member>
+      <tp:member type="a{sv}" name="Properties" tp:type="String_Variant_Map">
+        <tp:docstring>Optional key-value pairs describing extended
+          properties of the hat.</tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:enum name="Hat_Style" type="u">
+      <tp:enumvalue suffix="None" value="0">
+        <tp:docstring>There is no hat. color MUST be the empty
+          string and properties MUST be an empty mapping.</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Other" value="1">
+        <tp:docstring>An unspecified type of hat.</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Fedora" value="2">
+        <tp:docstring>A fedora, which MAY be red.</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Knitted" value="3">
+        <tp:docstring>A knitted hat, with or without a bobble.</tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Bowler" value="4">
+        <tp:docstring>A bowler hat, as worn by stereotypical English
+          businessmen.</tp:docstring>
+      <tp:enumvalue suffix="Helmet" value="5">
+        <tp:docstring>A hat with protective qualities.</tp:docstring>
+      </tp:enumvalue>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <signal name="HatsChanged">
+      <tp:docstring>
+        Emitted when the contact's hat has changed.
+      </tp:docstring>
+      <arg name="Contact" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The handle representing the contact's ID on the server
+        </tp:docstring>
+      </arg>
+      <arg name="Color" type="s">
+        <tp:docstring>
+          The color of the contact's hat.
+        </tp:docstring>
+      </arg>
+      <arg name="Style" type="u" tp:type="Hat_Style">
+        <tp:docstring>
+          The style of the contact's hat.
+        </tp:docstring>
+      </arg>
+      <arg name="Properties" type="a{sv}" tp:type="String_Variant_Map">
+        <tp:docstring>
+          There's always an a{sv}. Perhaps there's some special religious
+          reason.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <method name="GetHats">
+      <tp:docstring>
+        Request a list of the hats worn by the given contacts.
+      </tp:docstring>
+      <arg direction="in" name="Contact" type="au" tp:type="Contact_Handle">
+        <tp:docstring>
+          The handles of the contacts whose hats are requested
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="Hats" type="a(usua{sv})"
+        tp:type="Contact_Hat[]">
+        <tp:docstring>
+          A list of contacts and their hats.
+        </tp:docstring>
+      </arg>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="SetHat">
+      <tp:docstring>
+        Indicate that the hat currently being worn by the local user
+        has changed.
+      </tp:docstring>
+      <arg name="Color" type="s">
+        <tp:docstring>
+          The color of the contact's hat.
+        </tp:docstring>
+      </arg>
+      <arg name="Style" type="u" tp:type="Hat_Style">
+        <tp:docstring>
+          The style of the contact's hat.
+        </tp:docstring>
+      </arg>
+      <arg name="Properties" type="a{sv}" tp:type="String_Variant_Map">
+        <tp:docstring>
+          There's always an a{sv}...
+        </tp:docstring>
+      </arg>
+    </method>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/examples/extensions/Makefile.am b/examples/extensions/Makefile.am
new file mode 100644
index 000000000..e85c626d4
--- /dev/null
+++ b/examples/extensions/Makefile.am
@@ -0,0 +1,140 @@
+# This directory is an example of how to build extensions to the spec.
+# Typically this would be in a top-level extensions/ directory.
+#
+# In this example we build an extension for the TpConnection class,
+# by using "--subclass=TpConnection --subclass-assert=TP_IS_CONNECTION".
+# We could instead (or additionally) have made an extension for any other
+# class, or by omitting those options entirely we could have made an extension
+# that will work on TpProxy or any subclass of TpProxy.
+
+tools_dir = $(top_srcdir)/tools
+
+AM_CFLAGS = \
+    $(ERROR_CFLAGS) \
+    $(DBUS_CFLAGS) \
+    $(GLIB_CFLAGS) \
+    $(TP_GLIB_CFLAGS)
+
+EXTRA_DIST = \
+    all.xml \
+    connection.xml \
+    Connection_Interface_Hats.xml
+
+noinst_LTLIBRARIES = libexample-extensions.la
+
+libexample_extensions_la_LIBADD = \
+    $(TP_GLIB_LIBS)
+
+# The client-specific parts are built into a separate .o file, so the linker
+# can discard them when linking services. The service-specific parts are
+# in svc-*.c, so we don't need an extensions-svc.c.
+libexample_extensions_la_SOURCES = \
+    extensions.c \
+    extensions-cli.c \
+    extensions.h
+
+nodist_libexample_extensions_la_SOURCES = \
+    _gen/signals-marshal.c \
+    _gen/signals-marshal.h \
+    _gen/signals-marshal.list \
+    _gen/register-dbus-glib-marshallers-body.h \
+    _gen/enums.h \
+    _gen/gtypes.h \
+    _gen/gtypes-body.h \
+    _gen/interfaces.h \
+    _gen/interfaces-body.h \
+    _gen/cli-connection.h \
+    _gen/cli-connection-body.h \
+    _gen/svc-connection.h \
+    _gen/svc-connection.c
+
+BUILT_SOURCES = \
+    _gen/all.xml \
+    _gen/connection.xml \
+    $(nodist_libexample_extensions_la_SOURCES) \
+    extensions.html
+
+CLEANFILES = $(BUILT_SOURCES)
+
+XSLTPROCFLAGS = --nonet --novalid
+
+# Generated files which can be generated for all categories simultaneously
+
+_gen/all.xml: all.xml $(wildcard *.xml)
+	$(mkdir_p) _gen
+	$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \
+		$< > $@
+
+extensions.html: _gen/all.xml $(tools_dir)/doc-generator.xsl
+	$(XSLTPROC) $(XSLTPROCFLAGS) \
+		$(tools_dir)/doc-generator.xsl \
+		$< > $@
+
+_gen/gtypes.h _gen/gtypes-body.h: _gen/all.xml \
+	$(top_srcdir)/tools/glib-gtypes-generator.py
+	$(PYTHON) $(top_srcdir)/tools/glib-gtypes-generator.py \
+		$< _gen/gtypes Example
+
+_gen/signals-marshal.list: _gen/all.xml \
+	$(tools_dir)/glib-signals-marshal-gen.py
+	$(PYTHON) $(tools_dir)/glib-signals-marshal-gen.py $< > $@
+
+_gen/signals-marshal.h: _gen/signals-marshal.list
+	$(GLIB_GENMARSHAL) --header --prefix=_example_ext_marshal $< > $@
+
+_gen/signals-marshal.c: _gen/signals-marshal.list
+	$(GLIB_GENMARSHAL) --body --prefix=_example_ext_marshal $< > $@
+
+_gen/register-dbus-glib-marshallers-body.h: _gen/all.xml \
+	$(tools_dir)/glib-client-marshaller-gen.py
+	$(PYTHON) $(tools_dir)/glib-client-marshaller-gen.py $< \
+		_example_ext > $@
+
+_gen/enums.h: _gen/all.xml $(tools_dir)/c-constants-generator.xsl
+	$(XSLTPROC) $(XSLTPROCFLAGS) \
+		--stringparam mixed-case-prefix Example \
+		$(tools_dir)/c-constants-generator.xsl \
+		$< > $@
+
+_gen/interfaces.h: _gen/all.xml \
+	$(tools_dir)/glib-interfaces-generator.xsl \
+	$(tools_dir)/c-interfaces-generator.xsl
+	$(XSLTPROC) $(XSLTPROCFLAGS) \
+		--stringparam mixed-case-prefix Example \
+		$(tools_dir)/glib-interfaces-generator.xsl \
+		$< > $@
+
+_gen/interfaces-body.h: _gen/all.xml \
+	$(tools_dir)/glib-interfaces-body-generator.xsl \
+	$(tools_dir)/c-interfaces-generator.xsl
+	$(XSLTPROC) $(XSLTPROCFLAGS) \
+		--stringparam mixed-case-prefix Example \
+		$(tools_dir)/glib-interfaces-body-generator.xsl \
+		$< > $@
+
+# Generated files which must be generated per "category". Each TpProxy
+# subclass you want to use with --subclass will need to have its own category,
+# although you can subdivide further if you want.
+
+_gen/connection.xml: connection.xml $(wildcard *.xml)
+	$(mkdir_p) _gen
+	$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \
+		$< > $@
+
+_gen/cli-connection-body.h _gen/cli-connection.h: _gen/connection.xml \
+	$(tools_dir)/glib-client-gen.py
+	$(PYTHON) $(tools_dir)/glib-client-gen.py \
+		--group=connection \
+		--subclass=TpConnection \
+		--subclass-assert=TP_IS_CONNECTION \
+		$< Example_Cli _gen/cli-connection
+
+_gen/svc-connection.c _gen/svc-connection.h: _gen/connection.xml \
+	$(tools_dir)/glib-ginterface-gen.py
+	$(PYTHON) $(tools_dir)/glib-ginterface-gen.py \
+		--filename=_gen/svc-connection \
+		--signal-marshal-prefix=_example_ext \
+		--include='<telepathy-glib/dbus.h>' \
+		--include='"_gen/signals-marshal.h"' \
+		--not-implemented-func='tp_dbus_g_method_return_not_implemented' \
+		$< Example_Svc_
diff --git a/examples/extensions/all.xml b/examples/extensions/all.xml
new file mode 100644
index 000000000..52bbbe36d
--- /dev/null
+++ b/examples/extensions/all.xml
@@ -0,0 +1,16 @@
+<tp:spec
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+  xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<tp:title>Extensions for 'extended' examples</tp:title>
+
+<xi:include href="connection.xml"/>
+
+<tp:generic-types>
+  <tp:external-type name="Contact_Handle" type="u"
+    from="Telepathy specification"/>
+  <tp:external-type name="String_Variant_Map" type="a{sv}"
+    from="Telepathy specification"/>
+</tp:generic-types>
+
+</tp:spec>
diff --git a/examples/extensions/connection.xml b/examples/extensions/connection.xml
new file mode 100644
index 000000000..242fb1f5f
--- /dev/null
+++ b/examples/extensions/connection.xml
@@ -0,0 +1,9 @@
+<tp:spec
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+  xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<tp:title>Connection extensions for 'extended' example</tp:title>
+
+<xi:include href="Connection_Interface_Hats.xml"/>
+
+</tp:spec>
diff --git a/examples/extensions/extensions-cli.c b/examples/extensions/extensions-cli.c
new file mode 100644
index 000000000..e9da39042
--- /dev/null
+++ b/examples/extensions/extensions-cli.c
@@ -0,0 +1,23 @@
+#include "extensions.h"
+
+#include <telepathy-glib/connection.h>
+#include <telepathy-glib/proxy-subclass.h>
+
+#include "_gen/signals-marshal.h"
+
+/* FIXME: evil hack */
+#define TP_IFACE_QUARK_CONNECTION_INTERFACE_HATS \
+  EXAMPLE_IFACE_QUARK_CONNECTION_INTERFACE_HATS
+
+/* include auto-generated stubs for client-specific code */
+#include "_gen/cli-connection-body.h"
+#include "_gen/register-dbus-glib-marshallers-body.h"
+
+void
+example_cli_conn_add_signals (TpProxy *self,
+                              guint quark,
+                              DBusGProxy *proxy,
+                              gpointer unused)
+{
+  example_cli_connection_add_signals (self, quark, proxy, unused);
+}
diff --git a/examples/extensions/extensions.c b/examples/extensions/extensions.c
new file mode 100644
index 000000000..eeda4623c
--- /dev/null
+++ b/examples/extensions/extensions.c
@@ -0,0 +1,6 @@
+#include "extensions.h"
+
+/* include auto-generated stubs for things common to service and client */
+#include "_gen/gtypes-body.h"
+#include "_gen/interfaces-body.h"
+#include "_gen/signals-marshal.h"
diff --git a/examples/extensions/extensions.h b/examples/extensions/extensions.h
new file mode 100644
index 000000000..ed2eba688
--- /dev/null
+++ b/examples/extensions/extensions.h
@@ -0,0 +1,23 @@
+#ifndef __EXAMPLE_EXTENSIONS_H__
+#define __EXAMPLE_EXTENSIONS_H__
+
+#include <glib-object.h>
+#include <telepathy-glib/connection.h>
+
+#include "examples/extensions/_gen/enums.h"
+#include "examples/extensions/_gen/cli-connection.h"
+#include "examples/extensions/_gen/svc-connection.h"
+
+G_BEGIN_DECLS
+
+#include "examples/extensions/_gen/gtypes.h"
+#include "examples/extensions/_gen/interfaces.h"
+
+void example_cli_conn_add_signals (TpProxy *self, guint quark,
+    DBusGProxy *proxy, gpointer unused);
+
+void _example_ext_register_dbus_glib_marshallers (void);
+
+G_END_DECLS
+
+#endif