[Telepathy-commits] [telepathy-doc/master] 2009-02-06 Murray Cumming <murrayc at openismus.com>
Murray Cumming
murrayc at murrayc.com
Mon Feb 9 01:08:19 PST 2009
* docs/book/C/telepathy.xml: Channels: Write a short introduction,
mentioning the simple channel types. Moved content into other chapters
for ContactList Channel and Text Channel chapters. This seems better
than having them as sub-sections in Channels, because that would hide
this important functionality from the top-level table of contents.
There is much here yet TODO.
---
ChangeLog | 9 ++++
docs/book/C/telepathy.xml | 111 +++++++++++++++++++++++++++++++++------------
2 files changed, 91 insertions(+), 29 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 1bfb944..4804fac 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
2009-02-06 Murray Cumming <murrayc at openismus.com>
+ * docs/book/C/telepathy.xml: Channels: Write a short introduction,
+ mentioning the simple channel types. Moved content into other chapters
+ for ContactList Channel and Text Channel chapters. This seems better
+ than having them as sub-sections in Channels, because that would hide
+ this important functionality from the top-level table of contents.
+ There is much here yet TODO.
+
+2009-02-06 Murray Cumming <murrayc at openismus.com>
+
* docs/book/C/telepathy.xml: Channels: TODO comment: Some half-formed
thoughts about what structure would clarify the various uses of Channels.
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 00ceead..56e3184 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -89,6 +89,8 @@
<para>TODO: What are the benefits? How is it better than the alternatives? (If there are any). Is it easier, robuster, more secure, more flexible, cheaper, free-er, what?</para>
</chapter>
+ <!-- TODO: Quickly mention somewhere near the start that working with Telepathy generally means getting a connection from a connection manager and then using channels from the connection, saying that we'll explain what that actually means in subsequent chapters. -->
+
<chapter id="chapter-installation">
<title>Installation</title>
<para>If you are using a common Linux distribution you may already have the Telepathy packages installed. For instance, it is a dependency of the <application>Empathy</application> instant messenging client. However, you will probably still need some extra packages to build the examples in this book.</para>
@@ -557,37 +559,55 @@ AC_SUBST(EXAMPLE_LIBS)
<chapter id="chapter-channel">
<title>Channel</title>
- <para>TODO:
- Notes:
- - A connection has <ulink url="&url_spec_base;Channel">Channel</ulink>s.
- - Connection gives me several <ulink url="&url_spec_base;Channel.Type.ContactList">ContactList</ulink> Channels (subscribe, publish, etc)
- - Provides a <ulink url="&url_spec_base;Channel.Interface.Group">Group</ulink> interface.
- - Contains many members (Contact handles).
- - Has a <ulink url="&url_spec_base;Connection.RequestChannel">RequestChannel()</ulink> method that takes a channel type (text/voip/tubes)
- and a handle (contact, room, list or group) handle.
- </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>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>ContactList</primary></indexterm>
+ <ulink url="&url_spec_base;Channel.Type.ContactList"><interfacename>ContactList</interfacename></ulink>
+ </term>
+ <listitem>
+ <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. See the <link linkend="chapter-channel-contactlist">ContactList Channel</link> chapter.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>StreamedMedia</primary></indexterm>
+ <ulink url="&url_spec_base;Channel.Type.StreamedMedia"><interfacename>StreamedMedia</interfacename></ulink>
+ </term>
+ <listitem>
+ <para>This channel sends and receives streamed audio or video, such as a video call.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Text</primary></indexterm>
+ <ulink url="&url_spec_base;Channel.Type.Text"><interfacename>Text</interfacename></ulink>
+ </term>
+ <listitem>
+ <para>This channel sends and receives plain text messages, such as instant messages. See the <link linkend="chapter-channel-text">Text Channel</link> chapter.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <!-- 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> method.</para> <!-- 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? -->
+
+ <!-- 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. -->
- <!-- 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." -->
-
+
<para>TODO:
Notes:
- - <ulink url="&url_spec_base;Connection.RequestChannel">Connection.RequestChannel</ulink>, <ulink url="&url_spec_base;Channel">Channel</ulink>
- - Allows data exchange between the local account and a remote IM account
- (or group of remote accounts).
- - 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.)
- - Maybe an instance of one of these communication types: Text, Contact List,
- Streamed Media.
- - Channel provides (maybe _is_) a contacts list. Usually 2 people (local me
- and my remote contact), but x people for a chat group.
- - The base Channel interface provides channel type, handle and Interfaces
- properties, and Close method, Closed signal.
-
- 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
@@ -604,12 +624,10 @@ AC_SUBST(EXAMPLE_LIBS)
<para>For instance, these interfaces are present if the remote server or its protocol provides that functionality:</para>
<para>TODO:
- - Plus one type-specific interface, such as Text, or Tube, Media.
- This is also sometimes a <ulink url="&url_spec_base;Channel.Interface.Group">Group</ulink> interface, for instance if it's a group chat.
- Media channels may have DTMF, Hold, CallStates (on hold, ringing, etc)
interfaces
- - Text channels may have ChatState (typing notification), Messages (rich
- messages), Password interfaces
+
</para>
<!-- TODO: Are there other potential optional Channel interfaces. I can't tell from the Spec. murrayc. -->
@@ -629,6 +647,40 @@ AC_SUBST(EXAMPLE_LIBS)
</sect1>
+
+</chapter>
+
+<chapter id="chapter-channel-contactlist">
+ <title>ContactList Channel</title>
+
+ <para>TODO: - Provides a <ulink url="&url_spec_base;Channel.Interface.Group">Group</ulink> interface.
+ - Contains many members (Contact handles).
+ </para>
+
+ <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>
+
+ <sect1>
+ <title>Example</title>
+ <para>This example connects to a jabber account and lists all contacts for that account.</para>
+ <para><ulink url="&url_examples_base;list_contacts">Source Code</ulink></para>
+ </sect1>
+
+</chapter>
+
+<chapter id="chapter-channel-text">
+ <title>Text Channel</title>
+
+ <para>TODO: Notes: - Text channels may have ChatState (typing notification), Messages (rich
+ messages), Password interfaces
+ </para>
+
<sect1>
<title>Message Send Example</title>
<para>This example sends a text message to a jabber contact via a text channel.</para>
@@ -640,7 +692,7 @@ AC_SUBST(EXAMPLE_LIBS)
<chapter id="chapter-group">
<title>Group Interface</title>
<para>TODO:
- (used in lots of different channels)
+ (used in lots of different channels) (TODO: which ones? how? examples?)
- This is partitioned into:
- Current members
- Local pending members, awaiting approval (by doing Add or Remove) by the
@@ -691,6 +743,7 @@ added in future.
- Presence
</para>
+ <!-- TODO: This is already used in the ContactList Channel chapter. -->
<sect1>
<title>Example</title>
<para>This example connects to a jabber account and lists all contacts for that account.</para>
--
1.5.6.5
More information about the telepathy-commits
mailing list