[Telepathy-commits] [telepathy-doc/master] 2009-12-20 Murray Cumming <murrayc at murrayc.com>

Murray Cumming murrayc at murrayc.com
Thu Jan 22 09:00:42 PST 2009


* docs/book/C/telepathy.xml: Basics: Move the boring stuff about
Introspect() into a notes section because it is too soon to get scary.
---
 ChangeLog                 |   17 ++++++++++++++++-
 docs/book/C/telepathy.xml |   17 +++++++++++++----
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 731fceb..ca210b8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,19 @@
-2009-12-15  Murray Cumming  <murrayc at murrayc.com>
+2009-12-20  Murray Cumming  <murrayc at murrayc.com>
+
+	* docs/book/C/telepathy.xml: Basics: Move the boring stuff about 
+	Introspect() into a notes section because it is too soon to get scary.
+
+2009-12-20  Murray Cumming  <murrayc at murrayc.com>
+
+	* docs/book/C/telepathy.xml: Basics: Write some text about optional 
+	interfaces. Added a Connection Managers section before it, so that we 
+	see the point and so we can describe the Telepathy architecture briefly.
+
+	* docs/book/C/icons/: Put the .png files in the folder instead of above.
+	* docs/book/C/figures/: Tried adding this again, adding a README because 
+	git seems to ignore it if it is empty.
+
+2009-12-20  Murray Cumming  <murrayc at murrayc.com>
 
 	* configure.ac:
 	* docs/examples/basics_dbus_python/Makefile.am:
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index dd4a5dc..76657a5 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -127,13 +127,22 @@ of the Telapathy specification.
 
   </sect1>
 
+  <sect1 id="sec-basics-connection-managers">
+    <title>Connection Managers</title>
+    <para>Support for the various communication protocols is provided by various <literal>Connection Managers</literal>. For instance, the <literal>telepathy-gabble</literal> Connection Manager provides support for the <acronym>XMPP</acronym> protocol, also known as <literal>Jabber</literal>.</para>
+    <para>There is no central &app; D-Bus service. Instead there are several connection manager services, activated on demand, and each of these connection managers provide the same core set of D-Bus interfaces, such as <ulink url="&url_spec_base;Connection">Connection</ulink> and <ulink url="&url_spec_base;Channel">Channel</ulink>, allowing application code to be written generically for all connection managers.</para>
+  </sect1>
+
+  <!-- TODO: Notes: The interfaces are often called their type, particularly for channels. Explain. -->
+  <!-- TODO: Is it only Connection that has optional interfaces? -->
   <sect1 id="sec-basics-optional-interfaces">
     <title>Optional Interfaces</title>
-    <para>TODO: Notes: Objects have main interfaces (often called their type, particularly for channels), 
-    such as <ulink url="&url_spec_base;Channel">Channel</ulink> and <ulink url="&url_spec_base;Connection">Connection</ulink> 
-    and optional D-Bus interfaces , discovered at runtime.
-    See <ulink url="&url_spec_base;Connection.GetInterfaces">Connection.GetInterfaces</ulink>:
+    <para>Although a core set of D-Bus interfaces is provided by all connection managers, some extra D-Bus interfaces are optional. For instance, some connection managers only provide extra interfaces when it discovers that the remote server provides that optional functionality. Therefore, when using these interfaces, application code should first check that the interface is available, sometimes falling back to alternative interfaces. Use the Connection interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><function>GetInterfaces()</function></ulink> method for this.</para>
+
+    <note>
+    <para>Note that the <ulink url="&url_spec_base;Connection.GetInterfaces"><function>Connection.GetInterfaces()</function></ulink> method  does more than the standard D-Bus <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-introspectable"><function>Introspectable.Introspect()</function></ulink> method. <function>GetInterfaces()</function> allows tools and language bindings to know about the possible availability of interfaces via <function>Introspect()</function> while providing an additional check that the interface is really supported for the particular connection manager with the particular remote server to which that connection manager is connected. 
     </para>
+    </note>
   </sect1>
 
   <sect1 id="sec-basics-mission-control">
-- 
1.5.6.5




More information about the Telepathy-commits mailing list