[Telepathy-commits] [telepathy-doc/master] * docs/book/C/telepathy.xml: Channel: Make the distinction between ContactList objects and the remote lists that they manage, simplifying the use of TargetID handles for bother ContactList and communication channels. Mention the newer Requests interface (CreateChannel() and EnsureChannel()), moving Connection.RequestChannel() into a <note>. ContactList Channel: Mention standard lists and how to get them.
Murray Cumming
murrayc at murrayc.com
Mon Feb 9 04:21:09 PST 2009
---
ChangeLog | 10 ++++++
docs/book/C/telepathy.xml | 55 +++++++++++++++++++++++-------------
docs/examples/list_contacts/main.c | 1 +
3 files changed, 46 insertions(+), 20 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e5a98da..0d521d5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
2009-02-06 Murray Cumming <murrayc at openismus.com>
+ * docs/book/C/telepathy.xml: Channel: Make the distinction between
+ ContactList objects and the remote lists that they manage, simplifying
+ the use of TargetID handles for bother ContactList and communication
+ channels.
+ Mention the newer Requests interface (CreateChannel() and
+ EnsureChannel()), moving Connection.RequestChannel() into a <note>.
+ ContactList Channel: Mention standard lists and how to get them.
+
+2009-02-06 Murray Cumming <murrayc at openismus.com>
+
* docs/book/C/telepathy.xml: Added several indexterm tags. It would be
nice if chapter headings appeared there automatically.
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 35d66e5..9723651 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -171,7 +171,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 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>
+ <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: Mention CreateChannel instead. -->
<!-- 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>
@@ -570,7 +570,7 @@ AC_SUBST(EXAMPLE_LIBS)
<title>Channel</title>
<indexterm><primary>Channel</primary></indexterm>
- <para>Each <interfacename>Connection</interfacename> provides <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink>s, which allow the local application to exchange data with the remote server, for instance to retrieve a list of contacts in a chat room, or to send a message to a contact. There are various types of <interfacename>Channel</interfacename> for each type of data that might be exchanged, some of which are mentioned in detail in subsequent chapters. These D-Bus interfaces have names prefixed by "org.freedesktop.Telepathy.Channel.Type" For instance:</para>
+ <para>Each <interfacename>Connection</interfacename> provides <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink>s, which allow the local application to exchange data with the remote server, for instance to retrieve a list of contacts in a chat room, or to send a message to a contact. There are various types of <interfacename>Channel</interfacename> for each type of data that might be exchanged, some of which are mentioned in detail in subsequent chapters. These D-Bus interfaces have names prefixed by "org.freedesktop.Telepathy.Channel.Type". For instance:</para>
<variablelist>
@@ -609,18 +609,8 @@ AC_SUBST(EXAMPLE_LIBS)
<!-- TODO: Mention that the base Channel interface provides channel type, handle and Interfaces
properties, and Close method, Closed signal? Only if we can say how it might be used. -->
- <para>These <interfacename>Channel</interfacename>s can be created via the <interfacename>Connection</interfacename>'s <ulink url="&url_spec_base;Connection.RequestChannel"><methodname>RequestChannel()</methodname></ulink> D-Bus method. <!-- TODO: , which takes the D-Bus interface name of the required <interfacename>Channel</interfacename> type, TODO: How are the handle type and handle parameters used for different channel types? --> Telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection.html#tp_cli_connection_call_request_channel"><function>tp_cli_connection_call_request_channel()</function></ulink> function for this purpose.</para>
-
- <!-- TODO: Mention channels that are not directly created by the application: Davyd's text: "in response to communication initiated by someone else, in which case their advent is heralded by the NewChannel signal." -->
-
- <!-- TODO: Mention channels that are lists of contacts, and show the list_contacts example. But this is already in chapter-contacts later.
- Add chapters (or sub-sections for the different channels, so it's easier to see, for instance, that contact lists are channels too, and so we can discuss them differently. -->
-
-
<para>TODO:
Notes:
- - Mention basic channel requesting and then advanced channel requesting.
- (The new API makes it easier to do these things.)
- You'd need two channels for two types of communication with the same
contact. (At least with the new API.)
- Has capabilities. (API will change).
@@ -628,6 +618,28 @@ AC_SUBST(EXAMPLE_LIBS)
For instance, text/media/tube.
</para>
+ <sect1 id="sec-channel-requesting">
+ <title>Requesting Channels</title>
+
+ <para><interfacename>Channel</interfacename>s can be obtained via the <interfacename>Connection</interfacename>'s <ulink url="&url_spec_base;Connection.Interface.Requests"><interfacename>Requests</interfacename></ulink> interface. This provides the <ulink url="&url_spec_base;Connection.Interface.Requests.CreateChannel"><methodname>CreateChannel()</methodname></ulink> D-Bus method for creating new <interfacename>Channel</interfacename>s. Note that this method will fail if a suitable channel already exists.</para>
+ <para>The <ulink url="&url_spec_base;Connection.Interface.Requests.EnsureChannel"><methodname>EnsureChannel()</methodname></ulink> method, however, returns a suitable existing <interfacename>Channel</interfacename> where possible, only creating a new <interfacename>Channel</interfacename> when necessary. You should therefore use <methodname>EnsureChannel()</methodname> when requesting a standard <interfacename>ContactList</interfacename> Channel, such as the "subscribe" remote list.</para>
+ <para>Both methods takes a previously-obtained "TargetID" <link linkend="sec-basics-handles">Handle</link> that identifies the Channel. This handle identifies either the desired <interfacename>ContactList</interfacename>'s corresponding remote contact list or the remote contact (or contact list) with which the channel will communicate, depending on the requested channel type.</para>
+
+ <para>Telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-create-channel"><function>tp_cli_connection_interface_requests_call_create_channel()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-ensure-channel"><function>tp_cli_connection_interface_requests_call_ensure_channel()</function></ulink> functions for this purpose.</para>
+ <!-- TODO: This is complex enough that this is an ideal place for Davyd's snippet-of-a-full-example feature. -->
+
+ <note>
+ <para>The <interfacename>Requests</interfacename> D-Bus interface is relatively new, so it might not be implemented by all Connection Managers. You should therefore check that the interface is really available and fall back to the <interfacename>Connection</interfacename> interface's <ulink url="&url_spec_base;Connection.RequestChannel"><methodname>RequestChannel()</methodname></ulink> method if necessary. Telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection.html#tp_cli_connection_call_request_channel"><function>tp_cli_connection_call_request_channel()</function></ulink> function for this purpose.</para>
+ </note>
+
+ </sect1>
+
+ <!-- TODO: Mention channels that are not directly created by the application: Davyd's text: "in response to communication initiated by someone else, in which case their advent is heralded by the NewChannel signal." -->
+
+ <!-- TODO: Mention channels that are lists of contacts, and show the list_contacts example. But this is already in chapter-contacts later.
+ Add chapters (or sub-sections for the different channels, so it's easier to see, for instance, that contact lists are channels too, and so we can discuss them differently. -->
+
+
<sect1>
<title>Optional Interfaces</title>
<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>
@@ -665,17 +677,20 @@ AC_SUBST(EXAMPLE_LIBS)
<title>ContactList Channel</title>
<indexterm><primary>ContactList</primary></indexterm>
- <para>This channel provides a list of people on the server, such as the contacts to whose presence information you are subscribed or the contacts to whom you publish your presence information. </para>
+ <para>This channel provides a list of people on the server, such as the contacts to whose presence information you are subscribed or the contacts to whom you publish your presence information.</para>
- <para>TODO: - Provides a <ulink url="&url_spec_base;Channel.Interface.Group">Group</ulink> interface.
- - Contains many members (Contact handles).
- </para>
+ <para>Like individual remote contacts themselves, lists of remote contacts can be referred to by numeric <link linkend="sec-basics-handles"><literal>Handles</literal></link>. Each <ulink url="&url_spec_base;Channel.Type.ContactList"><interfacename>ContactList</interfacename></ulink> represents one of these remote contacts, which it identifies by the remote list's handle. This <literal>TargetHandle</literal> must be supplied when obtaining the <interfacename>ContactList</interfacename>, for instance via the <methodname>CreateChannel()</methodname> or <methodname>EnsureChannel()</methodname> D-Bus method, as described in the <link linkend="sec-channel-requesting">Requesting Channels</link> section. The handle may also be discovered by reading the <literal>TargetHandle</literal> D-Bus property of the <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink> interface.</para>
+
+ <para>The <literal>TargetHandle</literal> for some standard lists of remote contacts can be obtained from the <ulink url="&url_spec_base;Connection.RequestHandles"><methodname>RequestHandle()</methodname></ulink> D-Bus method, to which you may specify a standard identifier name, such as "subscribe" for the list of contacts for whom you receive presence information. See the <ulink url="&url_spec_base;Channel.Type.ContactList"><interfacename>ContactList</interfacename></ulink> documentation for more standard identifiers, and remember to use <methodname>EnsureChannel()</methodname> rather than <methodname>CreateChannel()</methodname> when obtaining <interfacename>ContactList</interfacename>s for these standard lists, as described in the <link linkend="sec-channel-requesting">Requesting Channels</link> section.</para>
+
+ <para>The <interfacename>ContactList</interfacename>'s functionality is actually provided by the <ulink url="&url_spec_base;Channel.Interface.Group"><interfacename>Group</interfacename></ulink> interface, which all <interfacename>ContactList</interfacename> objects implement.</para> <!-- Mention the Group chapter if that becomes useful. -->
+ <!-- TODO: One day, I would expect a nice language binding to provide the Group API as a base class (or implemented interface) of the ContactList class, so the separation is less of an issue. murrayc. -->
+
+ <note><para>If a person has multiple instant message accounts, for instance via different protocols, Telepathy has no way of knowing that these are actually the same person, and no way for your application to tell Telepathy this. Therefore, client applications should track this information if necessary.</para></note> <!-- TODO: (We need to call them something other than "IM accounts" because it is not just IM. It can be "people nearby", for instance.) -->
+
<para>TODO: Notes:
- - Only an application knows about actual people (who might have many IM
- accounts).
- - (We need to call them something other than "IM accounts" because it is not
- just IM. It can be "people nearby", for instance.)
+
- Channel provides (maybe _is_) a contacts list. Usually 2 people (local me
and my remote contact), but x people for a chat group.
</para>
diff --git a/docs/examples/list_contacts/main.c b/docs/examples/list_contacts/main.c
index bbcb341..371b378 100644
--- a/docs/examples/list_contacts/main.c
+++ b/docs/examples/list_contacts/main.c
@@ -217,6 +217,7 @@ void on_connection_request_handles (TpConnection *proxy,
/* Request the channel: */
+ /* TODO: Use tp_cli_connection_interface_requests_call_create_channel() instead. */
tp_cli_connection_call_request_channel (connection,
-1, /* timeout */
TP_IFACE_CHANNEL_TYPE_CONTACT_LIST, /* in_Type */
--
1.5.6.5
More information about the telepathy-commits
mailing list