[Telepathy-commits] [telepathy-doc/master] * docs/book/C/telepathy.xml: Basics: Moved the Using D-Bus section into its own chapter because it has become too big. Mention it in the initial paragraph of the Basics chapter. Move the Language Bindings section from Basics into that Using D-Bus section because that now seems like a logical place for it.
Murray Cumming
murrayc at murrayc.com
Tue Feb 3 07:36:39 PST 2009
---
ChangeLog | 8 ++
docs/book/C/telepathy.xml | 206 +++++++++++++++++++++++----------------------
2 files changed, 113 insertions(+), 101 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 85eeae9..2d579ef 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
2009-02-03 Murray Cumming <murrayc at openismus.com>
+ * docs/book/C/telepathy.xml: Basics: Moved the Using D-Bus section
+ into its own chapter because it has become too big. Mention it in the
+ initial paragraph of the Basics chapter. Move the Language Bindings
+ section from Basics into that Using D-Bus section because that now
+ seems like a logical place for it.
+
+2009-02-03 Murray Cumming <murrayc at openismus.com>
+
* Use <methodname> instead of <function> for D-Bus method names,
as seen in Davyd's branch.
Likewise, use <interfacename> (not <interface> which is a deprecated
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index d997816..b062ebb 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -124,11 +124,61 @@ of the Telapathy specification.
<title>Basics</title>
<para>This chapter introduces some basic techniques and concepts that you must understand to use Telepathy confidently. You should read through this chapter before proceeding, but you will probably want to refer back here again later.</para>
+ <para>Telepathy is a D-Bus API, so the <link linkend="chapter-dbus">Using D-Bus</link> chapter also provides an introduction for people who are not yet familiar with the D-Bus system. However, in most cases you will use a <link linkend="chapter-language-bindings">Language Binding</link>, such as telepathy-glib.</para>
- <sect1 id="sec-basics-dbus">
+ <sect1 id="sec-basics-connection-managers">
+ <title>Connection Managers</title>
+ <para>Support for the various communication protocols is provided by several <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"><interfacename>Connection</interfacename></ulink> and <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink>, allowing application code to be written generically for all connection managers.</para>
+ </sect1>
+
+ <!-- TODO: Should we even mention this before the new (5?) version is ready?
+ <sect1 id="sec-basics-mission-control">
+ <title>Mission Control</title>
+ <para>TODO: Notes: desktop-wide accounts and dispatching to applications.
+ </para>
+ </sect1>
+ -->
+
+ <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. 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 "hold" the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><methodname>HoldHandles()</methodname></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><methodname>ReleaseHandles()</methodname></ulink> when you have finished with the handle. However, a single <methodname>ReleaseHandles()</methodname> call will release a handle regardless of how many times <methodname>HoldHandles()</methodname> 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="chapter-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 <classname>TpContact</classname> object. Additionally, telepathy-glib wraps the <methodname>HoldHandles()</methodname> and <methodname>ReleaseHandles()</methodname> 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 "hold", allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
+
+ <!-- TODO: On irc, smcv said: "perhaps "the user types in the name of a chatroom to join" would be a better example of when you want to use tp_connection_request_handles/tp_connection_unref_handles". Explain that more fully. -->
+
+ <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>
+
+ </sect1>
+
+ <sect1 id="sec-basics-api-conventions">
+ <title>API conventions</title>
+ <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"><methodname>Connection.RequestChannel()</methodname></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"><methodname>Connection.GetStatus()</methodname></ulink>.</simpara></listitem>
+ </orderedlist>
+
+ <para>See the <link linkend="chapter-dbus">Using D-Bus</link> section 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 <link linkend="sec-language-bindings-telepathy-glib">telepathy-glib</link> section about its function naming conventions.</para>
+ </sect1>
+
+</chapter>
+
+
+<chapter id="chapter-dbus">
<title>Using D-Bus</title>
<para>Telepathy is a <indexterm><primary>D-Bus</primary></indexterm>D-Bus API. Telepathy components conform to the <ulink url="&url_spec;">Telepathy D-Bus Specification</ulink>, which is therefore also the main Telepathy API reference.</para>
- <para>D-Bus is an <indexterm><primary>IPC</primary></indexterm>IPC (Inter-process communication) system, allowing different software components to be implemented in different processes, with different programming languages. It also allows multiple applications to easily share functionality from a single process. Most examples in this book will use <link linkend="sec-basics-language-bindings">language bindings</link> instead of using D-Bus directly. However, an understanding of the following D-Bus concepts will help you even when using language bindings.</para>
+ <para>D-Bus is an <indexterm><primary>IPC</primary></indexterm>IPC (Inter-process communication) system, allowing different software components to be implemented in different processes, with different programming languages. It also allows multiple applications to easily share functionality from a single process. Most examples in this book will use <link linkend="chapter-language-bindings">language bindings</link> instead of using D-Bus directly. However, an understanding of the following D-Bus concepts will help you even when using language bindings.</para>
<variablelist>
@@ -173,65 +223,84 @@ of the Telapathy specification.
<para>These programming languages allow you to call D-Bus methods synchronously, meaning that they block until they can return the method's result. However, that is generally disapproved of because the D-Bus service may take a long time to reply, and because of some fundamental technical problems with the use of blocking calls between processes. Therefore, the examples call the D-Bus method asynchronously, theoretically allowing the application to continue with other tasks while waiting for the result.</para>
<!-- TODO: Get the result asynchronously. -->
- <sect2 id="sec-basics-dbus-glib">
+ <sect1 id="sec-dbus-glib">
<title>Using D-Bus from C, with glib</title>
- <sect3 id="sect-basics-dbus-glib-methods">
+ <sect2 id="sec-dbus-glib-methods">
<title>Calling Methods</title>
<para>This example uses dbus-glib's <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-begin-call"><function>dbus_g_proxy_begin_call()</function></ulink> function to call the <literal>Notify()</literal> method on the <literal>org.freedesktop.Notification</literal> interface of the desktop notification service at the <literal>/org/freedesktop/Notification</literal> path. Note that we must specify the types of each parameter. The specified callback function then calls <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-end-call"><function>dbus_g_proxy_end_call()</function></ulink> to retreive the result.</para>
<para>We could have used the synchronous <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-call"><function>dbus_g_proxy_call()</function></ulink> function instead but, as already mentioned, asynchronous calls are generally preferred with D-Bus.</para>
<para><ulink url="&url_examples_base;basics_dbus_glib_methods">Source Code</ulink></para>
- </sect3>
+ </sect2>
- <sect3 id="sect-basics-dbus-glib-properties">
+ <sect2 id="sec-dbus-glib-properties">
<title>Using Properties</title>
<para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <methodname>Get()</methodname>, <methodname>Set()</methodname> and <methodname>GetAll</methodname> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
- <para>As of this writing, telepathy-glib has no simple API for dealing with properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sect-basics-dbus-glib-methods">Calling Methods</link> example.</para>
+ <para>As of this writing, telepathy-glib has no simple API for dealing with properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sec-dbus-glib-methods">Calling Methods</link> example.</para>
<para><ulink url="&url_examples_base;basics_dbus_glib_properties">Source Code</ulink></para>
- </sect3>
+ </sect2>
- <sect3 id="sect-basics-dbus-glib-signals">
+ <sect2 id="sec-dbus-glib-signals">
<title>Handling Signals</title>
<para>D-Bus signal handlers may be specified with dbus-glib with the <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-connect-signal"><function>dbus_g_proxy_connect_signal()</function></ulink> function. As when calling D-Bus methods, you must specify the expected types, but for signals you must do this in a previous call to <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-add-signal"><function>dbus_g_proxy_add_signal()</function></ulink>. The specified callback function will then be called when the signal is emitted. This example connects to the "DeviceAdded" signal of the "org.freedesktop.Hal.Manager" interface so it can print a message to the terminal when, for instance, you plug in a USB stick.</para>
<para><ulink url="&url_examples_base;basics_dbus_glib_signals">Source Code</ulink></para>
- </sect3>
+ </sect2>
- </sect2>
+ </sect1>
- <sect2 id="sec-basics-dbus-python">
+ <sect1 id="sec-dbus-python">
<title>Using D-Bus from Python</title>
- <sect3 id="sect-basics-dbus-python-methods">
+ <sect2 id="sec-dbus-python-methods">
<title>Calling Methods</title>
<para>This example uses <indexterm><primary>Python</primary></indexterm>Python to call the <literal>Notify()</literal> method on the <literal>org.freedesktop.Notification</literal> interface of the desktop notification service at the <literal>/org/freedesktop/Notification</literal> path.</para>
<para>Note that we specify reply and error handlers as keyword arguments, to call the method asynchronously because asynchronous calls are generally preferred with D-Bus.</para>
<para><ulink url="&url_examples_base;basics_dbus_python_methods">Source Code</ulink></para>
- </sect3>
+ </sect2>
- <sect3 id="sect-basics-dbus-python-properties">
+ <sect2 id="sec-dbus-python-properties">
<title>Using Properties</title>
<para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <methodname>Get()</methodname>, <methodname>Set()</methodname> and <methodname>GetAll</methodname> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
- <para>As of this writing, Python has no simple API for dealing with D-Bus properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sect-basics-dbus-python-methods">Calling Methods</link> example.</para>
+ <para>As of this writing, Python has no simple API for dealing with D-Bus properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sec-dbus-python-methods">Calling Methods</link> example.</para>
<para><ulink url="&url_examples_base;basics_dbus_python_properties">Source Code</ulink></para>
- </sect3>
+ </sect2>
- <sect3 id="sect-basics-dbus-python-signals">
+ <sect2 id="sec-dbus-python-signals">
<title>Handling Signals</title>
<para>D-Bus signal handlers may be specified in Python with the proxy object's <ulink url="&url_dbus_python_base;dbus.proxies.Interface-class.html#connect_to_signal"><methodname>connect_to_signal()</methodname></ulink> method. The specified callback function will then be called when the signal is emitted. This example connects to the "DeviceAdded" signal of the "org.freedesktop.Hal.Manager" interface so it can print a message to the terminal when, for instance, you plug in a USB stick.</para>
<para><ulink url="&url_examples_base;basics_dbus_python_signals">Source Code</ulink></para>
- </sect3>
+ </sect2>
- </sect2>
- </sect1>
+ </sect1>
+
+ <!-- TODO: Notes: The interfaces are often called their type, particularly for channels. Explain. -->
+ <sect1 id="sec-dbus-optional-interfaces">
+ <title>Optional Interfaces</title>
+ <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 they discover 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.</para>
+ <para>For instance, use the <interfacename>Connection</interfacename> interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>GetInterfaces()</methodname></ulink> method. For <interfacename>ConnectionManager</interfacename>s and <interfacename>Channel</interfacename>s use their <property>Interfaces</property> D-Bus property. Eventually <interfacename>Connection</interfacename> will also have an <property>Interfaces</property> property, when its <methodname>GetInterfaces()</methodname> method will be deprecated.</para>
+
+ <para>When using telepathy-glib, you can simply call the <ulink url="&url_telepathy_glib_base;proxy.html#tp-proxy-has-interface"><function>tp_proxy_has_interface()</function></ulink> function for <classname>TpConnectionManager</classname>, <classname>TpConnection</classname>, or <classname>TpChannel</classname>.</para>
+ <para>Actually, the core interfaces are only "recommended" by the Telepathy D-Bus specification so you should check before using any interface even if it is not commonly considered to be optional.</para>
+
+ <note>
+ <para>Note that the <property>Interfaces</property> property (or the <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>Connection.GetInterfaces()</methodname></ulink> method) does more than the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><methodname>Introspectable.Introspect()</methodname></ulink> method. The Telepathy-specific mechanism allows tools and language bindings to know about the possible availability of interfaces via <methodname>Introspect()</methodname> 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 id="sec-basics-language-bindings">
+ <!-- TODO: Add dbus-glib and Python examples of checking-for and using an Interface. -->
+ </sect1>
+
+</chapter>
+
+
+<chapter id="chapter-language-bindings">
<title>Language Bindings</title>
- <para>As mentioned in the <link linkend="sec-basics-dbus">Using D-Bus</link> section, many programming languages have their own generic ways of using D-Bus APIs. In addition, there are some Telepathy-specific APIs to make the use of Telepathy even easier. For instance, <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink> provides an API that is familiar to users of Glib and GTK+, using the GObject system and related conventions.</para>
+ <para>As mentioned in the <link linkend="chapter-dbus">Using D-Bus</link> section, many programming languages have their own generic ways of using D-Bus APIs. In addition, there are some Telepathy-specific APIs to make the use of Telepathy even easier. For instance, <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink> provides an API that is familiar to users of Glib and GTK+, using the GObject system and related conventions.</para>
<para>Likewise, the <ulink url="http://telepathy.freedesktop.org/wiki/TelepathyQt">Telepathy-Qt</ulink> project provides a more Qt-like API for Telepathy and <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20Python">Telepathy-Python</ulink> does the same for Python.</para> <!-- TODO: Link to Telepathy-Qt4 when it is ready. -->
<para>Remember that, like raw use of D-Bus from these programming languages, the Telepathy language bindings only create <literal>proxies</literal> to the D-Bus objects, providing a way to use their API. The actual objects are instantiated in the service's process.</para>
- <sect2 id="sec-basics-language-bindings-telepathy-glib">
+ <sect1 id="sec-language-bindings-telepathy-glib">
<title>telepathy-glib</title>
<para>The C examples in this book will use telepathy-glib, which provides a GObject-based API for the Telepathy framework.</para>
@@ -239,13 +308,13 @@ of the Telapathy specification.
<para>The reference documentation only makes sense in terms of the Telepathy D-Bus Specification.</para>
-->
- <sect3 id="sec-basics-language-bindings-telepathy-glib-async">
+ <sect2 id="sec-language-bindings-telepathy-glib-async">
<title>Asynchronous Calls</title>
<para>For each Telepathy D-Bus method, telepathy-glib generally provides both a "run" and a "call" function. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_run_connect()</ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-call-connect">tp_cli_connection_call_connect()</ulink>. The "run" function is synchronous, blocking until the D-Bus service has returned the value, whereas the "call" function is asynchronous, immediately returning and later providing the result to a callback function.</para>
<para>However, the Telepathy developers strongly discourage the use of the "run" functions, so all examples in this book will use the asynchronous "call" functions. This complicates application code but it is more robust and allows the application to be more responsive, doing more than one thing at a time.</para>
- </sect3>
+ </sect2>
- <sect3 id="sec-basics-language-bindings-telepathy-glib-generated">
+ <sect2 id="sec-language-bindings-telepathy-glib-generated">
<title>Generated Functions</title>
<para>telepathy-glib provides both hand-coded and generated API. The generated functions have these prefixes:</para>
@@ -270,16 +339,16 @@ of the Telapathy specification.
<para>The generated functions make simple direct calls to the D-Bus methods, without any additional logic and without using more appropriate types. For instance, they use unsigned integers for parameters because D-Bus does not have a concept of enumerations. However, the Telepathy D-Bus Specification does describe enumerations of possible values for these parameters, so the hand-written functions do use enums. Likewise, raw D-Bus methods can only identify object instances in terms of a <literal>bus name</literal> and <literal>object path</literal> combination, but telepathy-glib can directly provide a GObject instance that is a proxy for a D-Bus object without exposing those intermediate details.</para>
<para>Hand-coded functions have a simple <literal>tp_</literal> prefix and should be preferred whenever they exist. The generated functions exist only because hand-written functions have not yet been implemented for all Telepathy D-Bus methods.</para>
<para>In addition to more pleasant syntax, some hand-written objects contain a large amount of useful logic which can simplify application code. For instance, <ulink url="&url_telepathy_glib_base;contact.html"><classname>TpContact</classname></ulink> uses GObject signals. <!-- TODO: Finish this sentence. --></para>
- </sect3>
+ </sect2>
- <sect3>
+ <sect2>
<title>Instantiation and Readiness</title>
<!-- TODO: Keep any eye on http://bugs.freedesktop.org/show_bug.cgi?id=13422 -->
<para>Some of the hand-coded objects, such as <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> and <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpChannel</classname></ulink>, call additional D-Bus methods to acquire necessary information. When they have received this information they are then "ready", meaning that other hand-written functions can then be called. This concept of "readiness" does not exist in the raw D-Bus API because it describes the status of the hand-written behaviour. For instance, you should call <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-call-when-ready">tp_connection_call_when_ready()</ulink> after instantiating a TpConnection, or <ulink url="&url_telepathy_glib_base;channel.html#tp-channel-call-when-ready">tp_channel_call_when_ready()</ulink> after instantiating a TpChannel.</para>
- </sect3>
+ </sect2>
- <sect3>
+ <sect2>
<title>Headers and Linking</title>
<para>To use the telepathy-glib API, you must include the headers for the library, and link to its shared library. The necessary compiler and linker commands can be obtained from the <literal>pkg-config</literal> utiltity like so:</para>
<para>
@@ -298,74 +367,9 @@ AC_SUBST(EXAMPLE_LIBS)
</programlisting>
</para>
<para>You should then use the generated _CFLAGS and _LIBS definitions in your Makefile.am files.</para>
- </sect3>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="sec-basics-connection-managers">
- <title>Connection Managers</title>
- <para>Support for the various communication protocols is provided by several <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"><interfacename>Connection</interfacename></ulink> and <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></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. -->
- <sect1 id="sec-basics-optional-interfaces">
- <title>Optional Interfaces</title>
- <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 they discover 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.</para>
- <para>For instance, use the <interfacename>Connection</interfacename> interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>GetInterfaces()</methodname></ulink> method. For <interfacename>ConnectionManager</interfacename>s and <interfacename>Channel</interfacename>s use their <property>Interfaces</property> D-Bus property. Eventually <interfacename>Connection</interfacename> will also have an <property>Interfaces</property> property, when its <methodname>GetInterfaces()</methodname> method will be deprecated.</para>
-
- <para>When using telepathy-glib, you can simply call the <ulink url="&url_telepathy_glib_base;proxy.html#tp-proxy-has-interface"><function>tp_proxy_has_interface()</function></ulink> function for <classname>TpConnectionManager</classname>, <classname>TpConnection</classname>, or <classname>TpChannel</classname>.</para>
- <para>Actually, the core interfaces are only "recommended" by the Telepathy D-Bus specification so you should check before using any interface even if it is not commonly considered to be optional.</para>
-
- <note>
- <para>Note that the <property>Interfaces</property> property (or the <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>Connection.GetInterfaces()</methodname></ulink> method) does more than the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><methodname>Introspectable.Introspect()</methodname></ulink> method. The Telepathy-specific mechanism allows tools and language bindings to know about the possible availability of interfaces via <methodname>Introspect()</methodname> 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>
-
- <!-- TODO: Add dbus-glib and Python examples of checking-for and using an Interface. -->
- </sect1>
-
- <!-- TODO: Should we even mention this before the new (5?) version is ready?
- <sect1 id="sec-basics-mission-control">
- <title>Mission Control</title>
- <para>TODO: Notes: desktop-wide accounts and dispatching to applications.
- </para>
- </sect1>
- -->
-
- <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. 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 "hold" the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><methodname>HoldHandles()</methodname></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><methodname>ReleaseHandles()</methodname></ulink> when you have finished with the handle. However, a single <methodname>ReleaseHandles()</methodname> call will release a handle regardless of how many times <methodname>HoldHandles()</methodname> 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 <classname>TpContact</classname> object. Additionally, telepathy-glib wraps the <methodname>HoldHandles()</methodname> and <methodname>ReleaseHandles()</methodname> 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 "hold", allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
-
- <!-- TODO: On irc, smcv said: "perhaps "the user types in the name of a chatroom to join" would be a better example of when you want to use tp_connection_request_handles/tp_connection_unref_handles". Explain that more fully. -->
+ </sect2>
- <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>
-
- </sect1>
-
- <sect1 id="sec-basics-api-conventions">
- <title>API conventions</title>
- <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"><methodname>Connection.RequestChannel()</methodname></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"><methodname>Connection.GetStatus()</methodname></ulink>.</simpara></listitem>
- </orderedlist>
-
- <para>See the <link linkend="sec-basics-dbus">Using D-Bus</link> section 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 <link linkend="sec-basics-language-bindings-telepathy-glib">telepathy-glib</link> section about its function naming conventions.</para>
- </sect1>
+ </sect1>
</chapter>
@@ -425,7 +429,7 @@ AC_SUBST(EXAMPLE_LIBS)
<para>As of this writing, there is no hand-coded telepathy-glib function to request the connection and directly provide a <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> proxy. However, you may use the generated <ulink url="&url_telepathy_glib_base;connection-manager.html#tp_cli_connection_manager_call_request_connection"><function>tp_cli_connection_manager_call_request_connection()</function></ulink> function. In the callback, you can then use the provided <literal>bus name</literal> and <literal>object path</literal> to instantiate a TpConnection proxy object.</para>
- <note><para>See the <link linkend="sec-basics-language-bindings-telepathy-glib-generated">Basics</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
+ <note><para>See the <link linkend="sec-language-bindings-telepathy-glib-generated">Language Bindings</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
<para>See the <link linkend="chapter-channel">Channels</link> section about obtaining and using <interfacename>Channel</interfacename>s from the <interfacename>Connection</interfacename> with which you can list groups of contacts .</para>
@@ -453,7 +457,7 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Optional Interfaces</title>
- <para>As mentioned in the <link linkend="sec-basics-optional-interfaces">Basics</link> section, the <interfacename>Connection</interfacename> may provide several optional interfaces, depending on the <interfacename>ConnectionManager</interfacename> used and depending on the capabilities of the remote server.</para>
+ <para>As mentioned in the <link linkend="sec-dbus-optional-interfaces">D-Bus</link> section, the <interfacename>Connection</interfacename> may provide several optional interfaces, depending on the <interfacename>ConnectionManager</interfacename> used and depending on the capabilities of the remote server.</para>
<para>For instance, these interfaces are present if the remote server or its protocol provides that functionality:</para>
@@ -574,7 +578,7 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Optional Interfaces</title>
- <para>As mentioned in the <link linkend="sec-basics-optional-interfaces">Basics</link> section, the <interfacename>Channel</interfacename> may provide several optional interfaces, depending on the <interfacename>ConnectionManager</interfacename> used and depending on the capabilities of the remote server.</para>
+ <para>As mentioned in the <link linkend="sec-dbus-optional-interfaces">D-Bus</link> section, the <interfacename>Channel</interfacename> may provide several optional interfaces, depending on the <interfacename>ConnectionManager</interfacename> used and depending on the capabilities of the remote server.</para>
<para>For instance, these interfaces are present if the remote server or its protocol provides that functionality:</para>
--
1.5.6.5
More information about the telepathy-commits
mailing list