[telepathy-doc/master] Add a chunk of examples to the TpProps section

[Davyd Madeley]

---
 docs/book/C/basics.xml                            |   59 +++++++++++++++++++++
 docs/examples/glib_telepathy_properties/example.c |   14 +++++
 2 files changed, 73 insertions(+), 0 deletions(-)

diff --git a/docs/book/C/basics.xml b/docs/book/C/basics.xml
index 354dd9d..057998b 100644
--- a/docs/book/C/basics.xml
+++ b/docs/book/C/basics.xml
@@ -1610,6 +1610,65 @@ AC_SUBST(EXAMPLE_LIBS)</programlisting>
     </para>
    </sect2>
 
+   <sect2 id="sect.basics.tpproperties.glib">
+    <title>telepathy-glib</title>
+
+    <para>
+     telepathy-glib provides no specific support infrastructure for
+     Telepathy Properties. You can set up some simple infrastructure for
+     handling properties in your project and attach it to the
+     <classname>TpProxy</classname>.
+    </para>
+
+    <sect3 id="sect.basics.tpproperties.glib.setup">
+     <title>Setup and Listing Properties</title>
+
+     <example id="ex.basics.tpproperties.setup"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Telepathy Properties Setup</title>
+     </example>
+
+     <example id="ex.basics.tpproperties.list"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Listing Telepathy Properties</title>
+     </example>
+    </sect3>
+
+    <sect3 id="sect.basics.tpproperties.glib.get">
+     <title>Getting Properties</title>
+
+     <example id="ex.basics.tpproperties.get"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Getting Telepathy Properties</title>
+     </example>
+
+     <example id="ex.basics.tpproperties.getcb"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Get Telepathy Properties Callback</title>
+     </example>
+    </sect3>
+
+    <sect3 id="sect.basics.tpproperties.glib.set">
+     <title>Setting Properties</title>
+
+     <example id="ex.basics.tpproperties.set"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Setting Telepathy Properties</title>
+     </example>
+
+     <example id="ex.basics.tpproperties.changecb"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Telepathy Properties Changed Callback</title>
+     </example>
+
+     <example id="ex.basics.tpproperties.flagchangecb"
+              file="glib_telepathy_properties/example.c">
+      <title>telepathy-glib Telepathy Property Flags Changed Callback</title>
+     </example>
+
+    </sect3>
+   </sect2>
+
   </sect1>
 
 </chapter>
diff --git a/docs/examples/glib_telepathy_properties/example.c b/docs/examples/glib_telepathy_properties/example.c
index 5239be0..b5c9fa1 100644
--- a/docs/examples/glib_telepathy_properties/example.c
+++ b/docs/examples/glib_telepathy_properties/example.c
@@ -15,6 +15,7 @@ static GMainLoop *loop = NULL;
 static TpDBusDaemon *bus_daemon = NULL;
 static TpConnection *conn = NULL;
 
+/* begin ex.basics.tpproperties.setup */
 typedef struct _TpProperty TpProperty;
 struct _TpProperty
 {
@@ -88,6 +89,7 @@ tp_property_init (TpProxy *proxy)
 	g_object_set_data (G_OBJECT (proxy), "tpproperties-array", array);
 	g_object_set_data (G_OBJECT (proxy), "tpproperties-map", map);
 }
+/* end ex.basics.tpproperties.setup */
 
 static void
 handle_error (const GError *error)
@@ -100,6 +102,7 @@ handle_error (const GError *error)
 	}
 }
 
+/* begin ex.basics.tpproperties.changecb */
 static void
 tp_properties_changed_cb (TpProxy	  *channel,
 			  const GPtrArray *properties,
@@ -124,7 +127,9 @@ tp_properties_changed_cb (TpProxy	  *channel,
 		g_free (str);
 	}
 }
+/* end ex.basics.tpproperties.changecb */
 
+/* begin ex.basics.tpproperties.flagchangecb */
 static void
 tp_property_flags_changed_cb (TpProxy		*channel,
 			      const GPtrArray	*properties,
@@ -145,7 +150,9 @@ tp_property_flags_changed_cb (TpProxy		*channel,
 			g_value_get_uint (g_value_array_get_nth (property, 1)));
 	}
 }
+/* end ex.basics.tpproperties.flagchangecb */
 
+/* begin ex.basics.tpproperties.getcb */
 static void
 tp_properties_get_cb (TpProxy		*channel,
 		      const GPtrArray	*properties,
@@ -173,7 +180,9 @@ tp_properties_get_cb (TpProxy		*channel,
 		g_free (str);
 	}
 }
+/* end ex.basics.tpproperties.getcb */
 
+/* begin ex.basics.tpproperties.list */
 static void
 list_properties_cb (TpProxy		*channel,
 		    const GPtrArray	*available_properties,
@@ -216,11 +225,13 @@ list_properties_cb (TpProxy		*channel,
 		func (channel);
 	}
 }
+/* end ex.basics.tpproperties.list */
 
 static void
 tpproperties_ready (TpChannel	*channel)
 {
 	{ /* pack the readable properties into a GArray */
+		/* begin ex.basics.tpproperties.get */
 		GArray *array = g_array_new (FALSE, FALSE, sizeof (guint));
 		int i;
 
@@ -241,9 +252,11 @@ tpproperties_ready (TpChannel	*channel)
 				NULL, NULL, NULL);
 
 		g_array_free (array, TRUE);
+		/* end ex.basics.tpproperties.get */
 	}
 
 	{ /* set some properties */
+		/* begin ex.basics.tpproperties.set */
 		GPtrArray *array = g_ptr_array_new ();
 
 		/* FIXME we're assuming this property exists, we should check */
@@ -274,6 +287,7 @@ tpproperties_ready (TpChannel	*channel)
 		/* we need to unset array */
 		g_ptr_array_foreach (array, (GFunc) g_value_array_free, NULL);
 		g_ptr_array_free (array, TRUE);
+		/* end ex.basics.tpproperties.set */
 	}
 }
 
-- 
1.5.6.5