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

Murray Cumming murrayc at murrayc.com
Mon Jan 26 05:45:19 PST 2009


* docs/book/C/telepathy.xml: Basics: API Conventions: Mention the
Request/Get distinction and link to the telepathy-glib conventions.
Removed the Asynchronous Calls section because we dealt with that here
and in the Using D-Bus section.
---
 ChangeLog                 |    7 +++++++
 docs/book/C/telepathy.xml |   30 +++++++++++++-----------------
 2 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b7c6fa4..3e471b3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2009-12-26  Murray Cumming  <murrayc at murrayc.com>
 
+	* docs/book/C/telepathy.xml: Basics: API Conventions: Mention the 
+	Request/Get distinction and link to the telepathy-glib conventions.
+	Removed the Asynchronous Calls section because we dealt with that here 
+	and in the Using D-Bus section.
+
+2009-12-26  Murray Cumming  <murrayc at murrayc.com>
+
 	* docs/book/C/telepathy.xml: Basics: Handles: Write this section. 
 	Removed the main Handles chapter because a) It was planned to cover the 
 	same stuff and b) It should be covered very early.
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index fc48c7a..84b6eaf 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -289,13 +289,13 @@ AC_SUBST(EXAMPLE_LIBS)
   <sect1 id="sec-basics-handles">
     <title>Handles</title>
     <para>The Telepathy D-Bus API does not have D-Bus objects to represent contacts, groups, or rooms. These are instead identified by numeric <literal>handles</literal>. This is for performance reasons, and because it is easier to compare numeric handles than to discover if two D-Bus proxy objects refer to the same object instance.</para>
-    <para>These numeric handles are only unique within a Telepathy Connection. For instance, don't try to use a Connection's contact handle with a different Connection. The handles also only make sense when combined with a <ulink url="&url_spec;#type-Handle_Type">handle type</ulink>, telling the API whether it represents a contact, group, or list.</para>
+    <para>These numeric handles are only unique within a Telepathy Connection. For instance, don't try to use a Connection's contact handle with a different Connection. The handles also only make sense when combined with a <ulink url="&url_spec;#type-Handle_Type">handle type</ulink>, telling the API whether it represents a contact, group, or list. In fact, two handles may be numerically identical but be for different types.</para>
 
     <sect2>
       <title>Hold and Release</title>
-      <para>When a Telepathy object has finished with a handle, that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to &quot;hold&quot; the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><function>HoldHandles()</function></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><function>ReleaseHandles()</function></ulink> when you have finished with the handle. However, a single <function>ReleaseHandles()</function> call will release a handle regardless of how many times <function>HoldHandles()</function> has been called, so be careful not to call it while other code may be using the handle.</para>
+      <para>When a Telepathy object has finished with a handle that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to &quot;hold&quot; the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><function>HoldHandles()</function></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><function>ReleaseHandles()</function></ulink> when you have finished with the handle. However, a single <function>ReleaseHandles()</function> call will release a handle regardless of how many times <function>HoldHandles()</function> has been called, so be careful not to call it while other code may be using the handle.</para>
 
-      <para>This is less necessary when using Telepathy <link linkend="sec-basics-language-bindings">language bindings</link>, such as telepathy-glib, because they may automatically hold and release handles for the lifetime of their objects, such as telepathy-glib's TpContact. Additionaly, telepathy-glib wraps the hold methods with the <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-hold-handles"><function>tp_connection_hold_handles()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-unref-handles"><function>tp_connection_unref_handles()</function></ulink> functions which reference-count the client-side handle &quot;hold&quot;, allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
+      <para>This is less necessary when using Telepathy <link linkend="sec-basics-language-bindings">language bindings</link>, such as telepathy-glib, because they may automatically hold and release handles for the lifetime of their objects, such as telepathy-glib's TpContact object. Additionally, telepathy-glib wraps the <function>HoldHandles()</function> and <function>ReleaseHandles()</function> D-Bus methods with the <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-hold-handles"><function>tp_connection_hold_handles()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-unref-handles"><function>tp_connection_unref_handles()</function></ulink> functions which reference-count the client-side handle &quot;hold&quot;, allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
 
       <para>In the later sections we will mention when it actually makes sense to do this when using specific parts of the Telapathy API.</para>
     </sect2>
@@ -304,22 +304,18 @@ AC_SUBST(EXAMPLE_LIBS)
 
   <sect1 id="sec-basics-api-conventions">
     <title>API conventions</title>
-    <para>TODO: Notes: For instance"Request*" vs. "Get*" - see Asynchronous Calls.
-    </para>
-  </sect1>
+    <para>Telepathy's method names follow a simple convention.</para>
+    <orderedlist>
+      <listitem><simpara>Methods prefixed with <literal>Request</literal> are aysnchronous, meaning that the result will be provided later and your application should not block while it waits. For instance, <ulink url="&url_spec_base;Connection.RequestChannel"><function>Connection.RequestChannel()</function></ulink>.</simpara></listitem>
+      <!-- TODO: What is the D-Bus convention for the separator? . or :: ? -->
+      <listitem><simpara>Methods prefixed with <literal>Get</literal> are synchronous, meaning that the result will be returned immediately. These methods generally access local information and do not need to make any contact with the remote server. For instance, <ulink url="&url_spec_base;Connection.GetStatus"><function>Connection.GetStatus()</function></ulink>.</simpara></listitem>
+    </orderedlist>
 
-  <sect1 id="sec-basics-asynchronous-calls">
-    <title>Asynchronous Calls</title>
-    <para>TODO: 
-    Notes: Most functions are synchronous, getting locally-stored data.
-    - Convention is that Get* methods access local information, but Request* 
-      methods may access the network.
-      (This convention seems to apply to the D-Bus API, but not to the telepathy-glib API. murrayc)
-    - Many Get* methods are being deprecated in favour of D-Bus properties 
-      currently (because you can do GetAll() for a given interface and download 
-      the state at once with fewer roundtrips).
-    </para>
+    <para>See the <link linkend="sec-basics-dbus">Using D-Bus section</link> to learn more about asynchronous D-Bus method calls. Note that many <literal>Get</literal> methods may be replaced with D-Bus properties in future, which will also be syncronous.</para>
+
+    <para>See also the section about <link linkend="sec-basics-language-bindings-telepathy-glib">telepathy-glib</link> section about its function naming conventions.</para>
   </sect1>
+
 </chapter>
 
 <chapter id="chapter-accounts">
-- 
1.5.6.5




More information about the Telepathy-commits mailing list