[Telepathy-commits] [telepathy-doc/master] 2009-02-06 Murray Cumming <murrayc at openismus.com>
Murray Cumming
murrayc at murrayc.com
Fri Feb 6 07:52:52 PST 2009
* docs/book/C/telepathy.xml: Connection Manager: Duplicate (rephrasing)
a little of the basics section for context. Direct people to the
Connection chapter.
Arrange the rest of the Connection Manager chapter into a sub-section
about discovering/querying connection managers, and added a TODO about
the need for a ConnectionManager::GetParameters() explanation and
example.
Basics: Connection Managers: Direct people to the main Connection
Manager chapter to learn more.
---
ChangeLog | 12 ++++++++++++
docs/book/C/telepathy.xml | 31 +++++++++++++++++++------------
2 files changed, 31 insertions(+), 12 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index de69186..8d47244 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2009-02-06 Murray Cumming <murrayc at openismus.com>
+
+ * docs/book/C/telepathy.xml: Connection Manager: Duplicate (rephrasing)
+ a little of the basics section for context. Direct people to the
+ Connection chapter.
+ Arrange the rest of the Connection Manager chapter into a sub-section
+ about discovering/querying connection managers, and added a TODO about
+ the need for a ConnectionManager::GetParameters() explanation and
+ example.
+ Basics: Connection Managers: Direct people to the main Connection
+ Manager chapter to learn more.
+
2009-02-03 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Using D-Bus: Add a <note> about the
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 83af1c5..285a724 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -130,6 +130,8 @@ of the Telapathy specification.
<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>
+ <para>See the <link linkend="chapter-connection-manager">Connection Manager</link> chapter for details.</para>
+
</sect1>
<!-- TODO: Should we even mention this before the new (5?) version is ready?
@@ -162,7 +164,7 @@ of the Telapathy specification.
<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>
+ <listitem><simpara>Methods prefixed with <literal>Request</literal> are asynchronous, 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>
@@ -216,7 +218,7 @@ of the Telapathy specification.
<para>Of course, for simple services with just one object that provides just one interface, these three names will often look very similar.</para>
- <note><para>As well as a <literal>Bus Name</literal>, every D-Bus service is also available via a generated <literal>Unique Name</literal>. This is an identifier assigned to a client by the D-Bus daemon (such as ":1.3"). The <literal>Unique Name</literal> is analagous to an IP address in computer networking, while the <literal>Bus Name</literal> is analogous to a DNS name. You are unlikely to deal with <literal>Bus Name</literal>s when using Telepathy.</para></note>
+ <note><para>As well as a <literal>Bus Name</literal>, every D-Bus service is also available via a generated <indexterm><primary>Unique Name</primary></indexterm><literal>Unique Name</literal>. This is an identifier, such as ":1.3", assigned to a client by the D-Bus daemon. The <literal>Unique Name</literal> is analogous to an IP address in computer networking, while the <literal>Bus Name</literal> is analogous to a DNS name. You are unlikely to deal with <literal>Bus Name</literal>s when using Telepathy.</para></note>
<para>In the following sections you will see how a D-Bus API can be used from some common programming languages. Remember that these examples 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>
@@ -408,16 +410,19 @@ AC_SUBST(EXAMPLE_LIBS)
<chapter id="chapter-connection-manager">
<title>Connection Manager</title>
- <para>As mentioned in the <link linkend="sec-basics-connection-managers">Basics</link> chapter, each <ulink url="&url_spec_base;ConnectionManager"><interfacename>ConnectionManager</interfacename></ulink> provides support for a communication protocol.</para>
+ <para>As mentioned in the <link linkend="sec-basics-connection-managers">Basics</link> chapter, each Connection Manager service provides support for a communication protocol. Each one implements the <ulink url="&url_spec_base;ConnectionManager"><interfacename>ConnectionManager</interfacename></ulink> D-Bus interface, allowing you to request a connection, among other things. See the <link linkend="chapter-connection">Connection</link> chapter for more details about connecting.</para>
- <para>All Telepathy Connection Managers have <literal>bus name</literal>s that begin with "org.freedesktop.Telepathy.ConnectionManager" so you can discover all available connection managers by calling the D-Bus <ulink url="&url_dbus_spec_base;bus-messages-list-activatable-names"><methodname>ListActivatableNames()</methodname></ulink> method and then comparing the names with that prefix. telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers()</function></ulink> function that conveniently does this.</para>
- <para>You may then discover what protocols are provided by each connection manager by calling the ConnectionManagers's <ulink url="&url_spec_base;ConnectionManager.ListProtocols"><methodname>ListProtocols()</methodname></ulink> D-Bus method. telepathy-glib's <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink> object calls this automatically and emits the <literal>got-info</literal> signal when it has returned. You can examine the TpConnectionManager::protocols struct field in your signal handler.</para>
- <para>Applications, such as IM clients, might choose to offer the user a choice from that list of protocols and then use the appropriate connection manager. Others might use only one protocol and therefore hard-code the connection manager's <literal>bus name</literal>.</para>
+ <sect1 id="sec-connection-manager-discovering">
+ <title>Discovering Connection Managers</title>
+ <para>Of course, you must specify the <literal>bus name</literal> of a <interfacename>ConnectionManager</interfacename> to access it. Applications, such as IM clients, might choose to offer the user a choice from that list of protocols and then use the appropriate connection manager. Others might use only one protocol and therefore hard-code the connection manager's <literal>bus name</literal>.</para>
+ <para>All Telepathy Connection Managers have <literal>bus name</literal>s that begin with "org.freedesktop.Telepathy.ConnectionManager" so you can discover all available connection managers by calling the D-Bus <ulink url="&url_dbus_spec_base;bus-messages-list-activatable-names"><methodname>ListActivatableNames()</methodname></ulink> method and then comparing the names with that prefix. telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers()</function></ulink> function that conveniently does this.</para>
+ <para>You may then discover what protocols are provided by each connection manager by calling the ConnectionManagers's <ulink url="&url_spec_base;ConnectionManager.ListProtocols"><methodname>ListProtocols()</methodname></ulink> D-Bus method. telepathy-glib's <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink> object calls this automatically and emits the <literal>got-info</literal> signal when it has returned. You can examine the <structfield>TpConnectionManager::protocols</structfield> struct field in your signal handler.</para>
- <sect1>
- <title>Protocols Listing Example</title>
- <para>This example list all available connection managers and the protocols they support.</para>
- <para><ulink url="&url_examples_base;list_all_protocols">Source Code</ulink></para>
+ <sect2>
+ <title>Protocols Listing Example</title>
+ <para>This example list all available connection managers and the protocols they support.</para>
+ <para><ulink url="&url_examples_base;list_all_protocols">Source Code</ulink></para>
+ </sect2>
</sect1>
</chapter>
@@ -427,13 +432,15 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Connecting</title>
- <para>To attempt a connection to the remote server, for instance to your Jabber IM account, call a <interfacename>ConnectionManager</interfacename>'s <ulink url="&url_spec_base;ConnectionManager.RequestConnection"><methodname>RequestConnection()</methodname></ulink> D-Bus method, providing the connection details. If the connection succeeds then this method returns the <literal>bus name</literal> and <literal>object path</literal> of a Telepathy <ulink url="&url_spec_base;Connection"><interfacename>Connection</interfacename></ulink> object.</para>
+ <para>To attempt a connection to the remote server, for instance to your Jabber IM account, you should call a <interfacename>ConnectionManager</interfacename>'s <ulink url="&url_spec_base;ConnectionManager.RequestConnection"><methodname>RequestConnection()</methodname></ulink> D-Bus method, providing the connection details. If the connection succeeds then this method returns the <literal>bus name</literal> and <literal>object path</literal> of a Telepathy <ulink url="&url_spec_base;Connection"><interfacename>Connection</interfacename></ulink> object.</para>
+
+ <!-- TODO: Mention (and ad an example (below) of) using ConnectionManager::GetParameters() to discover what parameters are needed by RequestConnection() for this ConnectionManager. -->
<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-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>
+ <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>
<!-- TODO: Mention these interfaces, mentioned by smcv on irc: Requests and Contacts are "recommended" (every protocol ought to be able to support them), and are only non-core because they're new (so clients can discover whether they're present)
murrayc: when we eventually remove deprecated stuff, it's likely that Requests and Contacts will become part of Connection -->
--
1.5.6.5
More information about the telepathy-commits
mailing list