[Telepathy-commits] [telepathy-doc/master] Split stuff related to retrieving contact information out into its own chapter
Davyd Madeley
davyd at madeley.id.au
Tue Mar 17 22:59:16 PDT 2009
---
docs/book/C/channel.xml | 2 +-
docs/book/C/connection.xml | 144 +-------------------------------
docs/book/C/contactinfo.xml | 190 +++++++++++++++++++++++++++++++++++++++++++
docs/book/C/telepathy.xml | 21 +-----
docs/book/Makefile.am | 1 +
5 files changed, 198 insertions(+), 160 deletions(-)
create mode 100644 docs/book/C/contactinfo.xml
diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index 6604465..78f7946 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -581,7 +581,7 @@
<para>
Information about a list of contacts can be looked up using the
connection's <interfacename>Contacts</interfacename> interface. This
- is documented in <xref linkend="sect.connection.contacts"/>.
+ is documented in <xref linkend="sect.contactinfo.contacts"/>.
</para>
<para>
diff --git a/docs/book/C/connection.xml b/docs/book/C/connection.xml
index f4a2948..e225adb 100644
--- a/docs/book/C/connection.xml
+++ b/docs/book/C/connection.xml
@@ -67,7 +67,7 @@
The <interfacename>Contacts</interfacename> interface is a sort of
proxy to other interfaces on the connection. It is used to gather as
much information about a contact as required in a single D-Bus
- roundtrip. It is documented in <xref linkend="sect.connection.contacts"/>.
+ roundtrip. It is documented in <xref linkend="sect.contactinfo.contacts"/>.
</para>
</listitem>
<listitem>
@@ -75,7 +75,8 @@
<para>
The <interfacename>SimplePresence</interfacename> interface is used to
set and obtain presence information on a given Connection. It is
- documented in <xref linkend="sect.connection.presence"/>.
+ documented in <xref linkend="sect.connection.presence"/> and
+ <xref linkend="sect.contactinfo.presence"/>.
</para>
</listitem>
<listitem>
@@ -380,122 +381,6 @@
</sect2>
</sect1>
- <sect1 id="sect.connection.contacts">
- <title>Contacts</title>
- <para>
- It is often the case that a Telepathy client will want to learn as much
- information about a list of contacts as it can, e.g. their alias, avatar,
- presence, capabilities, location. Requesting data from each of the
- interfaces individually results in n D-Bus method calls on the
- connection. The <interfacename>Contacts</interfacename> interface
- acts as a sort of proxy to the other interfaces of the connection,
- allowing the client to request the most common information in a single
- D-Bus method call (thus saving on D-Bus roundtrips).
- </para>
-
- <para>
- Depending on a connection's capabilities, it may not implement the full
- set of available interfaces (e.g. IRC provides no avatars). Thus the
- interfaces available for use with the
- <interfacename>Contacts</interfacename> interface are available through
- the <property>ContactAttributeInterfaces</property> property.
- </para>
-
- <para>
- The lookup is done using the
- <methodname>GetContactAttributes</methodname> method, which takes an
- array of contact handles (e.g. from a contact list), an array of
- interfaces you re interested in (from the
- <property>ContactAttributeInterfaces</property>) and whether or not
- to hold the handles (as if <methodname>HoldHandles</methodname> was
- called). The return value is a nested mapping of handles to mapped
- key/value pairs. <xref linkend="ex.connection.contacts.return"/> gives
- an example return.
- </para>
-
- <para>
- The keys are of the form
- <literal>interface/attribute</literal> (e.g.
- <literal>org.freedesktop.Telepathy.Connection/contact-id</literal>).
- They do not map to interface properties. For the moment they are
- documented in the spec with the <interfacename>Contacts</interfacename>
- interface.
- </para>
-
- <example id="ex.connection.contacts.return">
- <title>Example Return Value for GetContactAttributes</title>
- <para>
- <methodname>GetContactAttributes</methodname> was called on a list of
- handles with the <interfacename>Connection</interfacename>,
- <interfacename>Aliasing</interfacename> and
- <interfacename>SimplePresence</interfacename> interfaces.
- </para>
-
- <informaltable>
- <tgroup cols="3">
- <tbody>
- <row>
- <entry morerows="2"><handle 1></entry>
- <entry>org.freedesktop.Telepathy.Connection/contact-id</entry>
- <entry>friend1 at jabber.org</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias</entry>
- <entry>Gary</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence</entry>
- <entry>Presence...</entry>
- </row>
-
- <row>
- <entry morerows="2"><handle 2></entry>
- <entry>org.freedesktop.Telepathy.Connection/contact-id</entry>
- <entry>friend2 at jabber.org</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias</entry>
- <entry>Stephanie</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence</entry>
- <entry>Presence...</entry>
- </row>
-
- <row>
- <entry morerows="2"><handle 3></entry>
- <entry>org.freedesktop.Telepathy.Connection/contact-id</entry>
- <entry>friend3 at jabber.org</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias</entry>
- <entry>Danielle</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence</entry>
- <entry>Presence...</entry>
- </row>
-
- </tbody>
- </tgroup>
- </informaltable>
- </example>
-
- <sect2>
- <title>Receiving Updates</title>
- <para>
- While <interfacename>Contacts</interfacename>/
- <methodname>GetContactAttributes</methodname> allows us to
- bulk-request lots of information about a contact. It does not provide a
- mechanism to receive signals to notify the client of changes to a contact
- (e.g., their alias, avatar, location, status, etc.).
- Instead the client should connect to the various signals provided by
- the interfaces its interested in.
- </para>
- </sect2>
-
- </sect1>
-
<sect1 id="sect.connection.presence">
<title>Presence</title>
<para>
@@ -571,28 +456,9 @@
<sect2>
<title>Retrieving Contacts' Presence</title>
- <tip>
- <para>
- Many of the common requests that are made when a Telepathy client
- starts up (e.g. aliases, avatars, presence) can be batched together
- in a call to <methodname>Contacts.GetContactAttributes</methodname>.
- </para>
- <para>
- See <xref linkend="sect.connection.contacts"/> for more information.
- </para>
- </tip>
-
- <para>
- The presence for a list of contact handles can be retrieved with the
- <methodname>GetPresences</methodname> method call. This method call
- takes an array of handles of type <type>Handle_Type_Contact</type>
- and returns a map of those handles to <type>Simple_Presence</type>
- structs.
- </para>
-
<para>
- Presence updates can be tracked by connecting the
- <methodname>PresencesChanged</methodname> signal.
+ This is documented in
+ <xref linkend="sect.contactinfo.presence"/>.
</para>
</sect2>
diff --git a/docs/book/C/contactinfo.xml b/docs/book/C/contactinfo.xml
new file mode 100644
index 0000000..e5928db
--- /dev/null
+++ b/docs/book/C/contactinfo.xml
@@ -0,0 +1,190 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY mdash "—">
+ <!ENTITY appversion "0.7">
+ <!ENTITY manrevision "0.2">
+ <!ENTITY date "12 August 2008">
+ <!ENTITY app_no_markup "Telepathy">
+ <!ENTITY app "<application>&app_no_markup;</application>">
+ <!ENTITY url_examples_base "./examples/">
+ <!ENTITY url_spec "http://telepathy.freedesktop.org/spec.html">
+ <!ENTITY url_spec_base "&url_spec;#org.freedesktop.Telepathy.">
+ <!ENTITY url_telepathy_glib_base "http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-">
+ <!ENTITY url_dbus_spec_base "http://dbus.freedesktop.org/doc/dbus-specification.html#">
+ <!ENTITY url_dbus_glib_base "http://dbus.freedesktop.org/doc/dbus-glib/">
+ <!ENTITY url_dbus_python_base "http://dbus.freedesktop.org/doc/dbus-python/api/">
+]>
+
+<chapter id="chapter.contactinfo">
+ <title>Accessing and Managing Contact Information</title>
+
+ <sect1 id="sect.contactinfo.contacts">
+ <title>Contacts</title>
+ <para>
+ It is often the case that a Telepathy client will want to learn as much
+ information about a list of contacts as it can, e.g. their alias, avatar,
+ presence, capabilities, location. Requesting data from each of the
+ interfaces individually results in n D-Bus method calls on the
+ connection. The <interfacename>Contacts</interfacename> interface
+ acts as a sort of proxy to the other interfaces of the connection,
+ allowing the client to request the most common information in a single
+ D-Bus method call (thus saving on D-Bus roundtrips).
+ </para>
+
+ <para>
+ Depending on a connection's capabilities, it may not implement the full
+ set of available interfaces (e.g. IRC provides no avatars). Thus the
+ interfaces available for use with the
+ <interfacename>Contacts</interfacename> interface are available through
+ the <property>ContactAttributeInterfaces</property> property.
+ </para>
+
+ <para>
+ The lookup is done using the
+ <methodname>GetContactAttributes</methodname> method, which takes an
+ array of contact handles (e.g. from a contact list), an array of
+ interfaces you re interested in (from the
+ <property>ContactAttributeInterfaces</property>) and whether or not
+ to hold the handles (as if <methodname>HoldHandles</methodname> was
+ called). The return value is a nested mapping of handles to mapped
+ key/value pairs. <xref linkend="ex.connection.contacts.return"/> gives
+ an example return.
+ </para>
+
+ <para>
+ The keys are of the form
+ <literal>interface/attribute</literal> (e.g.
+ <literal>org.freedesktop.Telepathy.Connection/contact-id</literal>).
+ They do not map to interface properties. For the moment they are
+ documented in the spec with the <interfacename>Contacts</interfacename>
+ interface.
+ </para>
+
+ <example id="ex.connection.contacts.return">
+ <title>Example Return Value for GetContactAttributes</title>
+ <para>
+ <methodname>GetContactAttributes</methodname> was called on a list of
+ handles with the <interfacename>Connection</interfacename>,
+ <interfacename>Aliasing</interfacename> and
+ <interfacename>SimplePresence</interfacename> interfaces.
+ </para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry morerows="2"><handle 1></entry>
+ <entry>org.freedesktop.Telepathy.Connection/contact-id</entry>
+ <entry>friend1 at jabber.org</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias</entry>
+ <entry>Gary</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence</entry>
+ <entry>Presence...</entry>
+ </row>
+
+ <row>
+ <entry morerows="2"><handle 2></entry>
+ <entry>org.freedesktop.Telepathy.Connection/contact-id</entry>
+ <entry>friend2 at jabber.org</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias</entry>
+ <entry>Stephanie</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence</entry>
+ <entry>Presence...</entry>
+ </row>
+
+ <row>
+ <entry morerows="2"><handle 3></entry>
+ <entry>org.freedesktop.Telepathy.Connection/contact-id</entry>
+ <entry>friend3 at jabber.org</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias</entry>
+ <entry>Danielle</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence</entry>
+ <entry>Presence...</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </example>
+
+ <sect2>
+ <title>Receiving Updates</title>
+ <para>
+ While <interfacename>Contacts</interfacename>/
+ <methodname>GetContactAttributes</methodname> allows us to
+ bulk-request lots of information about a contact. It does not provide a
+ mechanism to receive signals to notify the client of changes to a contact
+ (e.g., their alias, avatar, location, status, etc.).
+ Instead the client should connect to the various signals provided by
+ the interfaces its interested in.
+ </para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="sect.contactinfo.presence">
+ <title>Presence</title>
+ <para>
+ If a protocol has the concept of presence, showing when users are
+ online or available, then its <interfacename>Connection</interfacename>
+ will provide the <interfacename>SimplePresence</interfacename> interface.
+ This interface provides functions to set and get the user's current
+ presence as well as the presence of other accounts (usually the accounts
+ on the user's roster).
+ </para>
+
+ <para>
+ Setting the user's own presence is documented in
+ <xref linkend="sect.connection.presence"/>.
+ </para>
+
+ <warning>
+ <title>Presence vs. SimplePresence</title>
+ <para>
+ The Telepathy API specification also specifies another presence interface
+ <interfacename>Presence</interfacename>. This interface was deemed too
+ complex and has summarily been deprecated. Telepathy clients should
+ not use <interfacename>Presence</interfacename> and instead use
+ <interfacename>SimplePresence</interfacename>.
+ </para>
+ </warning>
+
+ <tip>
+ <para>
+ Many of the common requests that are made when a Telepathy client
+ starts up (e.g. aliases, avatars, presence) can be batched together
+ in a call to <methodname>Contacts.GetContactAttributes</methodname>.
+ </para>
+ <para>
+ See <xref linkend="sect.contactinfo.contacts"/> for more information.
+ </para>
+ </tip>
+
+ <para>
+ The presence for a list of contact handles can be retrieved with the
+ <methodname>GetPresences</methodname> method call. This method call
+ takes an array of handles of type <type>Handle_Type_Contact</type>
+ and returns a map of those handles to <type>Simple_Presence</type>
+ structs.
+ </para>
+
+ <para>
+ Presence updates can be tracked by connecting the
+ <methodname>PresencesChanged</methodname> signal.
+ </para>
+ </sect1>
+
+</chapter>
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 81b9fa4..98ffefc 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -87,6 +87,7 @@
<xi:include href="channel-dispatcher.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="connection.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="channel.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<xi:include href="contactinfo.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="tubes.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<!--
@@ -97,26 +98,6 @@ code snippets which will also be in dbus-glib, but python versions could be
added in future.
-->
-<chapter id="chapter-contacts">
- <title>Accessing/managing contact information</title> <!-- TODO: rename the title. -->
- <para>TODO:
- - Contact Lists
- - publish/subscribe
- - Groups
- - Contact Information
- - Aliases
- - Avatars
- - Presence
- </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-chat-client">
<title>Implementing a Chat Client</title>
<para>TODO:
diff --git a/docs/book/Makefile.am b/docs/book/Makefile.am
index 5809162..37f8b86 100644
--- a/docs/book/Makefile.am
+++ b/docs/book/Makefile.am
@@ -21,6 +21,7 @@ DOC_INCLUDES = \
channel-dispatcher.xml \
connection.xml \
channel.xml \
+ contactinfo.xml \
tubes.xml
# these are figures that need to be rasterised
--
1.5.6.5
More information about the telepathy-commits
mailing list