[telepathy-doc/master] More on D-Bus properties

[Davyd Madeley]

---
 docs/book/C/services.xml                           |   53 +++++++++++++++++++-
 docs/examples/glib_mc5_observer/example-observer.c |    5 ++
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/docs/book/C/services.xml b/docs/book/C/services.xml
index acddd5b..8696061 100644
--- a/docs/book/C/services.xml
+++ b/docs/book/C/services.xml
@@ -166,7 +166,7 @@ observer_iface_init (gpointer g_iface, gpointer iface_data)
 
     <para>
      <application>telepathy-glib</application> provides a special class
-     mixin for handling D-Bus properties as GObject properties,
+     mixin for handling D-Bus properties,
      <classname>TpDBusPropertiesMixin</classname>.
     </para>
 
@@ -174,7 +174,7 @@ observer_iface_init (gpointer g_iface, gpointer iface_data)
      <title>Mixins</title>
      <para>
       Mixins are so called because they are mixed into a class to extend its
-      functionality. For example, a class my inherit from
+      functionality. For example, a class might inherit from
       <classname>GObject</classname> or some subclass, but then has the
       <classname>TpDBusPropertiesMixin</classname> to add additional
       functionality without having to inherit from a different class.
@@ -208,6 +208,55 @@ observer_iface_init (gpointer g_iface, gpointer iface_data)
        <title>Class structure</title>
       </example>
      </listitem>
+     <listitem>
+      <para>
+       The simplest way to use this mixin is to map D-Bus properties to
+       GObject properties.
+       Your class' class_init method provides the mapping from D-Bus
+       property names to GObject property names.
+      </para>
+      <para>
+       Each D-Bus interface requires a NULL-terminated array of
+       <type>TpDBusPropertiesMixinPropImpl</type> structures which provide
+       the mappings between property names. The class also requires a
+       NULL-terminated array of <type>TpDBusPropertiesMixinIfaceImpl</type>,
+       which gives the D-Bus interface name, and getter and setter for each
+       interface as shown in
+       <xref linkend="ex.services.glib.properties.prop-mappings"/>.
+      </para>
+      <example id="ex.services.glib.properties.prop-mappings"
+               file="glib_mc5_observer/example-observer.c">
+       <title>Property Mappings</title>
+      </example>
+      <para>
+       The mixin provides default getter and setter functions,
+       <function>tp_dbus_properties_mixin_getter_gobject_properties</function>
+       and
+       <function>tp_dbus_properties_mixin_setter_gobject_properties</function>
+       for mapping D-Bus properties to GObject properties.
+      </para>
+      <tip>
+       <para>
+        If you wish, rather than using GObject properties, you may write
+	your own getter and setter functions for handling D-Bus properties.
+       </para>
+       <para>
+        The data provided to <type>TpDBusPropertiesMixinPropImpl</type> will
+	be passed as the data to your callback.
+       </para>
+      </tip>
+     </listitem>
+     <listitem>
+      <para>
+       You must chain up the mixin's class_init method at the end of your
+       class' class_init, as shown in
+       <xref linkend="ex.services.glib.properties.chain-up"/>.
+      </para>
+      <example id="ex.services.glib.properties.chain-up"
+               file="glib_mc5_observer/example-observer.c">
+       <title>Property Mappings</title>
+      </example>
+     </listitem>
     </itemizedlist>
    </sect2>
 
diff --git a/docs/examples/glib_mc5_observer/example-observer.c b/docs/examples/glib_mc5_observer/example-observer.c
index 7ee5524..a3aa381 100644
--- a/docs/examples/glib_mc5_observer/example-observer.c
+++ b/docs/examples/glib_mc5_observer/example-observer.c
@@ -105,6 +105,7 @@ example_observer_class_init (ExampleObserverClass *klass)
 
   object_class->get_property = example_observer_get_property;
 
+  /* begin ex.services.glib.properties.prop-mappings */
   /* D-Bus properties are exposed as GObject properties through the
    * TpDBusPropertiesMixin */
   /* properties on the Client interface */
@@ -113,6 +114,7 @@ example_observer_class_init (ExampleObserverClass *klass)
         { NULL }
   };
 
+  /* properties on the Client.Observer interface */
   static TpDBusPropertiesMixinPropImpl client_observer_props[] = {
         { "ObserverChannelFilter", "channel-filter", NULL },
         { NULL }
@@ -132,6 +134,7 @@ example_observer_class_init (ExampleObserverClass *klass)
         },
         { NULL }
   };
+  /* end ex.services.glib.properties.prop-mappings */
 
   g_object_class_install_property (object_class, PROP_INTERFACES,
       g_param_spec_boxed ("interfaces",
@@ -147,10 +150,12 @@ example_observer_class_init (ExampleObserverClass *klass)
                           TP_ARRAY_TYPE_CHANNEL_CLASS_LIST,
                           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+  /* begin ex.services.glib.properties.chain-up */
   /* call our mixin class init */
   klass->dbus_props_class.interfaces = prop_interfaces;
   tp_dbus_properties_mixin_class_init (object_class,
       G_STRUCT_OFFSET (ExampleObserverClass, dbus_props_class));
+  /* end ex.services.glib.properties.chain-up */
 }
 
 static void
-- 
1.5.6.5