[Telepathy-commits] [telepathy-doc/master] * docs/book/C/telepathy.xml: Text Channel: Wrote a little text and added (unfinished) Sending and Receiving subsections.

[Murray Cumming]

---
 ChangeLog                          |    5 +++++
 docs/book/C/telepathy.xml          |   36 +++++++++++++++++++++++++++++-------
 docs/examples/list_contacts/main.c |    2 +-
 docs/examples/send_message/main.c  |    3 +--
 4 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5615afa..24d5fa3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2009-02-06  Murray Cumming  <murrayc at openismus.com>
 
+	* docs/book/C/telepathy.xml: Text Channel: Wrote a little text and 
+	added (unfinished) Sending and Receiving subsections.
+
+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.
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index dae8ad7..d5e9ad6 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -713,18 +713,40 @@ 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 &quot;chat room&quot;. This contact or contacts list must be specified when creating the channel with <methodname>CreateChannel()</methodname> </para>
+  <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 &quot;chat room&quot;. 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>The remote contact or contact list can be referred to by numeric <link linkend="sec-basics-handles"><literal>Handles</literal></link>, (<property>TargetHandle</property>) or indentifier (<property>TargetID</property>) when obtaining the <interfacename>Text</interfacename> channel, 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.</para>
 
-  <para>TODO: Notes: - Text channels may have ChatState (typing notification), Messages (rich 
+  <para>TODO: Notes: 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>
-  <para><ulink url="&url_examples_base;send_message">Source Code</ulink></para>
+  <sect1 id="sec-channel-text-sending">
+    <title>Sending Messages</title>
+    <para>Messages may be sent to the contact (or contact list) with the <ulink url="&url_spec_base;Channel.Type.Text.Send"><methodname>Send()</methodname></ulink> method. Sending messages can be requested using the Send method, which will return successfully. Other parts of your application may handle the <literal>Sent</literal> signal, for instance to log that side of the conversation.</para>
+  
+    <note>
+      <para>Soem Connection Managers also provide the <ulink url="&url_spec_base;Channel.Interface.Messages"><interface>Messages</interface></ulink> interface on the <interfacename>Text</interfacename> channel object. This optional interface allows sending and receiving of formatted messages and delivery reports. For instance, you might use the <interfacename>Message</interfacename> interface's <ulink url="&url_spec_base;Channel.Interface.Messages.SendMessage"><methodname>SendMessage()</methodname></ulink> method instead of the main <interfacename>Text</interfacename> interface's <methodname>Send()</methodname> method.</para>
+    </note>
+
+    <sect2>
+      <title>Example</title>
+      <para>This example sends a text message to a jabber contact via a text channel.</para>
+      <para><ulink url="&url_examples_base;send_message">Source Code</ulink></para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="sec-channel-text-receiving">
+    <title>Receiving Messages</title>
+    <para>TODO</para>
+  
+    <para>TODO: Notes: - Text channels may have ChatState (typing notification).</para> 
+
+    <sect2>
+      <title>Example</title>
+      <para>This example receives text messages from a jabber contact via a text channel.</para>
+      <!-- TODO: <para><ulink url="&url_examples_base;receive_message">Source Code</ulink></para> -->
+    </sect2>
   </sect1>
 
 </chapter>
diff --git a/docs/examples/list_contacts/main.c b/docs/examples/list_contacts/main.c
index 371b378..1689ae1 100644
--- a/docs/examples/list_contacts/main.c
+++ b/docs/examples/list_contacts/main.c
@@ -217,7 +217,7 @@ void on_connection_request_handles (TpConnection *proxy,
 
 
   /* Request the channel: */
-  /* TODO: Use tp_cli_connection_interface_requests_call_create_channel() instead. */
+  /* TODO: Use tp_cli_connection_interface_requests_call_ensure_channel() instead. */
   tp_cli_connection_call_request_channel (connection, 
     -1, /* timeout */
     TP_IFACE_CHANNEL_TYPE_CONTACT_LIST, /* in_Type */
diff --git a/docs/examples/send_message/main.c b/docs/examples/send_message/main.c
index 24f219b..45eee78 100644
--- a/docs/examples/send_message/main.c
+++ b/docs/examples/send_message/main.c
@@ -102,8 +102,7 @@ void on_text_channel_is_ready (TpChannel *channel,
 
   g_printf("DEBUG: Text channel is ready.\n");
 
-  //Send a message:
-
+  /* Send a message: */
   TpProxyPendingCall* pending = tp_cli_channel_type_text_call_send (channel, 
     -1, /* timeout */
     0, /* Channel_Text_Message_Type_Normal */
-- 
1.5.6.5