[Telepathy-commits] [telepathy-doc/master] * docs/book/C/telepathy.xml: Channel: Requesting Channels, ContactList Channel: Mention TargetID as an alternative to TargetHandle and mention when that is useful. ContactList Channel: Say server-defined list instead of standard list, as per the spec. Move that into a sub-section. Put TargetID and TargetHandle in <property> tags.
Murray Cumming
murrayc at murrayc.com
Mon Feb 9 08:44:28 PST 2009
---
ChangeLog | 9 +++++++++
docs/book/C/telepathy.xml | 32 +++++++++++++++++++++-----------
2 files changed, 30 insertions(+), 11 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 0d521d5..5615afa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
2009-02-06 Murray Cumming <murrayc at openismus.com>
+ * docs/book/C/telepathy.xml: Channel: Requesting Channels,
+ ContactList Channel: Mention TargetID as an alternative to TargetHandle
+ and mention when that is useful.
+ ContactList Channel: Say server-defined list instead of standard list,
+ as per the spec. Move that into a sub-section.
+ Put TargetID and TargetHandle in <property> tags.
+
+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
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 9723651..dae8ad7 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -622,8 +622,10 @@ AC_SUBST(EXAMPLE_LIBS)
<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>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 server-defined <interfacename>ContactList</interfacename> Channel, such as the "subscribe" remote list. See the <link linkend="sec-channel-contactlist-server-defined">Server-Defined Lists</link> section.</para>
+ <para>Both methods can take a previously-obtained <property>TargetID</property> <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>Alternatively, many Connection Managers allow you to specify an <indexterm><primary>Identifier</primary></indexterm><literal>Identifier</literal> (via the <property>TargetID</property> property) for the target contact or target list, instead of the <literal>Handle</literal> (via the <property>TargetHandle</property> property), if you do not yet have a <literal>Handle</literal>. For instance, this might be an individual's jabber address, a chat room name or the standard identifier for a server-defined list (see the <link linkend="sec-channel-contactlist-server-defined">Server-Defined Lists</link> section.</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. -->
@@ -677,23 +679,27 @@ 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>The <ulink url="&url_spec_base;Channel.Type.ContactList"><interfacename>ContactList</interfacename></ulink> channel provides a list of people on the server, such as the contacts in a chat room, or the contacts to whose presence information you are subscribed.</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>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 <interfacename>ContactList</interfacename> represents one of these remote contact lists, which it identifies by the remote list's handle. This <property>TargetHandle</property> may 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 <property>TargetHandle</property> 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>Alternatively, many Connection Managers allow you to specify an <indexterm><primary>Identifier</primary></indexterm><literal>Identifier</literal> (via the <property>TargetID</property> property) for the contact list, instead of the <literal>Handle</literal> (via the <property>TargetHandle</property> property), if you do not yet have a <literal>Handle</literal> for the contact list. For <interfacename>ContactList</interfacename> channels this only makes sense for named chat rooms or server-defined lists (see the <link linkend="sec-channel-contactlist-server-defined">Server-Defined Lists</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. -->
+ <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:
- - Channel provides (maybe _is_) a contacts list. Usually 2 people (local me
- and my remote contact), but x people for a chat group.
- </para>
+
+ <sect1 id="sec-channel-contactlist-server-defined">
+ <title>Server-Defined Lists</title>
+ <indexterm><primary>Server-Defined Lists</primary></indexterm>
+
+ <para>Depending on the capabilities of the remote server and its protocol, the Connection Manager may provide some standard "server-defined" remote lists, such as the "subscribe" remote list, which lists all the contacts to whose presence you are subscribed. See the <ulink url="&url_spec_base;Channel.Type.ContactList"><interfacename>ContactList</interfacename></ulink> documentation for more server-defined identifiers, and remember to use <methodname>EnsureChannel()</methodname> rather than <methodname>CreateChannel()</methodname> when obtaining <interfacename>ContactList</interfacename>s for these server-defined lists, as described in the <link linkend="sec-channel-requesting">Requesting Channels</link> section.</para>
+
+ <para>When calling <interfacename>EnsureChannel()</interfacename>, you may specify a standard identifier for a server-defined remote list, such as ", via the <property>TargetID</property> propety. Alternatively, the <property>TargetHandle</property> for server-defined lists can be obtained from the <ulink url="&url_spec_base;Connection.RequestHandles"><methodname>RequestHandle()</methodname></ulink> D-Bus method, to which you may specify the server-defined identifier.</para>
+ </sect1>
<sect1>
<title>Example</title>
@@ -707,6 +713,10 @@ AC_SUBST(EXAMPLE_LIBS)
<title>Text Channel</title>
<indexterm><primary>Text</primary></indexterm>
+ <para>The <ulink url="&url_spec_base;Channel.Type.Text"><interfacename>Text</interfacename></ulink> channel sends and receives plain text messages, such as instant messages. Each <interfacename>Text</interfacename> channel represents communication with a contact or group of contacts. A group of contacts can be considered as a "chat room". This contact or contacts list must be specified when creating the channel with <methodname>CreateChannel()</methodname> </para>
+
+<para>The remote contact or contact list can be referred to by numeric <link linkend="sec-basics-handles"><literal>Handles</literal></link>. This <property>TargetID</property> may 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 <property>TargetHandle</property> D-Bus property of the <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink> interface.</para>
+
<para>TODO: Notes: - Text channels may have ChatState (typing notification), Messages (rich
messages), Password interfaces
</para>
--
1.5.6.5
More information about the telepathy-commits
mailing list