[Telepathy-commits] [telepathy-doc/master] Refactor book into file per chapter
Davyd Madeley
davyd at madeley.id.au
Sun Mar 1 21:30:05 PST 2009
---
.gitignore | 1 +
docs/book/.gitignore | 1 +
docs/book/C/.gitignore | 1 +
docs/book/C/accounts.xml | 286 +++++
docs/book/C/basics.xml | 939 +++++++++++++++
docs/book/C/channel-dispatcher.xml | 28 +
docs/book/C/channel.xml | 476 ++++++++
docs/book/C/connection-manager.xml | 72 ++
docs/book/C/connection.xml | 417 +++++++
docs/book/C/introduction.xml | 161 +++
docs/book/C/telepathy.xml | 2303 +-----------------------------------
docs/book/C/tubes.xml | 39 +
docs/examples/.gitignore | 3 +
13 files changed, 2432 insertions(+), 2295 deletions(-)
create mode 100644 docs/book/C/.gitignore
create mode 100644 docs/book/C/accounts.xml
create mode 100644 docs/book/C/basics.xml
create mode 100644 docs/book/C/channel-dispatcher.xml
create mode 100644 docs/book/C/channel.xml
create mode 100644 docs/book/C/connection-manager.xml
create mode 100644 docs/book/C/connection.xml
create mode 100644 docs/book/C/introduction.xml
create mode 100644 docs/book/C/tubes.xml
create mode 100644 docs/examples/.gitignore
diff --git a/.gitignore b/.gitignore
index 2f1eea2..04770af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,4 @@ config.log
config.status
configure
depcomp
+*.sw?
diff --git a/docs/book/.gitignore b/docs/book/.gitignore
index 282522d..632bedd 100644
--- a/docs/book/.gitignore
+++ b/docs/book/.gitignore
@@ -1,2 +1,3 @@
Makefile
Makefile.in
+/html/
diff --git a/docs/book/C/.gitignore b/docs/book/C/.gitignore
new file mode 100644
index 0000000..5ac0818
--- /dev/null
+++ b/docs/book/C/.gitignore
@@ -0,0 +1 @@
+telepathy-with-examples.xml
diff --git a/docs/book/C/accounts.xml b/docs/book/C/accounts.xml
new file mode 100644
index 0000000..19e8e64
--- /dev/null
+++ b/docs/book/C/accounts.xml
@@ -0,0 +1,286 @@
+<?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-accounts">
+ <title>Accounts and AccountManager</title>
+ <note>
+ <para>
+ The <interfacename>AccountManager</interfacename> and
+ <interfacename>Account</interfacename> interfaces are not implemented
+ in <application>Mission Control 5</application> exactly as they are
+ specified in the Telepathy API specification.
+ </para>
+
+ <para>
+ <application>Mission Control 4</application> implements a completely
+ different interface which is not documented here.
+ </para>
+ </note>
+
+ <para>
+ The Account Manager is implemented as part of Mission Control and is
+ responsible for keeping a list of accounts (e.g. XMPP/Jabber, IRC, MSN).
+ The service is available on the session bus via the well-known bus name
+ <literal>org.freedesktop.Telepathy.AccountManager</literal>, object
+ <literal>/org/freedesktop/Telepathy/AccountManager</literal> and
+ interface <literal>org.freedesktop.Telepathy.AccountManager</literal>.
+ </para>
+
+ <para>
+ To get a list of all accounts known to the Account Manager, you can
+ access the <property>ValidAccounts</property> and
+ <property>InvalidAccounts</property> properties, both of which return an
+ array of D-Bus objects. Valid accounts are accounts that are complete
+ and usable for establishing a connection to a remote service. Invalid
+ accounts are incomplete or otherwise unusable and cannot be used to
+ establish a connection.
+ </para>
+
+ <!-- FIXME: example listing accounts -->
+
+ <sect1 id="sect.accounts.accounts">
+ <title>Accounts</title>
+ <para>
+ Account objects store off of the information that is used for making a
+ <link linkend="chapter-connection">Connection</link> to a remote
+ service. Mission Control can be used to establish connections for valid
+ accounts.
+ </para>
+
+ <para>
+ <interfacename>Account</interfacename> objects have object paths of the form
+ <literal>/org/freedesktop/Telepathy/Account/cm/proto/acct</literal>
+ where <literal>cm</literal> is the Connection Manager name (e.g. gabble,
+ salut) and <literal>proto</literal> is the protocol name (as used in the
+ object path of a <interfacename>Connection</interfacename>). Account
+ objects implement the interface
+ <literal>org.freedesktop.Telepathy.Account</literal>.
+ </para>
+
+ <para>
+ Settings for an account are managed through D-Bus properties. To reduce
+ D-Bus roundtrips: bulk read the properties with the standard
+ <methodname>org.freedesktop.DBus.Properties.GetAll</methodname> method;
+ bulk set properties with the
+ <methodname>org.freedesktop.Telepathy.Account.UpdateParameters</methodname>
+ method. <xref linkend="table.accounts.account-properties"/> shows the
+ properties of an <interfacename>Account</interfacename> object.
+ </para>
+
+ <table id="table.accounts.account-properties">
+ <title>Account Properties</title>
+ <tgroup cols="4">
+ <colspec colname="property"/>
+ <colspec colname="type"/>
+ <colspec colname="description"/>
+ <colspec colname="example"/>
+ <thead>
+
+ <row>
+ <entry namest="property" nameend="example">
+ Read/Write Properties
+ </entry>
+ </row>
+ <row>
+ <entry>Property</entry><entry>Type</entry>
+ <entry>Description</entry><entry>Example</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>DisplayName</entry><entry>String</entry>
+ <entry>
+ The user-visible name of this account. This is how the account is
+ referred to in the user interface, and should be able to be set by
+ the user.
+ </entry>
+ <entry>Jabber (bob at example.com), Work</entry>
+ </row>
+
+ <row>
+ <entry>Icon</entry><entry>String</entry>
+ <entry>
+ The name of an icon in the system's icon theme or the empty string to
+ not specify an icon (in which case one may be automatically chosen).
+ </entry>
+ <entry>im-msn</entry>
+ </row>
+
+ <row>
+ <entry>Enabled</entry><entry>Boolean</entry>
+ <entry>
+ Whether or not an account is enabled (whether or not it can be used
+ to go online). N.B. this is different from whether or not it is
+ Valid.
+ </entry>
+ <entry>True</entry>
+ </row>
+
+ <row>
+ <entry>Nickname</entry><entry>String</entry>
+ <entry>
+ The nickname to set on this account for display to other contacts,
+ as set by the user.
+ </entry>
+ <entry>
+ Bob McBadgers
+ </entry>
+ </row>
+
+ <row>
+ <entry>AutomaticPresence</entry><entry><type>SimplePresence</type></entry>
+ <entry>
+ The presence status that this account should have if it is brought
+ online.
+ </entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>ConnectAutomatically</entry><entry>Boolean</entry>
+ <entry>
+ Whether or not the Account Manager should automatically establish a
+ <link xref="chapter-connection">Connection</link> for this account.
+ </entry>
+ <entry>True</entry>
+ </row>
+
+ <row>
+ <entry>RequestedPresence</entry><entry><type>SimplePresence</type></entry>
+ <entry>
+ The requested presence for this account.
+ </entry>
+ <entry></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+
+ <tgroup cols="4">
+ <colspec colname="property"/>
+ <colspec colname="type"/>
+ <colspec colname="description"/>
+ <colspec colname="example"/>
+ <thead>
+ <row>
+ <entry namest="property" nameend="example">
+ Read-Only Properties
+ </entry>
+ </row>
+ <row>
+ <entry>Property</entry><entry>Type</entry>
+ <entry>Description</entry><entry>Example</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Interfaces</entry><entry><type>DBus_Interface[]</type></entry>
+ <entry>
+ A list of the extra interfaces provided by this account.
+ </entry>
+ <entry>
+ <interfacename>org.freedesktop.Telepathy.Account.Interface.Avatar</interfacename>
+ </entry>
+ </row>
+
+ <row>
+ <entry>Valid</entry><entry>Boolean</entry>
+ <entry>
+ Whether this account is considered by the Account Banager to be
+ complete and usable.
+ </entry>
+ <entry>True</entry>
+ </row>
+
+ <row>
+ <entry>Parameters</entry><entry>Map</entry>
+ <entry>
+ A map from connection manager parameter names (as in the
+ <interfacename>ConnectionManager</interfacename> interface) to their
+ values.
+ </entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>Connection</entry><entry><interfacename>Connection</interfacename></entry>
+ <entry>
+ Either the object path of the Connection to this account, or the
+ special value '/' if there is no connection.
+ </entry>
+ <entry>
+ /org/freedesktop/Telepathy/Connection/gabble/jabber/bob_40example_2ecom_2fwork
+ </entry>
+ </row>
+
+ <row>
+ <entry>ConnectionStatus</entry><entry>integer</entry>
+ <entry>
+ If the Connection property is non-empty, the status of that
+ connection.
+ </entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>ConnectionStatusReason</entry><entry>integer</entry>
+ <entry>
+ The reason for the last change to ConnectionStatus.
+ </entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>CurrentPresence</entry><entry><type>SimplePresence</type></entry>
+ <entry>
+ The actual presence of the account.
+ </entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>NormalizedName</entry><entry>String</entry>
+ <entry>
+ The normalized user ID of the local user on this account.
+ </entry>
+ <entry></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+
+ <!-- para>TODO:
+ Notes:
+ - This is described in the telepathy specification but only partially
+ implemented in Nokia mission control.
+ - AccountManager contains a list of my accounts (my jabber account, my
+ ICQ account, etc)
+ - This is a desktop-wide list of accounts shared by all applications (via
+ the Mission Control service)
+ - most developers probably won't need to deal with them much.
+ - This is not a list of remote accounts held by my contacts.
+ - Includes the parameters which are passed to RequestConnection().
+ - Includes some other parameters such as your avatar/your alias, which the
+ AccountManager takes care of setting for you
+ - Responds to connectivity events/requests.
+ </para -->
+</chapter>
diff --git a/docs/book/C/basics.xml b/docs/book/C/basics.xml
new file mode 100644
index 0000000..776bd22
--- /dev/null
+++ b/docs/book/C/basics.xml
@@ -0,0 +1,939 @@
+<?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-basics">
+ <title>Basics</title>
+
+ <para>This chapter introduces some basic techniques and concepts that you must understand to use Telepathy confidently. You should read through this chapter before proceeding, but you will probably want to refer back here again later.</para>
+
+ <sect1>
+ <title>Terminology</title>
+ <para>
+ This section aims to be a glossary of the different terms you will
+ encounter in Telepathy. Each of these concepts is explained in more
+ detail later in the manual.
+ </para>
+
+ <para>
+ The design of Telepathy is heavily influenced by D-Bus, so much of its
+ terminology is shared in common with D-Bus. For those unfamiliar with
+ D-Bus, a quick primer is presented in <xref linkend="sec-basics-dbus"/>.
+ For more indepth information, consult A MANUAL THAT PROBABLY HASN'T BEEN
+ WRITTEN YET.<!-- FIXME -->
+ </para>
+
+ <!-- FIXME: what order do these go in? -->
+ <!-- FIXME: some of this information is too detailed for this glossary
+ and should be moved further down the manual -->
+ <sect2>
+ <title>Connection Manager</title>
+ <para>
+ Connection managers are simply factories for connections; new
+ connections are created using the
+ <methodname>RequestConnection</methodname> method on the
+ <!-- FIXME - link to spec ? -->
+ <interfacename>org.freedesktop.Telepathy.ConnectionManager</interfacename>
+ interface.
+ </para>
+ <para>
+ The term
+ “connection manager†is often used to mean the process that provides
+ the connection manager service. Each connection has its own D-Bus
+ service name (e.g.
+ <literal>org.freedesktop.Telepathy.ConnectionManager.gabble</literal>),
+ but it's common for the connection manager service to run
+ in the same process as its connections. It's also common for the
+ connection manager object to provide only the main connection manager
+ interface (the common D-Bus introspection and properties interfaces
+ excepted).
+ </para>
+ <para>
+ Connection managers are typically started via D-Bus service activation,
+ when a Telepathy application would like to create a new connection.
+ </para>
+ <para>
+ Connection managers are discussed in more detail in
+ <xref linkend="chapter-connection-manager"/>.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Connection</title>
+ <para>
+ Connections represent active protocol sessions. A connection has a set
+ of parameters that it is requested with. Although the parameters used
+ vary from protocol to protocol, some parameter names have a standard
+ meaning. A notable example is the account parameter, used to specify a
+ persistent identity, usually stored on a server. Some protocols,
+ however, do not have accounts, in which case the account parameter will
+ be absent.
+ </para>
+ <para>
+ The connection interface
+ <!-- FIXME - link to spec ? -->
+ (<interfacename>org.freedesktop.Telepathy.Connection</interfacename>) is
+ mainly concerned with the management of Handles and Channels. It's
+ common for connections to have a number of other interfaces, such as
+ the aliasing, avatars and presence interfaces.
+ </para>
+ <para>
+ Connection objects cease to exist when the
+ <methodname>Disconnect</methodname> method is called.
+ If the connection wasn't already in the Disconnected state, a
+ <!-- FIXME - is there a way to markup signals? -->
+ StatusChanged signal is emitted.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Channel</title>
+ <para>
+ A <interfacename>Channel</interfacename> is used by Telepathy to
+ exchange data between local applications and remote servers. A
+ <interfacename>Channel</interfacename> has a type, depending on what
+ it's used for (e.g. Text, ContactList, StreamedMedia).
+ Channels are either created automatically by a
+ <interfacename>Connection</interfacename>, created by request of the
+ client application or created in response to incoming communication.
+ </para>
+ <para>
+ A complete explanation channels is presented in
+ <xref linkend="chapter-channel"/>.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Handle</title>
+ <para>
+ Handles are used to represent various kinds of protocol resources. Each
+ handle has an associated string identifier. Handles are used to avoid
+ normalisation problems: by having the connection be responsible for
+ mapping equivalent resource identifiers to the same handle, Telepathy
+ clients need only compare handles for integer equality. For instance,
+ protocol X might consider the identifiers foobar at example.com and
+ fooBaR at example.com equivalent, in which case a connection speaking
+ protocol X, when asked to convert both into handles, would return the
+ same handle for both.
+ </para>
+ <para>
+ The handle 0 is never a valid handle, but may be used in the API to
+ indicate a special case.
+ </para>
+ <para>
+ Handles can be generated explicitly, using the RequestHandles method,
+ in which case the client owns a reference to those handles. The
+ reference can be relinquished using ReleaseHandles. In other cases, the
+ connection manager might generate handles implicitly, in which case
+ clients can obtain a reference using HoldHandles. Each client can only
+ obtain one reference to each handle; referencing a handle multiple
+ times is idempotent. A client's references are automatically released
+ when it exits.
+ </para>
+ <para>
+ Handles cease to exist when they have no implicit references (e.g. from
+ a channel that they are related to) and no explicit references from
+ clients.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Interface</title>
+ <para>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec-basics-dbus">
+ <title>Using D-Bus</title>
+ <para>
+ Telepathy is a <indexterm><primary>D-Bus</primary></indexterm>D-Bus API.
+ Telepathy components conform to the
+ <ulink url="&url_spec;">Telepathy D-Bus Specification</ulink>,
+ which is therefore also the main Telepathy API reference.
+ </para>
+
+ <para>
+ D-Bus is an <indexterm><primary>IPC</primary></indexterm>IPC
+ (Inter-process communication) system, allowing different software
+ components running in different processes and implemented in different
+ programming languages to communicate. D-Bus is primarily used as a
+ server/client architecture, but one-to-one communication via a private
+ bus is also possible. D-Bus is the defacto standard IPC mechanism for
+ Linux.
+ </para>
+
+ <para>
+ Most of the Telepathy examples in this book will use a
+ <link linkend="sec-basics-language-bindings">language binding</link>
+ instead of using D-Bus directly. However, an understanding of D-Bus is
+ very helpful when learning Telepathy.
+ </para>
+
+ <figure id="fig.basics.dbus.conceptual">
+ <title>
+ Programs connected to a D-Bus Bus
+ </title>
+ <mediaobject><imageobject>
+ <imagedata fileref="figures/bus-conceptual.png"
+ format="PNG" />
+ </imageobject></mediaobject>
+ </figure>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <indexterm><primary>Message Bus</primary></indexterm>
+ Message Bus
+ </term>
+ <listitem>
+ <para>
+ A message bus is a bus that D-Bus messages are transmitted over,
+ brokered by a D-Bus daemon. There are two main buses that
+ programs communicate with: the <literal>system bus</literal>
+ (for machine wide services, e.g. HAL, NetworkManager, Avahi) and
+ the <literal>session bus</literal> (for user/session specific
+ services, e.g. notification messages, Telepathy, desktop session
+ management).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Unique Name</primary></indexterm>
+ Unique Name
+ </term>
+ <listitem>
+ <para>
+ This is an identifier assigned to a client by the D-Bus daemon
+ (e.g. :1.3). Every client on the D-Bus has one, whether or not
+ it is offering a named service.
+ It is an analagous to an IP address in computer networking.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Well-Known Name</primary></indexterm>
+ Well-Known Name
+ </term>
+ <!-- FIXME - what's the correct markup for bus names, etc? -->
+ <listitem>
+ <para>
+ A process can make a service available by connecting to a
+ D-Bus <literal>bus</literal> and requesting a
+ "well-known" bus name for the
+ connection (this is sometimes referred to as a
+ <literal>service name</literal>),
+ by which other processes, such as applications, can
+ access it.
+ If unique names are analagous to IP addresses, then
+ well-known names are like a DNS name.
+ </para>
+ <para>
+ The example in
+ <xref linkend="fig.basics.dbus.hierarchy-conceptual"/> provides
+ the well-known bus name "org.freedesktop.foo.Foo".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Object Path</primary></indexterm>
+ Object Path
+ </term>
+ <listitem>
+ <para>
+ The service process provides D-Bus objects on that bus name.
+ Each object has an <literal>object path</literal>, such as
+ "/org/freedesktop/foo/jack"
+ (<xref linkend="fig.basics.dbus.hierarchy-conceptual"/>),
+ which a client application must specify to use that object.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Interface Name</primary></indexterm>
+ Interface Name
+ </term>
+ <listitem>
+ <para>Each D-Bus object implements one or more D-Bus interfaces.
+ Each interface has an <literal>interface name</literal>, such as
+ "org.freedesktop.foo.Jack"
+ (<xref linkend="fig.basics.dbus.hierarchy-conceptual"/>).
+ Each interface provides one
+ or more methods or signals, each with a member name.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Method</primary></indexterm>
+ Method
+ </term>
+ <listitem>
+ <para>
+ A D-Bus interface can expose a number of methods that can be
+ called by a client. They have parameters and return types that
+ are given as a D-Bus type signature.
+ </para>
+ <para>
+ <xref linkend="fig.basics.dbus.hierarchy-conceptual"/> gives the
+ example of the "Fetch" method (telling Jack to fetch a
+ pail of water).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Signal</primary></indexterm>
+ Signal
+ </term>
+ <listitem>
+ <para>
+ A D-Bus interface can also expose a number of signals that can be
+ connected to by a client. Connecting a signal involves
+ providing a callback that matches the signal's type signature
+ that can be called by the mainloop (unlike
+ UNIX signals, D-Bus signals are not asynchronous).
+ </para>
+ <para>
+ <xref linkend="fig.basics.dbus.hierarchy-conceptual"/> gives the
+ example of the "Broken" signal (which is triggered
+ when Jack falls down and breaks his crown).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>Property</primary></indexterm>
+ Property
+ </term>
+ <listitem>
+ <para>
+ D-Bus objects implementing the org.freedesktop.DBus.Properties
+ interface may also expose typed properties.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <figure id="fig.basics.dbus.hierarchy-conceptual">
+ <title>
+ Methods and signals on an object
+ </title>
+ <mediaobject><imageobject>
+ <imagedata fileref="figures/bus-hierarchy-conceptual.png"
+ format="PNG" />
+ </imageobject></mediaobject>
+ </figure>
+
+ <tip>
+ <title>Naming in D-Bus</title>
+ <para>
+ A D-Bus bus is shared with lots of other clients and services, some of
+ which will not have been thought of yet. It is important to ensure
+ that your well-known names, objects and interfaces all have unique
+ names.
+ </para>
+ <para>
+ When choosing a well-known bus name, object name or interface name
+ it is best practice to use a reversed domain name (as
+ is done for Java packages) to avoid possible conflicts.
+ </para>
+ <para>
+ For example for well-known bus names or interfaces:
+ </para>
+ <itemizedlist>
+ <listitem><para>org.freedesktop.Telepathy.ConnectionManager</para></listitem>
+ <listitem><para>org.gnome.Project</para></listitem>
+ <listitem><para>com.mycompany.MyProduct</para></listitem>
+ </itemizedlist>
+ <para>
+ For objects:
+ </para>
+ <itemizedlist>
+ <listitem><para>/org/freedesktop/Telepathy/ConnectionManager/gabble</para></listitem>
+ <listitem><para>/org/gnome/Project/adaptor</para></listitem>
+ <listitem><para>/com/mycompany/MyProduct/object0</para></listitem>
+ </itemizedlist>
+ <para>
+ For simple services, with just one object that provides just one
+ interface, these three names will often look very similar.
+ </para>
+ </tip>
+
+ <para>
+ In the following sections you will see how a D-Bus API can be used from
+ some common programming languages. Remember that these examples only
+ create <literal>proxies</literal> to the D-Bus objects, providing a way
+ to use their API. The actual objects are instantiated in the service's
+ process.
+ </para>
+
+ <!--
+ <para>In these examples, we use the FreeDesktop <literal>Notification</literal> system, which should be available on most modern Linux installations. The examples should cause a message to popup from your desktop panel. Note that, like Telepathy, this service is available on the <indexterm><primary>Session Bus</primary></indexterm><literal>Session Bus</literal> rather than the <indexterm><primary>System Bus</primary></indexterm><literal>System Bus</literal>. Services on the <literal>Session Bus</literal> are for the current user's session only. Services on the <literal>System Bus</literal> are shared between all users.</para>
+ -->
+
+ <warning id="warning.dbus.sync">
+ <title>Always Avoid Synchronous D-Bus Calls</title>
+ <!-- this information came from
+ http://smcv.pseudorandom.co.uk/2008/11/nonblocking/ -->
+
+ <para>
+ The <ulink
+ url="http://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
+ specification</ulink> defines D-Bus as an asynchronous
+ message-passing system, and provides no mechanism for blocking calls
+ at the protocol level. However <literal>libdbus</literal> and most
+ D-Bus bindings (dbus-glib, dbus-python and QtDBus) provide a
+ "blocking" API
+ (<function>dbus_do_something_and_block</function>) that implements a
+ "pseudo-blocking" behaviour. In this mode only the D-Bus
+ socket is polled for new I/O and any D-Bus messages that are not the
+ reply to the original message are put on a queue for later
+ processing once the reply has been received.
+ </para>
+
+ <para>
+ This causes several major problems:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Messages can be reordered. Any message received before the reply and
+ placed on the queue will be delivered to the client after the reply,
+ which violates the ordering guarentee the D-Bus daemon provides.
+ </para>
+ <para>
+ This can cause practical problems where a signal indicating an
+ object's destruction is delayed. The client gets a method reply
+ "UnknownMethod" and doesn't know why until the signal is
+ delivered with more information.
+ </para>
+ </listitem>
+ <listitem><para>
+ The client is completely unresponsive until the service replies
+ (include the user interface). If the service you're calling into has
+ locked up (this can happen, even in services that are designed to be
+ purely non-blocking and asynchronous), the client will be
+ unresponsive for 25 seconds until the call times out.
+ </para></listitem>
+ <listitem><para>
+ The client cannot parallelize calls — if a signal causes
+ method calls to be made, a client that uses pseudo-blocking calls
+ can't start processing the next message until those method calls
+ return.
+ </para></listitem>
+ <listitem>
+ <para>
+ If two processes make pseudo-blocking calls on each other, a
+ deadlock occurs.
+ </para>
+ <para>
+ This sort of scenario occurs with plugin architectures and shared
+ D-Bus connections. One plugin "knows" it's a client, not a service;
+ and another plugin, shaing the same connection, "knows" it's a
+ service, not a client. This results in a process that is both a
+ service and a client (and hence deadlock-prone).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </warning>
+
+ <tip>
+ <title>Introspecting a Bus</title>
+ <para>
+ Many services on a D-Bus bus provide a mechanism to introspect their
+ available objects and associated interfaces. A good utility for doing
+ this in an interactive way is
+ <ulink url="https://fedorahosted.org/d-feet/">D-Feet</ulink>.
+ </para>
+ <figure id="fig.dbus.d-feet">
+ <title>
+ D-Feet D-Bus Introspection Tool
+ </title>
+ <mediaobject><imageobject>
+ <imagedata fileref="figures/dfeet-dbus-introspection-tool.png"
+ format="PNG" />
+ </imageobject></mediaobject>
+ </figure>
+ <para>
+ D-Feet shows each service connected to the bus and the objects,
+ interfaces, methods and signals available for that service.
+ It allows (synchronous) method calls to be made.
+ </para>
+ </tip>
+
+ <sect2 id="sect.basics-dbus-glib.types">
+ <title>D-Bus Type Signatures</title>
+
+ <para>
+ D-Bus methods and signals are strongly typed with types given by a
+ D-Bus type signature. The complete documentation for D-Bus type
+ signatures is presented in the
+ <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures">D-Bus specification</ulink>.
+ </para>
+
+ <!-- FIXME: should write more here -->
+ </sect2>
+
+ <sect2 id="sec-basics-dbus-glib">
+ <title>Using D-Bus from C, with glib</title>
+
+ <!-- FIXME: something about dbus-glib
+ link to
+ http://dbus.freedesktop.org/doc/dbus-tutorial.html#glib-client
+ -->
+
+ <para>
+ Before any method calls can be made or signals connected, via
+ D-Bus, we need to make a connection to the message bus we wish to
+ use (e.g. the system bus, the session bus or some private bus).
+ Generally an application only makes one connection to each bus.
+ <xref linkend="dbus-glib-methods-get-bus"/> shows how to create a
+ connection to a user's session bus.
+ </para>
+
+ <example id="dbus-glib-methods-get-bus"
+ file="basics_dbus_glib_methods/main.c">
+ <title>Connecting to a Message Bus</title>
+ </example>
+
+ <para>
+ In order to interact with a D-Bus object (i.e. call methods or
+ connect signals) we need to create a proxy object for it. A proxy
+ object is a <classname>GObject</classname> that we call methods on
+ in our application. <xref linkend="dbus-glib-methods-get-proxy"/>
+ shows connecting up a proxy object for the desktop notification
+ service.
+ </para>
+ <example id="dbus-glib-methods-get-proxy"
+ file="basics_dbus_glib_methods/main.c">
+ <title>Acquiring a Proxy Object</title>
+ </example>
+
+ <sect3 id="sect-basics-dbus-glib-methods">
+ <title>Calling Methods</title>
+ <para>
+ Method calls in D-Bus should <emphasis>always</emphasis> be made
+ asynchronously, for the reasons
+ outlined in <xref linkend="warning.dbus.sync"/>.
+ <literal>dbus-glib</literal> offers a synchronous way
+ to make method calls, but you should never use it,
+ </para>
+ <para>
+ In <literal>dbus-glib</literal>, method calls are made with the function
+ <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-begin-call"><function>dbus_g_proxy_begin_call</function></ulink>,
+ which takes as its arguments the name of a D-Bus method to call,
+ a callback function to handle the reply, optional user data and the
+ parameters (and types) for the D-Bus method.
+ </para>
+ <para>
+ <xref linkend="dbus-glib-methods-call-method"/> shows calling the
+ D-Bus method <methodname>Notify</methodname> on the previously
+ acquired proxy.
+ </para>
+
+ <example id="dbus-glib-methods-call-method"
+ file="basics_dbus_glib_methods/main.c">
+ <title>Calling a Method</title>
+ </example>
+
+ <para>
+ In your reply callback, use the function
+ <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-end-call"><function>dbus_g_proxy_end_call</function></ulink>
+ to collect the return values from the method call. This function can
+ be called outside of the reply callback, but if it is called before
+ the reply has been received, it will block; causing the same problems
+ as synchronous D-Bus calls.
+ </para>
+ <para>
+ <xref linkend="dbus-glib-methods-call-method-subroutine"/> shows a
+ reply callback for the method call above.
+ </para>
+
+ <example id="dbus-glib-methods-call-method-subroutine"
+ file="basics_dbus_glib_methods/main.c">
+ <title>Calling a Method: Reply Callback</title>
+ </example>
+ </sect3>
+
+ <sect3 id="sect-basics-dbus-glib-properties">
+ <title>Using Properties</title>
+ <para>
+ D-Bus properties are available via an additional
+ <ulink url="&url_dbus_spec_base;standard-interfaces-properties"><interfacename>org.freedesktop.DBus.Properties</interfacename></ulink>
+ interface on some objects, which provides the methods
+ <methodname>Get</methodname>, <methodname>Set</methodname> and
+ <methodname>GetAll</methodname> to get or set property values for the
+ object's other interfaces.
+ </para>
+ <para>
+ Currently <literal>dbus-glib</literal> has no specific API for handling
+ properties, so they can only be accessed using the D-Bus method calls.
+ <xref linkend="dbus-glib-properties"/> is therefore very
+ similar to <xref linkend="dbus-glib-methods-call-method"/> presented
+ above.
+ </para>
+
+ <example id="dbus-glib-properties"
+ file="basics_dbus_glib_properties/main.c">
+ <title>Accessing D-Bus Properties Using Methods</title>
+ </example>
+ </sect3>
+
+ <sect3 id="sect-basics-dbus-glib-signals">
+ <title>Handling Signals</title>
+ <para>
+ Handlers for D-Bus signals may be connected with the function
+ <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-connect-signal"><function>dbus_g_proxy_connect_signal</function></ulink>.
+ As when calling D-Bus methods, you must specify the expected
+ types, but for signals you must do this in a previous call to
+ <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-add-signal"><function>dbus_g_proxy_add_signal</function></ulink>.
+ The specified callback function will then be called when the signal is
+ emitted.
+ </para>
+ <para>
+ <xref linkend="dbus-glib-signals"/>
+ connects to the "DeviceAdded" signal of
+ the <interface>org.freedesktop.Hal.Manager</interface> interface so it
+ can print a message to the terminal when, for instance, you plug in a
+ USB stick.
+ </para>
+
+ <example id="dbus-glib-signals"
+ file="basics_dbus_glib_signals/main.c">
+ <title>Connecting and Receiving a Signal</title>
+ </example>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="sec-basics-dbus-python">
+ <title>Using D-Bus from Python</title>
+
+ <para>
+ Using D-Bus from Python is done using the <literal>dbus</literal>
+ module. If you're planning on using the GLib mainloop you'll also
+ need the <literal>dbus.mainloop.glib</literal> module.
+ </para>
+
+ <para>
+ <xref linkend="dbus-python-get-bus"/> shows how to configure D-Bus to
+ use the GLib mainloop for its event dispatching and then makes a
+ connection to the session bus.
+ </para>
+
+ <example id="dbus-python-get-bus"
+ file="basics_dbus_python_methods/example.py">
+ <title>Connecting to a Message Bus</title>
+ </example>
+
+ <para>
+ In order to interact with a D-Bus object (i.e. call methods or
+ connect signals) we need to create a proxy object for it. A proxy
+ object is a Python object that we call methods on
+ in our application.
+ </para>
+
+ <para>
+ <xref linkend="dbus-python-get-proxy"/> shows how to acquire a proxy
+ object <classname>/org/freedesktop/Notifications</classname> binding
+ the <interfacename>org.freedesktop.Notifications</interfacename>
+ interface.
+ </para>
+
+ <example id="dbus-python-get-proxy"
+ file="basics_dbus_python_methods/example.py">
+ <title>Acquiring a Proxy Object</title>
+ </example>
+
+ <sect3 id="sect-basics-dbus-python-methods">
+ <title>Calling Methods</title>
+ <para>
+ <xref linkend="dbus-python-call-method"/>
+ uses <indexterm><primary>Python</primary></indexterm>
+ Python to call the <methodname>Notify</methodname> method on the
+ proxy object acquired in <xref linkend="dbus-python-get-proxy"/>
+ above. Proxy objects in Python bind D-Bus methods into their local
+ namespace (unlike when using dbus-glib, where the method name is
+ passed as a string).
+ </para>
+
+ <para>
+ The <literal>reply_handler</literal> and
+ <literal>error_handler</literal> keywords are important to make your
+ method call asynchronous. Method calls in D-Bus should
+ <emphasis>always</emphasis> be made asynchronously, for the reasons
+ outlined in <xref linkend="warning.dbus.sync"/>. Python features
+ such as inline functions and lambdas are permitted as callback
+ functions.
+ </para>
+
+ <example id="dbus-python-call-method"
+ file="basics_dbus_python_methods/example.py">
+ <title>Calling a Method</title>
+ </example>
+ </sect3>
+
+ <sect3 id="sect-basics-dbus-python-properties">
+ <title>Using Properties</title>
+ <para>
+ D-Bus properties are available via an additional
+ <ulink url="&url_dbus_spec_base;standard-interfaces-properties"><interfacename>org.freedesktop.DBus.Properties</interfacename></ulink>
+ interface on some objects, which provides the methods
+ <methodname>Get</methodname>, <methodname>Set</methodname> and
+ <methodname>GetAll</methodname> to get or set property values for the
+ object's other interfaces.
+ </para>
+ <para>
+ Python D-Bus currently has no specific API for dealing with
+ properties, so they must be accessed through the D-Bus method calls.
+ <xref linkend="dbus-python-properties"/> is therefore very similar to
+ <xref linkend="dbus-python-call-method"/> presented above.
+ </para>
+ <example id="dbus-python-properties"
+ file="basics_dbus_python_properties/example.py">
+ <title>Accessing D-Bus Properties Using Methods</title>
+ </example>
+ </sect3>
+
+ <sect3 id="sect-basics-dbus-python-signals">
+ <title>Handling Signals</title>
+ <para>
+ D-Bus signal handlers may be specified in Python with the proxy object's
+ <ulink url="&url_dbus_python_base;dbus.proxies.Interface-class.html#connect_to_signal"><methodname>connect_to_signal</methodname></ulink>
+ method. The specified callback function will then be called when the
+ signal is emitted. <xref linkend="dbus-python-signals"/> connects to
+ the "DeviceAdded" signal of the
+ <interfacename>org.freedesktop.Hal.Manager</interfacename> interface
+ so it can print a message to the terminal when, for instance, you plug
+ in a USB stick.
+ </para>
+
+ <example id="dbus-python-signals"
+ file="basics_dbus_python_signals/example.py">
+ <title>Connecting and Receiving a Signal</title>
+ </example>
+ </sect3>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec-basics-language-bindings">
+ <title>Language Bindings</title>
+ <para>As mentioned in the <link linkend="sec-basics-dbus">Using D-Bus</link> section, many programming languages have their own generic ways of using D-Bus APIs. In addition, there are some Telepathy-specific APIs to make the use of Telepathy even easier. For instance, <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink> provides an API that is familiar to users of Glib and GTK+, using the GObject system and related conventions.</para>
+ <para>Likewise, the <ulink url="http://telepathy.freedesktop.org/wiki/TelepathyQt">Telepathy-Qt</ulink> project provides a more Qt-like API for Telepathy and <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20Python">Telepathy-Python</ulink> does the same for Python.</para> <!-- TODO: Link to Telepathy-Qt4 when it is ready. -->
+
+ <para>Remember that, like raw use of D-Bus from these programming languages, the Telepathy language bindings only create <literal>proxies</literal> to the D-Bus objects, providing a way to use their API. The actual objects are instantiated in the service's process.</para>
+
+ <sect2 id="sec-basics-language-bindings-telepathy-glib">
+ <title>telepathy-glib</title>
+ <para>The C examples in this book will use telepathy-glib, which provides a GObject-based API for the Telepathy framework.</para>
+
+ <!-- TODO: Mention this?
+ <para>The reference documentation only makes sense in terms of the Telepathy D-Bus Specification.</para>
+ -->
+
+ <sect3 id="sec-basics-language-bindings-telepathy-glib-async">
+ <title>Asynchronous Calls</title>
+ <para>For each Telepathy D-Bus method, telepathy-glib generally provides both a "run" and a "call" function. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_run_connect()</ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-call-connect">tp_cli_connection_call_connect()</ulink>. The "run" function is synchronous, blocking until the D-Bus service has returned the value, whereas the "call" function is asynchronous, immediately returning and later providing the result to a callback function.</para>
+ <para>
+ However, the use of the "run" functions is strongly
+ discouraged (see <xref linkend="warning.dbus.sync"/>), so all
+ examples in this book will use the asynchronous "call"
+ functions. While this might seem to complicate the examples,
+ it is more robust and means the applications will be more responsive.
+ </para>
+ </sect3>
+
+ <sect3 id="sec-basics-language-bindings-telepathy-glib-generated">
+ <title>Generated Functions</title>
+ <para>telepathy-glib provides both hand-coded and generated API. The generated functions have these prefixes:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>tp_cli_</term>
+ <listitem>
+ <para>These functions are useful for client applications. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_run_connect()</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>tp_svc_</term>
+ <listitem>
+ <para>These functions are useful for service implementations, such as connection managers. For instance, <ulink url="&url_telepathy_glib_base;svc-connection.html#tp-svc-connection-implement-connect">tp_svc_connection_implement_connect()</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>The generated functions make simple direct calls to the D-Bus methods, without any additional logic and without using more appropriate types. For instance, they use unsigned integers for parameters because D-Bus does not have a concept of enumerations. However, the Telepathy D-Bus Specification does describe enumerations of possible values for these parameters, so the hand-written functions do use enums. Likewise, raw D-Bus methods can only identify object instances in terms of a <literal>bus name</literal> and <literal>object path</literal> combination, but telepathy-glib can directly provide a GObject instance that is a proxy for a D-Bus object without exposing those intermediate details.</para>
+ <para>Hand-coded functions have a simple <literal>tp_</literal> prefix and should be preferred whenever they exist. The generated functions exist only because hand-written functions have not yet been implemented for all Telepathy D-Bus methods.</para>
+ <para>In addition to more pleasant syntax, some hand-written objects contain a large amount of useful logic which can simplify application code. For instance, <ulink url="&url_telepathy_glib_base;contact.html"><classname>TpContact</classname></ulink> uses GObject signals. <!-- TODO: Finish this sentence. --></para>
+ </sect3>
+
+ <sect3>
+ <title>Instantiation and Readiness</title>
+ <!-- TODO: Keep any eye on http://bugs.freedesktop.org/show_bug.cgi?id=13422 -->
+ <para>Some of the hand-coded objects, such as <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> and <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpChannel</classname></ulink>, call additional D-Bus methods to acquire necessary information. When they have received this information they are then "ready", meaning that other hand-written functions can then be called. This concept of "readiness" does not exist in the raw D-Bus API because it describes the status of the hand-written behaviour. For instance, you should call <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-call-when-ready">tp_connection_call_when_ready()</ulink> after instantiating a TpConnection, or <ulink url="&url_telepathy_glib_base;channel.html#tp-channel-call-when-ready">tp_channel_call_when_ready()</ulink> after instantiating a TpChannel.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Headers and Linking</title>
+ <para>To use the telepathy-glib API, you must include the headers for the library, and link to its shared library. The necessary compiler and linker commands can be obtained from the <literal>pkg-config</literal> utiltity like so:</para>
+ <para>
+<programlisting>
+pkg-config telepathy-glib --cflags
+pkg-config telepathy-glib --libs
+</programlisting>
+ </para>
+ <para>However, if you are using the "autotools" (automake, autoconf, etc) build system, you will find it more convenient to use the <function>PKG_CHECK_MODULES</function> macro in your <literal>configure.ac</literal> file.
+ </para>
+ <para>
+<programlisting>
+PKG_CHECK_MODULES(EXAMPLE, telepathy-glib)
+AC_SUBST(EXAMPLE_CFLAGS)
+AC_SUBST(EXAMPLE_LIBS)
+</programlisting>
+ </para>
+ <para>You should then use the generated _CFLAGS and _LIBS definitions in your Makefile.am files.</para>
+ </sect3>
+
+ </sect2>
+
+ </sect1>
+
+ <!-- TODO: Notes: The interfaces are often called their type, particularly for channels. Explain. -->
+ <sect1 id="sec-basics-optional-interfaces">
+ <title>Optional Interfaces</title>
+ <para>Although a core set of D-Bus interfaces is provided by all connection managers, some extra D-Bus interfaces are optional. For instance, some connection managers only provide extra interfaces when they discover that the remote server provides that optional functionality. Therefore, when using these interfaces, application code should first check that the interface is available, sometimes falling back to alternative interfaces.</para>
+ <para>For instance, use the <interfacename>Connection</interfacename> interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>GetInterfaces()</methodname></ulink> method. For <interfacename>ConnectionManager</interfacename>s and <interfacename>Channel</interfacename>s use their <property>Interfaces</property> D-Bus property. Eventually <interfacename>Connection</interfacename> will also have an <property>Interfaces</property> property, when its <methodname>GetInterfaces()</methodname> method will be deprecated.</para>
+
+ <para>When using telepathy-glib, you can simply call the <ulink url="&url_telepathy_glib_base;proxy.html#tp-proxy-has-interface"><function>tp_proxy_has_interface()</function></ulink> function for <classname>TpConnectionManager</classname>, <classname>TpConnection</classname>, or <classname>TpChannel</classname>.</para>
+ <para>Actually, the core interfaces are only "recommended" by the Telepathy D-Bus specification so you should check before using any interface even if it is not commonly considered to be optional.</para>
+
+ <note>
+ <para>Note that the <property>Interfaces</property> property (or the <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>Connection.GetInterfaces()</methodname></ulink> method) does more than the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><methodname>Introspectable.Introspect()</methodname></ulink> method. The Telepathy-specific mechanism allows tools and language bindings to know about the possible availability of interfaces via <methodname>Introspect()</methodname> while providing an additional check that the interface is really supported for the particular connection manager with the particular remote server to which that connection manager is connected.
+ </para>
+ </note>
+
+ <!-- TODO: Add dbus-glib and Python examples of checking-for and using an Interface. -->
+ </sect1>
+
+ <!-- TODO: Should we even mention this before the new (5?) version is ready?
+ <sect1 id="sec-basics-mission-control">
+ <title>Mission Control</title>
+ <para>TODO: Notes: desktop-wide accounts and dispatching to applications.
+ </para>
+ </sect1>
+ -->
+
+ <sect1 id="sec-basics-handles">
+ <title>Handles</title>
+ <para>The Telepathy D-Bus API does not have D-Bus objects to represent contacts, groups, or rooms. These are instead identified by numeric <literal>handles</literal>. This is for performance reasons, and because it is easier to compare numeric handles than to discover if two D-Bus proxy objects refer to the same object instance.</para>
+ <para>These numeric handles are only unique within a Telepathy Connection. For instance, don't try to use a Connection's contact handle with a different Connection. The handles also only make sense when combined with a <ulink url="&url_spec;#type-Handle_Type">handle type</ulink>, telling the API whether it represents a contact, group, or list. In fact, two handles may be numerically identical but be for different types.</para>
+
+ <sect2>
+ <title>Hold and Release</title>
+ <para>When a Telepathy object has finished with a handle that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to "hold" the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><methodname>HoldHandles()</methodname></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><methodname>ReleaseHandles()</methodname></ulink> when you have finished with the handle. However, a single <methodname>ReleaseHandles()</methodname> call will release a handle regardless of how many times <methodname>HoldHandles()</methodname> has been called, so be careful not to call it while other code may be using the handle.</para>
+
+ <para>This is less necessary when using Telepathy <link linkend="sec-basics-language-bindings">language bindings</link>, such as telepathy-glib, because they may automatically hold and release handles for the lifetime of their objects, such as telepathy-glib's <classname>TpContact</classname> object. Additionally, telepathy-glib wraps the <methodname>HoldHandles()</methodname> and <methodname>ReleaseHandles()</methodname> D-Bus methods with the <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-hold-handles"><function>tp_connection_hold_handles()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-unref-handles"><function>tp_connection_unref_handles()</function></ulink> functions which reference-count the client-side handle "hold", allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
+
+ <!-- TODO: On irc, smcv said: "perhaps "the user types in the name of a chatroom to join" would be a better example of when you want to use tp_connection_request_handles/tp_connection_unref_handles". Explain that more fully. -->
+
+ <para>In the later sections we will mention when it actually makes sense to do this when using specific parts of the Telepathy API.</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="sec-basics-api-conventions">
+ <title>API conventions</title>
+
+ <para>
+ There is a general convention for method names in Telepathy.
+ </para>
+
+ <para>
+ Many method names begin with <emphasis>Get</emphasis> (e.g.
+ <methodname>GetAliases</methodname>, <methodname>GetParameters</methodname>,
+ <methodname>GetInterfaces</methodname>, etc.).
+ <emphasis>Get</emphasis> methods
+ will only ever return immutable or cached data. They never block on a
+ network request to a remote service; so data should be available
+ immediately (see <xref linkend="note.basics-api-conventions.get-triggers"/>
+ below).
+ </para>
+ <para>
+ Method names beginning with <emphasis>Request</emphasis> (e.g.
+ <methodname>RequestAliases</methodname>,
+ <methodname>RequestAvatars</methodname>,
+ <methodname>RequestContactInfo</methodname>, etc.) may make network
+ requests (but not always, this depends on the Connection Manager).
+ Depending on the network service, its latency and the size of the
+ reply, it may be some time before data is available (or the network
+ might fail and eventually an error will be returned).
+ </para>
+ <!-- FIXME: should Ensure/Create methods be mentioned?
+ what about any types of signals? -->
+
+ <warning>
+ <title>Always Use Asynchronous Method Calls</title>
+ <para>
+ Even when using a <emphasis>Get</emphasis> call, for which the
+ information will already be available, you must
+ <emphasis>always</emphasis> make asynchronous requests via D-Bus for the
+ reasons outlined in <xref linkend="warning.dbus.sync"/>.
+ </para>
+ </warning>
+
+ <note id="note.basics-api-conventions.get-triggers">
+ <title>Get Calls Can Trigger Network Traffic</title>
+
+ <para>
+ Telepathy interprets <emphasis>Get</emphasis> calls as a way for a
+ client to show interest in information.
+ </para>
+ <para>
+ In the case where there is no information cached in a Connection
+ Manager, <emphasis>Get</emphasis> calls may choose to trigger a
+ network request. The current (empty) cache will be returned as the
+ reply, but upon completion of the request a signal will be emitted to
+ indicate new data is available.
+ </para>
+ <para>
+ For example, if there is no cached data,
+ <methodname>GetAliases</methodname> will return no information, but a
+ request for alias information will be made to the remote service.
+ Once that information has been retrieved the AliasesChanged signal will be
+ emitted.
+ </para>
+ </note>
+
+ </sect1>
+
+</chapter>
diff --git a/docs/book/C/channel-dispatcher.xml b/docs/book/C/channel-dispatcher.xml
new file mode 100644
index 0000000..e5a8ed5
--- /dev/null
+++ b/docs/book/C/channel-dispatcher.xml
@@ -0,0 +1,28 @@
+<?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-channel-dispatcher">
+ <title>TODO: ChannelDispatcher</title>
+ <para>TODO:
+ Notes:
+ - This is in mission control.
+ - This dispatches some events to applications that care about them, by
+ calling a method on the ChannelHandler interface (that the application
+ implements). This API is currently in flux.
+ </para>
+</chapter>
diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
new file mode 100644
index 0000000..05e397b
--- /dev/null
+++ b/docs/book/C/channel.xml
@@ -0,0 +1,476 @@
+<?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-channel">
+ <title>Channel</title>
+ <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.
+ </para>
+ <para>
+ Channels always provide at least two D-Bus interfaces interfaces:
+ <interfacename>org.freedesktop.telepathy.Channel</interfacename>,
+ and another interface according to the type of channel it is (which can
+ be retrieved using the <property>ChannelType</property> property).
+ For instance, a text channel provides the
+ <interfacename>org.freedesktop.telepathy.ChannelType.Text</interfacename>
+ interface.
+ </para>
+
+ <!-- para>
+ Channels are created using a connection's RequestChannel method, or are
+ created by the connection manager in response to communication
+ initiated by someone else, in which case their advent is heralded by
+ the NewChannel signal.
+ </para -->
+
+ <para>
+ The channel types currently available in Telepathy are:
+ </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.
+ </para>
+ <para>
+ See <xref linkend="sect-channel-contactlist"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>RoomList</primary></indexterm>
+ <ulink url="&url_spec_base;Channel.Type.RoomList"><interfacename>RoomList</interfacename></ulink>
+ </term>
+ <listitem>
+ <para>
+ A channel type for listing named channels (e.g. chatrooms)
+ available on the server.
+ </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.
+ </para>
+ <para>
+ See <xref linkend="sect-channel-text"/>.
+ </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>Tubes</primary></indexterm>
+ <ulink url="&url_spec_base;Channel.Type.Tubes"><interfacename>Tubes</interfacename></ulink>
+ </term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry-->
+
+ <varlistentry>
+ <term>
+ <indexterm><primary>FileTransfer</primary></indexterm>
+ <ulink
+ url="&url_spec_base;Channel.Type.FileTransfer"><interfacename>FileTransfer</interfacename></ulink>
+ </term>
+ <listitem>
+ <para>
+ A channel type for transferring files.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <sect1 id="sec-channel-requesting">
+ <title>Requesting Channels</title>
+
+ <para>
+ Channels are requested from a <classname>Connection</classname> object
+ using the <ulink url="&url_spec_base;Connection.Interface.Requests"><interfacename>Requests</interfacename></ulink>
+ interface.
+ </para>
+
+ <para>
+ This interface provides two methods:
+ <methodname>CreateChannel</methodname> and
+ <methodname>EnsureChannel</methodname>.
+ Both methods take the same parameter, a dictionary containing the
+ desired properties for the channel.
+ </para>
+
+ <para>
+ <methodname>CreateChannel</methodname> will attempt to create a new
+ channel with the requested properties. Depending on the protocol, some
+ types of channels are exclusive, and only one such channel can exist at
+ a time (e.g. a XMPP chatroom). If a second channel is requested, the
+ error <errorname>NotAvailable</errorname> is returned.
+ </para>
+
+ <para>
+ Conversely, <methodname>EnsureChannel</methodname> will attempt to reuse an
+ existing channel with the same properties wherever possible, else it
+ will create a new channel. It's possible that another client is also
+ utilising this channel. <!-- FIXME: write more on this -->
+ </para>
+
+ <tip>
+ <title>When to Create and when to Ensure</title>
+ <para>
+ Choosing when to always create a new channel, or when to use an
+ existing channel can usually be deduced based on the function of the
+ channel. If it would make sense to reuse an existing channel then
+ use <methodname>EnsureChannel</methodname>, otherwise use
+ <methodname>CreateChannel</methodname>.
+ </para>
+ <para>
+ <methodname>EnsureChannel</methodname> is usually used for
+ <interfacename>Text</interfacename>,
+ <interfacename>StreamedMedia</interfacename> and
+ <interfacename>ContactList</interfacename> channels.
+ </para>
+ <para>
+ <methodname>CreateChannel</methodname> is usually used for
+ <interfacename>FileTransfer</interfacename>,
+ <interfacename>Tubes</interfacename>,
+ <interfacename>RoomList</interfacename> and
+ <interfacename>ContactSearch</interfacename> channels.
+ </para>
+ </tip>
+
+ <para>
+ The properties argument for <methodname>RequestChannel</methodname> and
+ <methodname>EnsureChannel</methodname> is a map of property names on
+ the desired channel, and their values.
+ In general every channel requires at least three channel
+ properties: the type of channel we wish to create
+ (<property>ChannelType</property>), the handle/id of the contact/room/list
+ we wish to create a channel for (<property>TargetHandle</property> or
+ <property>TargetID</property>) and the type of that handle
+ (<property>TargetHandleType</property>). Specific channel types may
+ require additional properties in order to be created, this is noted in
+ the specification.
+ </para>
+
+ <para>
+ For example, to create a <interfacename>ContactList</interfacename>
+ channel (this is the type of channel that is used to get a list of
+ subscribed contacts from a service), we might provide a map like so:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>org.freedesktop.Telepathy.Channel.ChannelType</entry>
+ <entry>org.freedesktop.Telepathy.Channel.Type.ContactList</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Channel.TargetHandleType</entry>
+ <entry>Handle_Type_List</entry>
+ </row>
+ <row>
+ <entry>org.freedesktop.Telepathy.Channel.TargetID</entry>
+ <entry>"subscribe"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <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>
+
+ <warning>
+ <title>RequestChannel</title>
+ <para>
+ Some Connection Managers might not yet implement the
+ <interfacename>Requests</interfacename> interface on their
+ <classname>Connection</classname>s. In these cases you can
+ use the <methodname>RequestChannel</methodname> method on the
+ <interfacename>Connection</interfacename> interface, but you do so at
+ your own risk.
+ </para>
+ <para>
+ <methodname>CreateChannel</methodname> and
+ <methodname>EnsureChannel</methodname> fix several flaws that were
+ present in <methodname>RequestChannel</methodname>:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <methodname>RequestChannel</methodname> doesn't provide a way to insist
+ on a new channel or prefer an existing channel;
+ </para></listitem>
+ <listitem><para>
+ If <methodname>RequestChannel</methodname> returns an existing
+ channel, the caller is not told whether the channel can be safely
+ handled or if something else is handling it already;
+ </para></listitem>
+ <listitem><para>
+ <methodname>RequestChannel</methodname> can request a channel type,
+ a handle type and a handle, but nothing more elaborate
+ (e.g. you can't request a <interfacename>RoomList</interfacename>
+ with a particular server); and
+ </para></listitem>
+ <listitem><para>
+ <methodname>RequestChannel</methodname> doesn't return the channel's
+ immutable properties (which is a useful optimization).
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ If you must call <methodname>RequestChannel</methodname>, XXX WRITE ME
+ </para>
+ </warning>
+
+ </sect1>
+
+ <sect1 id="sect-channel-contactlist">
+ <title>ContactList Channel</title>
+ <indexterm><primary>ContactList</primary></indexterm>
+
+ <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 <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>
+ 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. -->
+
+ <!-- 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.) -->
+
+ <sect2 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>
+ </sect2>
+
+ <sect2>
+ <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>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="chapter-group">
+ <title>Group Interface</title>
+ <para>TODO:
+ (used in lots of different channels)
+ - This is partitioned into:
+ - Current members
+ - Local pending members, awaiting approval (by doing Add or Remove) by the
+ local user.
+ - Remote pending members, awaiting approval remotely by the other user)
+ - Unusually, one-to-one calls use the <ulink url="&url_spec_base;Channel.Interface.Group">Group</ulink> interface to indicate call
+ progression (explain in call section?).
+ </para>
+ </sect1>
+
+ <sect1 id="sect-channel-text">
+ <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>
+ (<property>TargetHandle</property>) or identifier
+ (<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: Password interfaces
+ </para>
+
+ <sect2 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>
+ Some 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>
+
+ <sect3>
+ <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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="sec-channel-text-receiving">
+ <title>Receiving Messages</title>
+ <para>TODO</para>
+
+ <para>TODO: Notes: - Text channels may have ChatState (typing notification).</para>
+
+ <sect3>
+ <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> -->
+ </sect3>
+ </sect2>
+
+ </sect1>
+
+</chapter>
diff --git a/docs/book/C/connection-manager.xml b/docs/book/C/connection-manager.xml
new file mode 100644
index 0000000..18f2b3d
--- /dev/null
+++ b/docs/book/C/connection-manager.xml
@@ -0,0 +1,72 @@
+<?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-connection-manager">
+ <title>Connection Manager</title>
+
+ <para>
+ Support for the various communication protocols is provided by several
+ <literal>Connection Managers</literal>. For instance, the
+ <literal>telepathy-gabble</literal> Connection Manager provides support
+ for the <acronym>XMPP</acronym> protocol, also known as
+ <literal>Jabber</literal>.
+ </para>
+
+ <para>
+ There is no central &app; D-Bus service. Instead there are several
+ connection manager services, activated on demand, and each of these
+ connection managers provide the same core set of D-Bus interfaces, such as
+ <interfacename>Connection</interfacename> and
+ <interfacename>Channel</interfacename>, allowing application code to be
+ written generically for all connection managers.
+ </para>
+
+ <para>
+ All Telepathy Connection Managers have <literal>bus name</literal>s that
+ begin with "org.freedesktop.Telepathy.ConnectionManager" so
+ you can discover all available connection managers by calling the D-Bus
+ <methodname>ListActivatableNames</methodname> method and then comparing
+ the names with that prefix. telepathy-glib provides the
+ <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers</function></ulink> function
+ that conveniently does this.
+ </para>
+
+ <para>
+ You may then discover what protocols are provided by each connection
+ manager by calling the ConnectionManagers's
+ <methodname>ListProtocols</methodname> method. telepathy-glib's
+ <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink>
+ object calls this automatically and emits the <literal>got-info</literal>
+ signal when it has returned. You can examine the
+ TpConnectionManager::protocols struct field in your signal handler.
+ </para>
+
+ <para>
+ Applications, such as IM clients, might choose to offer the user a choice
+ from that list of protocols and then use the appropriate connection manager.
+ Others might use only one protocol and therefore hard-code the connection
+ manager's <literal>bus name</literal>.
+ </para>
+
+ <sect1>
+ <title>Protocols Listing Example</title>
+ <para>This example list all available connection managers and the protocols they support.</para>
+ <para><ulink url="&url_examples_base;list_all_protocols">Source Code</ulink></para>
+ </sect1>
+
+</chapter>
diff --git a/docs/book/C/connection.xml b/docs/book/C/connection.xml
new file mode 100644
index 0000000..6cb52b4
--- /dev/null
+++ b/docs/book/C/connection.xml
@@ -0,0 +1,417 @@
+<?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-connection">
+ <title>Connection</title>
+
+ <para>
+ A <interfacename>Connection</interfacename> object in Telepathy
+ represents an active (or activatable) protocol session. Connections are
+ created by the appropriate
+ <link xref="chapter-connection-manager">Connection Manager</link>.
+ </para>
+
+ <para>
+ A connection can be located on the D-Bus session bus via the well-known name
+ <literal>org.freedesktop.Telepathy.Connection.cm.proto.account</literal>,
+ where <literal>cm</literal> is the name of the Connection Manager that
+ created the connection (e.g. gabble, salut) and <literal>proto</literal>
+ is the name of a Telepathy <type>Protocol</type> (e.g. jabber, msn, irc).
+ The connection object can then be retrieved from the path
+ <literal>/org/freedesktop/Telepathy/Connection/cm/proto/account</literal>.
+ </para>
+
+ <para>
+ Depending on what features are supported by the protocol, a given
+ connection will implement more interfaces than just
+ <interfacename>Connection</interfacename>. The interfaces supported by
+ a given connection can be retreived using the
+ <methodname>GetInterfaces</methodname> method once the connection is in
+ the <literal>CONNECTED</literal> state. The supported list of interfaces
+ doesn't change during the life on a connection, so it is expected that a
+ client will retreive this once the connection is
+ <literal>CONNECTED</literal>.
+ </para>
+
+ <para>
+ Interfaces that a connection might support are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><interfacename>Requests</interfacename></para>
+ <para>
+ The <interfacename>Requests</interfacename> interface is used to
+ obtain <link linkend="chapter-channel">channels</link>, which are how
+ data is exchanged in Telepathy. Its use is documented in
+ <xref linkend="sec-channel-requesting"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><interfacename>Contacts</interfacename></para>
+ <para>
+ 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"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><interfacename>SimplePresence</interfacename></para>
+ <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"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Avatars</para>
+ <para>
+ Describe me
+ </para>
+ </listitem>
+ <listitem>
+ <para>Capabilities</para>
+ <para>
+ Describe me
+ </para>
+ </listitem>
+ <!--
+ <listitem>
+ <para>ContactCapabilities</para>
+ <para>
+ Draft
+ </para>
+ </listitem>
+ -->
+ <!--
+ <listitem>
+ <para>ContactInfo</para>
+ <para>
+ Draft
+ </para>
+ </listitem>
+ -->
+ <!--
+ <listitem>
+ <para>Location</para>
+ <para>
+ Draft
+ </para>
+ </listitem>
+ -->
+ <!--
+ <listitem>
+ <para>Presence</para>
+ <para>
+ Deprecated with extreme prejudice.
+ </para>
+ </listitem>
+ -->
+ <listitem>
+ <para>Renaming</para>
+ <para>
+ Describe me
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <sect1>
+ <title>Obtaining a Connection</title>
+
+ <sect2>
+ <title>From the Account Manager</title>
+
+ <note>
+ <para>
+ The <interfacename>AccountManager</interfacename> and
+ <interfacename>Account</interfacename> interfaces are not implemented
+ in <application>Mission Control 5</application> exactly as they are
+ specified in the Telepathy API specification.
+ </para>
+ <para>
+ <application>Mission Control 4</application> implements a completely
+ different interface which is not documented here.
+ </para>
+ </note>
+
+ <para>
+ In general, Telepathy clients will want to share the same set of
+ already-configured accounts rather than managing their own accounts
+ and setting up their own connections. The
+ <link linkend="chapter-accounts">Account Manager</link> manages
+ connections for configured accounts which can be retrieved as a
+ property from each <interfacename>Account</interfacename> object.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>From a Connection Manager</title>
+ <para>
+ There might be times when you are using Telepathy without an
+ Account Manager and need to manually set up your own connections using
+ the Connection Manager. For example, a status reporting client that
+ runs as its own user without a desktop session might only run itself,
+ <application>dbus-daemon</application> and a Connection Manager.
+ </para>
+
+ <para>
+ To setup your own connection to the remote server (e.g. your Jabber
+ IM account) you need to call <methodname>RequestConnection</methodname>
+ on the appropriate <link xref="chapter-connection-manager">Connection
+ Manager</link> (e.g. gabble), providing a map of connection details.
+ Assuming the connection succeeds this method will return the
+ <literal>bus name</literal> and <literal>object path</literal>
+ of a newly created Telepathy <interfacename>Connection</interfacename>
+ object.
+ </para>
+
+ <para>
+ To determine what parameters are required or optional for a given
+ Connection Manager its <methodname>GetParameters</methodname> method
+ should be called with the relevant protocol.
+ <xref linkend="example.connection.get_parameters"/> shows how this is
+ done. Some common, "well-known" parameters names are shown
+ in <xref linkend="table.connection.well_known_parameters"/>.
+ </para>
+
+ <example id="example.connection.get_parameters"
+ file="python_get_parameters/example.py">
+ <title>Getting Connection Parameters</title>
+ </example>
+
+ <table id="table.connection.well_known_parameters">
+ <title>Well-Known Connection Parameters for RequestConnection</title>
+ <tgroup cols="4">
+ <colspec colname="property"/>
+ <colspec colname="type"/>
+ <colspec colname="description"/>
+ <colspec colname="example"/>
+
+ <thead>
+ <row>
+ <entry>Property</entry><entry>Type</entry>
+ <entry>Description</entry><entry>Example</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>account</entry><entry>String</entry>
+ <entry>
+ The identifier for the user's account on the server.
+ </entry>
+ <entry>bob at example.com</entry>
+ </row>
+
+ <row>
+ <entry>server</entry><entry>String</entry>
+ <entry>
+ A fully qualified domain name or numeric IPv4 or IPv6 address.
+ </entry>
+ <entry>xmpp.example.com</entry>
+ </row>
+
+ <row>
+ <entry>port</entry><entry>uint16</entry>
+ <entry>
+ A TCP/UDP network port.
+ </entry>
+ <entry>8080</entry>
+ </row>
+
+ <row>
+ <entry>require-encryption</entry><entry>Boolean</entry>
+ <entry>
+ Require encryption for this connection.
+ </entry>
+ <entry>False</entry>
+ </row>
+
+ <row>
+ <entry>register</entry><entry>Boolean</entry>
+ <entry>
+ This account should be created on the server if it does not
+ already exist.
+ </entry>
+ <entry>False</entry>
+ </row>
+
+ <row>
+ <entry>ident</entry><entry>String</entry>
+ <entry>
+ The local username to report to the server.
+ </entry>
+ <entry>bmcbadgers</entry>
+ </row>
+
+ <row>
+ <entry>fullname</entry><entry>String</entry>
+ <entry>
+ The user's full name.
+ </entry>
+ <entry>Bob McBadgers</entry>
+ </row>
+
+ <row>
+ <entry>stun-server</entry><entry>String</entry>
+ <entry>
+ A fully qualified domain name or numeric IPv4 or IPv6 address of a
+ STUN server to use for NAT traversal.
+ </entry>
+ <entry>stun.example.com</entry>
+ </row>
+
+ <row>
+ <entry>stun-port</entry><entry>uint16</entry>
+ <entry>
+ A UDP network port for the STUN server.
+ </entry>
+ <entry>1337</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The new connection will not actually attempt to establish a network
+ connection until its <methodname>Connect</methodname> method has been
+ called. The connection will be ready to use after the
+ <methodname>StatusChanged</methodname> signal returns a
+ <type>Connection_Status</type> of <literal>Connected</literal>.
+ </para>
+
+ <para>
+ <xref linkend="example.connection.establish-connection"/> shows how to
+ manually establish a connection.
+ </para>
+
+ <!--
+ <para>As of this writing, there is no hand-coded telepathy-glib function to request the connection and directly provide a <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> proxy. However, you may use the generated <ulink url="&url_telepathy_glib_base;connection-manager.html#tp_cli_connection_manager_call_request_connection"><function>tp_cli_connection_manager_call_request_connection()</function></ulink> function. In the callback, you can then use the provided <literal>bus name</literal> and <literal>object path</literal> to instantiate a TpConnection proxy object.</para>
+
+ <note><para>See the <link linkend="sec-basics-language-bindings-telepathy-glib-generated">Basics</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
+
+ <para>See the <link linkend="chapter-channel">Channels</link> section about obtaining and using <interfacename>Channel</interfacename>s from the <interfacename>Connection</interfacename> with which you can list groups of contacts .</para>
+ -->
+
+ <example id="example.connection.establish-connection">
+ <title>Establishing a Connection</title>
+ <!--
+ <para><ulink url="&url_examples_base;connect">Source Code</ulink></para>
+ -->
+ </example>
+
+ </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>ContractAttributeInterfaces</property> property.
+ </para>
+ </sect1>
+
+ <sect1 id="sect.connection.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 accounts
+ the on the user's roster).
+ </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>
+
+ <sect2>
+ <title>Setting the User's Presence</title>
+
+ <sect3>
+ <title>Via the Account Manager</title>
+ <note>
+ <para>
+ The <interfacename>AccountManager</interfacename> and
+ <interfacename>Account</interfacename> interfaces are not implemented
+ in <application>Mission Control 5</application> exactly as they are
+ specified in the Telepathy API specification.
+ </para>
+
+ <para>
+ <application>Mission Control 4</application> implements a completely
+ different interface which is not documented here.
+ </para>
+ </note>
+
+ <para>
+ If this Connection was obtained from the
+ <link linkend="chapter-accounts">Account Manager</link>, then the
+ user's presence can be set on the appropriate
+ <link linkend="sect.accounts.accounts">Account</link> object using
+ the <property>RequestPresence</property> property of the
+ <interfacename>Account</interfacename> interface. This property takes
+ a <type>SimplePresence</type> as its value.
+ </para>
+ </sect3>
+
+ <sect3>
+ <title>Via the Connection</title>
+ <para>
+ The user sets their own presence via the
+ <methodname>SetPresence</methodname> method. Parameters are a status
+ identifier (e.g. available, away, hidden) and an optional status message
+ (e.g. "At the Movies"). Valid status identifiers for this
+ connection can be retrieved using the <property>Statuses</property>.
+ </para>
+ </sect3>
+ </sect2>
+
+ <!--
+ <sect2>
+ <title>Presence Example</title>
+ <para>This example sets the presence for a jabber account, by calling the <methodname>SetPresence()</methodname> method of the <interfacename>Connection</interfacename>'s <interfacename>SimplePresence</interfacename> interface, using telepathy-glib.</para>
+ <para><ulink url="&url_examples_base;set_presence">Source Code</ulink></para>
+ </sect2>
+ -->
+
+ </sect1>
+
+</chapter>
diff --git a/docs/book/C/introduction.xml b/docs/book/C/introduction.xml
new file mode 100644
index 0000000..374191a
--- /dev/null
+++ b/docs/book/C/introduction.xml
@@ -0,0 +1,161 @@
+<?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" [
+
+ <!-- These entities are used in the generated .omf files,
+ along with the author tags,
+ allowing the Yelp help browser to know about the document.
+
+ The legal.xml file contains legal information, there is no need to edit the file.
+ Use the appversion entity to specify the version of the application.
+ Use the manrevision entity to specify the revision number of this manual.
+ Use the date entity to specify the release date of this manual.
+ Use the app entity to specify the name of the application. -->
+ <!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-introduction">
+ <title>Introduction</title>
+ <para>
+ Telepathy is a flexible, modular communications framework that enables
+ real-time communication via pluggable protocol backends. Telepathy
+ creates the idea of communication as a desktop service. It
+ uses
+ <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>
+ to separate components running in separate processes. Telepathy clients
+ use this D-Bus API (usually via a convenience library — e.g.
+ telepathy-glib) to share connections between multiple clients (e.g. an
+ instant messaging program, presence in email application, collaboration
+ in word processor).
+ </para>
+
+ <note>
+ <title>Do One Thing and Do It Well</title>
+ <blockquote>
+ <attribution>Doug McIlroy</attribution>
+ <para>
+ This is the Unix philosophy: Write programs that do one thing and do it
+ well. Write programs to work together.
+ </para>
+ </blockquote>
+ <para>
+ Telepathy components are modular, this means that developers can focus
+ on making each component being the best it can be.
+ </para>
+ <para>
+ Application developers can focus on user interaction whilst protocol
+ developers can focus on an individual protocol.
+ </para>
+ </note>
+
+ <figure id="fig.introduction.telepathy-architecture-overview">
+ <title>
+ Conceptual example of Telepathy clients (blue) and
+ Connection Managers (green)
+ </title>
+ <mediaobject><imageobject>
+ <imagedata fileref="figures/telepathy-architecture-overview.png"
+ format="PNG" />
+ </imageobject></mediaobject>
+ </figure>
+
+ <para>
+ Backends for
+ many popular instant messaging protocols already exist including
+ XMPP/Jabber (telepathy-gabble), SIP (telepathy-sofiasip), MSN
+ (telepathy-butterfly) and IRC (telepathy-idle). The development of a
+ new protocol backend can be utilised immediately by all Telepathy consumers.
+ </para>
+
+ <para>
+ Telepathy backends can expose the different features of a communications
+ protocol, including presence (status), text chat (instant messaging),
+ voice and video conferencing, file transfer and
+ Tubes (contact-to-contact network sockets brokered by Telepathy); and do
+ this in a unified way via D-Bus interfaces.
+ </para>
+
+ <note>
+ <title>Is Telepathy a Specification or an Implementation?</title>
+ <para>
+ It's both.
+ </para>
+ <para>
+ There is one
+ <ulink url="http://telepathy.freedesktop.org/spec.html">specification</ulink>
+ which defines the D-Bus API for how one Telepathy component talks to
+ another. Additionally there are many implementations of this
+ specification in the form of libraries that wrap the D-Bus API in a
+ model that might be more familiar to you; and components (e.g. the
+ Connection Managers) that allow you to do useful things with Telepathy.
+ </para>
+ </note>
+
+ <sect1>
+ <title>Rationale</title>
+ <!-- much of this was crimed from
+ http://telepathy.freedesktop.org/wiki/Rationale -->
+ <para>
+ The design of Telepathy, and its approach to real-time communications
+ comes from a very specific rationale:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Robustness:</emphasis>
+ one component can crash without crashing others.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Ease of development:</emphasis>
+ components can be replaced within a running system; tools like
+ dbus-inspector can trace interactions between components.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Language independence:</emphasis>
+ components can be written in any language that has a D-Bus binding;
+ if the best free and open implementation of a given communications
+ protocol is in a certain language, you are able to write your
+ Connection Manager in that language and still have it available to
+ all Telepathy clients.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Desktop independence:</emphasis>
+ D-Bus has been adopted by both GNOME and KDE. Multiple user
+ interfaces can be developed on top of the same Telepathy components.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>License independence:</emphasis>
+ Components can be under different licenses that would be incompatible
+ if all components were running in one process.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Code reuse:</emphasis>
+ Telepathy allows clients to ignore protocol details as much as
+ possible, easing transitions between different communications
+ systems.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Connection reuse:</emphasis>
+ Multiple Telepathy clients can use the same connection simultaneously.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Security:</emphasis>
+ Components can run with very limited privileges; a typical connection
+ manager only needs access to the network and to the D-Bus session bus
+ (e.g. making it possible to use an SELinux policy to prevent protocol
+ code from accessing the disk).
+ </para></listitem>
+ </itemizedlist>
+ </sect1>
+</chapter>
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index e8b4bee..34a9d86 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -81,2301 +81,14 @@
</bookinfo>
-<chapter id="chapter-introduction">
- <title>Introduction</title>
- <!--
- <para>The Telepathy framework allows applications to use real-time communications via several common protocols, such as XMPP (Jabber). For instance, an instant messenger application might use Telepathy to allow chats with online contacts via accounts with various IM services. Or a game might use Telepathy to simplify the implementation of its networking code, allowing users to play against each other.</para>
- <para>Telepathy is a <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink> API so it may be used from most programming languages.</para>
- <para>All this functionality is available under an open source license, allowing people to make improvements and add new features.</para>
-
- <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>
- -->
- <para>
- Telepathy is a flexible, modular communications framework that enables
- real-time communication via pluggable protocol backends. Telepathy
- creates the idea of communication as a desktop service. It
- uses
- <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>
- to separate components running in separate processes. Telepathy clients
- use this D-Bus API (usually via a convenience library — e.g.
- telepathy-glib) to share connections between multiple clients (e.g. an
- instant messaging program, presence in email application, collaboration
- in word processor).
- </para>
-
- <note>
- <title>Do One Thing and Do It Well</title>
- <blockquote>
- <attribution>Doug McIlroy</attribution>
- <para>
- This is the Unix philosophy: Write programs that do one thing and do it
- well. Write programs to work together.
- </para>
- </blockquote>
- <para>
- Telepathy components are modular, this means that developers can focus
- on making each component being the best it can be.
- </para>
- <para>
- Application developers can focus on user interaction whilst protocol
- developers can focus on an individual protocol.
- </para>
- </note>
-
- <figure id="fig.introduction.telepathy-architecture-overview">
- <title>
- Conceptual example of Telepathy clients (blue) and
- Connection Managers (green)
- </title>
- <mediaobject><imageobject>
- <imagedata fileref="figures/telepathy-architecture-overview.png"
- format="PNG" />
- </imageobject></mediaobject>
- </figure>
-
- <para>
- Backends for
- many popular instant messaging protocols already exist including
- XMPP/Jabber (telepathy-gabble), SIP (telepathy-sofiasip), MSN
- (telepathy-butterfly) and IRC (telepathy-idle). The development of a
- new protocol backend can be utilised immediately by all Telepathy consumers.
- </para>
-
- <para>
- Telepathy backends can expose the different features of a communications
- protocol, including presence (status), text chat (instant messaging),
- voice and video conferencing, file transfer and
- Tubes (contact-to-contact network sockets brokered by Telepathy); and do
- this in a unified way via D-Bus interfaces.
- </para>
-
- <note>
- <title>Is Telepathy a Specification or an Implementation?</title>
- <para>
- It's both.
- </para>
- <para>
- There is one
- <ulink url="http://telepathy.freedesktop.org/spec.html">specification</ulink>
- which defines the D-Bus API for how one Telepathy component talks to
- another. Additionally there are many implementations of this
- specification in the form of libraries that wrap the D-Bus API in a
- model that might be more familiar to you; and components (e.g. the
- Connection Managers) that allow you to do useful things with Telepathy.
- </para>
- </note>
-
- <sect1>
- <title>Rationale</title>
- <!-- much of this was crimed from
- http://telepathy.freedesktop.org/wiki/Rationale -->
- <para>
- The design of Telepathy, and its approach to real-time communications
- comes from a very specific rationale:
- </para>
- <itemizedlist>
- <listitem><para>
- <emphasis>Robustness:</emphasis>
- one component can crash without crashing others.
- </para></listitem>
- <listitem><para>
- <emphasis>Ease of development:</emphasis>
- components can be replaced within a running system; tools like
- dbus-inspector can trace interactions between components.
- </para></listitem>
- <listitem><para>
- <emphasis>Language independence:</emphasis>
- components can be written in any language that has a D-Bus binding;
- if the best free and open implementation of a given communications
- protocol is in a certain language, you are able to write your
- Connection Manager in that language and still have it available to
- all Telepathy clients.
- </para></listitem>
- <listitem><para>
- <emphasis>Desktop independence:</emphasis>
- D-Bus has been adopted by both GNOME and KDE. Multiple user
- interfaces can be developed on top of the same Telepathy components.
- </para></listitem>
- <listitem><para>
- <emphasis>License independence:</emphasis>
- Components can be under different licenses that would be incompatible
- if all components were running in one process.
- </para></listitem>
- <listitem><para>
- <emphasis>Code reuse:</emphasis>
- Telepathy allows clients to ignore protocol details as much as
- possible, easing transitions between different communications
- systems.
- </para></listitem>
- <listitem><para>
- <emphasis>Connection reuse:</emphasis>
- Multiple Telepathy clients can use the same connection simultaneously.
- </para></listitem>
- <listitem><para>
- <emphasis>Security:</emphasis>
- Components can run with very limited privileges; a typical connection
- manager only needs access to the network and to the D-Bus session bus
- (e.g. making it possible to use an SELinux policy to prevent protocol
- code from accessing the disk).
- </para></listitem>
- </itemizedlist>
- </sect1>
-</chapter>
-
-<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>
-
- <sect1>
- <title>Installation on Ubuntu Linux</title>
- <para>You can install the Telepathy packages from the command line <application>Terminal</application> with this command: <command>sudo apt-get install telepathy-devel libtelepathy-glib-dev</command></para>
- </sect1>
-
- <sect1>
- <title>Installation on Fedora Linux</title>
- <!-- TODO: Is there no general telepathy-devel package? -->
- <para>You can install the Telepathy packages from the command line <application>Terminal</application> with this command, as root: <command>yum install telepathy-glib-devel telepathy-gabble telepathty-butterfly telepathy-haze telepathy-salut telepathy-stream-engine</command></para>
- </sect1>
-
- <sect1>
- <title>Building from Source</title>
-
- <sect2>
- <title>Getting the Source</title>
-
- <sect3>
- <title>Released Versions</title>
- <para>
- Releases of Telepathy components are made available as tarballs
- on the
- <ulink url="http://telepathy.freedesktop.org/releases/">Telepathy
- website</ulink>.
- </para>
- </sect3>
-
- <sect3>
- <title>From Git</title>
- <para>
- Telepathy uses Git for revision control.
- XXX WRITE MORE ABOUT THIS
- </para>
- </sect3>
-
- </sect2>
- </sect1>
-
-</chapter>
-
-<!--
-Notes:
-- The following sections describe important D-Bus API in telepathy.
-These sections will describe how these interfaces can be used, including small
-code snippets.
-- Where possible the documentation will pull in small but complete
-code examples which can build as part of the documentation, guaranteeing that
-they at least compile with the latest API, and making it easier to test that
-they really work.
-- Wherever interfaces are mentioned, there will be a links to online API
-reference documentation (assuming that it exists) and links to relevant parts
-of the Telepathy specification.
--->
-
-<chapter id="chapter-basics">
- <title>Basics</title>
-
- <para>This chapter introduces some basic techniques and concepts that you must understand to use Telepathy confidently. You should read through this chapter before proceeding, but you will probably want to refer back here again later.</para>
-
- <sect1>
- <title>Terminology</title>
- <para>
- This section aims to be a glossary of the different terms you will
- encounter in Telepathy. Each of these concepts is explained in more
- detail later in the manual.
- </para>
-
- <para>
- The design of Telepathy is heavily influenced by D-Bus, so much of its
- terminology is shared in common with D-Bus. For those unfamiliar with
- D-Bus, a quick primer is presented in <xref linkend="sec-basics-dbus"/>.
- For more indepth information, consult A MANUAL THAT PROBABLY HASN'T BEEN
- WRITTEN YET.<!-- FIXME -->
- </para>
-
- <!-- FIXME: what order do these go in? -->
- <!-- FIXME: some of this information is too detailed for this glossary
- and should be moved further down the manual -->
- <sect2>
- <title>Connection Manager</title>
- <para>
- Connection managers are simply factories for connections; new
- connections are created using the
- <methodname>RequestConnection</methodname> method on the
- <!-- FIXME - link to spec ? -->
- <interfacename>org.freedesktop.Telepathy.ConnectionManager</interfacename>
- interface.
- </para>
- <para>
- The term
- “connection manager†is often used to mean the process that provides
- the connection manager service. Each connection has its own D-Bus
- service name (e.g.
- <literal>org.freedesktop.Telepathy.ConnectionManager.gabble</literal>),
- but it's common for the connection manager service to run
- in the same process as its connections. It's also common for the
- connection manager object to provide only the main connection manager
- interface (the common D-Bus introspection and properties interfaces
- excepted).
- </para>
- <para>
- Connection managers are typically started via D-Bus service activation,
- when a Telepathy application would like to create a new connection.
- </para>
- <para>
- Connection managers are discussed in more detail in
- <xref linkend="chapter-connection-manager"/>.
- </para>
- </sect2>
-
- <sect2>
- <title>Connection</title>
- <para>
- Connections represent active protocol sessions. A connection has a set
- of parameters that it is requested with. Although the parameters used
- vary from protocol to protocol, some parameter names have a standard
- meaning. A notable example is the account parameter, used to specify a
- persistent identity, usually stored on a server. Some protocols,
- however, do not have accounts, in which case the account parameter will
- be absent.
- </para>
- <para>
- The connection interface
- <!-- FIXME - link to spec ? -->
- (<interfacename>org.freedesktop.Telepathy.Connection</interfacename>) is
- mainly concerned with the management of Handles and Channels. It's
- common for connections to have a number of other interfaces, such as
- the aliasing, avatars and presence interfaces.
- </para>
- <para>
- Connection objects cease to exist when the
- <methodname>Disconnect</methodname> method is called.
- If the connection wasn't already in the Disconnected state, a
- <!-- FIXME - is there a way to markup signals? -->
- StatusChanged signal is emitted.
- </para>
- </sect2>
-
- <sect2>
- <title>Channel</title>
- <para>
- A <interfacename>Channel</interfacename> is used by Telepathy to
- exchange data between local applications and remote servers. A
- <interfacename>Channel</interfacename> has a type, depending on what
- it's used for (e.g. Text, ContactList, StreamedMedia).
- Channels are either created automatically by a
- <interfacename>Connection</interfacename>, created by request of the
- client application or created in response to incoming communication.
- </para>
- <para>
- A complete explanation channels is presented in
- <xref linkend="chapter-channel"/>.
- </para>
- </sect2>
-
- <sect2>
- <title>Handle</title>
- <para>
- Handles are used to represent various kinds of protocol resources. Each
- handle has an associated string identifier. Handles are used to avoid
- normalisation problems: by having the connection be responsible for
- mapping equivalent resource identifiers to the same handle, Telepathy
- clients need only compare handles for integer equality. For instance,
- protocol X might consider the identifiers foobar at example.com and
- fooBaR at example.com equivalent, in which case a connection speaking
- protocol X, when asked to convert both into handles, would return the
- same handle for both.
- </para>
- <para>
- The handle 0 is never a valid handle, but may be used in the API to
- indicate a special case.
- </para>
- <para>
- Handles can be generated explicitly, using the RequestHandles method,
- in which case the client owns a reference to those handles. The
- reference can be relinquished using ReleaseHandles. In other cases, the
- connection manager might generate handles implicitly, in which case
- clients can obtain a reference using HoldHandles. Each client can only
- obtain one reference to each handle; referencing a handle multiple
- times is idempotent. A client's references are automatically released
- when it exits.
- </para>
- <para>
- Handles cease to exist when they have no implicit references (e.g. from
- a channel that they are related to) and no explicit references from
- clients.
- </para>
- </sect2>
-
- <sect2>
- <title>Interface</title>
- <para>
- </para>
- </sect2>
- </sect1>
-
- <sect1 id="sec-basics-dbus">
- <title>Using D-Bus</title>
- <para>
- Telepathy is a <indexterm><primary>D-Bus</primary></indexterm>D-Bus API.
- Telepathy components conform to the
- <ulink url="&url_spec;">Telepathy D-Bus Specification</ulink>,
- which is therefore also the main Telepathy API reference.
- </para>
-
- <para>
- D-Bus is an <indexterm><primary>IPC</primary></indexterm>IPC
- (Inter-process communication) system, allowing different software
- components running in different processes and implemented in different
- programming languages to communicate. D-Bus is primarily used as a
- server/client architecture, but one-to-one communication via a private
- bus is also possible. D-Bus is the defacto standard IPC mechanism for
- Linux.
- </para>
-
- <para>
- Most of the Telepathy examples in this book will use a
- <link linkend="sec-basics-language-bindings">language binding</link>
- instead of using D-Bus directly. However, an understanding of D-Bus is
- very helpful when learning Telepathy.
- </para>
-
- <figure id="fig.basics.dbus.conceptual">
- <title>
- Programs connected to a D-Bus Bus
- </title>
- <mediaobject><imageobject>
- <imagedata fileref="figures/bus-conceptual.png"
- format="PNG" />
- </imageobject></mediaobject>
- </figure>
-
- <variablelist>
- <varlistentry>
- <term>
- <indexterm><primary>Message Bus</primary></indexterm>
- Message Bus
- </term>
- <listitem>
- <para>
- A message bus is a bus that D-Bus messages are transmitted over,
- brokered by a D-Bus daemon. There are two main buses that
- programs communicate with: the <literal>system bus</literal>
- (for machine wide services, e.g. HAL, NetworkManager, Avahi) and
- the <literal>session bus</literal> (for user/session specific
- services, e.g. notification messages, Telepathy, desktop session
- management).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Unique Name</primary></indexterm>
- Unique Name
- </term>
- <listitem>
- <para>
- This is an identifier assigned to a client by the D-Bus daemon
- (e.g. :1.3). Every client on the D-Bus has one, whether or not
- it is offering a named service.
- It is an analagous to an IP address in computer networking.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Well-Known Name</primary></indexterm>
- Well-Known Name
- </term>
- <!-- FIXME - what's the correct markup for bus names, etc? -->
- <listitem>
- <para>
- A process can make a service available by connecting to a
- D-Bus <literal>bus</literal> and requesting a
- "well-known" bus name for the
- connection (this is sometimes referred to as a
- <literal>service name</literal>),
- by which other processes, such as applications, can
- access it.
- If unique names are analagous to IP addresses, then
- well-known names are like a DNS name.
- </para>
- <para>
- The example in
- <xref linkend="fig.basics.dbus.hierarchy-conceptual"/> provides
- the well-known bus name "org.freedesktop.foo.Foo".
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Object Path</primary></indexterm>
- Object Path
- </term>
- <listitem>
- <para>
- The service process provides D-Bus objects on that bus name.
- Each object has an <literal>object path</literal>, such as
- "/org/freedesktop/foo/jack"
- (<xref linkend="fig.basics.dbus.hierarchy-conceptual"/>),
- which a client application must specify to use that object.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Interface Name</primary></indexterm>
- Interface Name
- </term>
- <listitem>
- <para>Each D-Bus object implements one or more D-Bus interfaces.
- Each interface has an <literal>interface name</literal>, such as
- "org.freedesktop.foo.Jack"
- (<xref linkend="fig.basics.dbus.hierarchy-conceptual"/>).
- Each interface provides one
- or more methods or signals, each with a member name.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Method</primary></indexterm>
- Method
- </term>
- <listitem>
- <para>
- A D-Bus interface can expose a number of methods that can be
- called by a client. They have parameters and return types that
- are given as a D-Bus type signature.
- </para>
- <para>
- <xref linkend="fig.basics.dbus.hierarchy-conceptual"/> gives the
- example of the "Fetch" method (telling Jack to fetch a
- pail of water).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Signal</primary></indexterm>
- Signal
- </term>
- <listitem>
- <para>
- A D-Bus interface can also expose a number of signals that can be
- connected to by a client. Connecting a signal involves
- providing a callback that matches the signal's type signature
- that can be called by the mainloop (unlike
- UNIX signals, D-Bus signals are not asynchronous).
- </para>
- <para>
- <xref linkend="fig.basics.dbus.hierarchy-conceptual"/> gives the
- example of the "Broken" signal (which is triggered
- when Jack falls down and breaks his crown).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>Property</primary></indexterm>
- Property
- </term>
- <listitem>
- <para>
- D-Bus objects implementing the org.freedesktop.DBus.Properties
- interface may also expose typed properties.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <figure id="fig.basics.dbus.hierarchy-conceptual">
- <title>
- Methods and signals on an object
- </title>
- <mediaobject><imageobject>
- <imagedata fileref="figures/bus-hierarchy-conceptual.png"
- format="PNG" />
- </imageobject></mediaobject>
- </figure>
-
- <tip>
- <title>Naming in D-Bus</title>
- <para>
- A D-Bus bus is shared with lots of other clients and services, some of
- which will not have been thought of yet. It is important to ensure
- that your well-known names, objects and interfaces all have unique
- names.
- </para>
- <para>
- When choosing a well-known bus name, object name or interface name
- it is best practice to use a reversed domain name (as
- is done for Java packages) to avoid possible conflicts.
- </para>
- <para>
- For example for well-known bus names or interfaces:
- </para>
- <itemizedlist>
- <listitem><para>org.freedesktop.Telepathy.ConnectionManager</para></listitem>
- <listitem><para>org.gnome.Project</para></listitem>
- <listitem><para>com.mycompany.MyProduct</para></listitem>
- </itemizedlist>
- <para>
- For objects:
- </para>
- <itemizedlist>
- <listitem><para>/org/freedesktop/Telepathy/ConnectionManager/gabble</para></listitem>
- <listitem><para>/org/gnome/Project/adaptor</para></listitem>
- <listitem><para>/com/mycompany/MyProduct/object0</para></listitem>
- </itemizedlist>
- <para>
- For simple services, with just one object that provides just one
- interface, these three names will often look very similar.
- </para>
- </tip>
-
- <para>
- In the following sections you will see how a D-Bus API can be used from
- some common programming languages. Remember that these examples only
- create <literal>proxies</literal> to the D-Bus objects, providing a way
- to use their API. The actual objects are instantiated in the service's
- process.
- </para>
-
- <!--
- <para>In these examples, we use the FreeDesktop <literal>Notification</literal> system, which should be available on most modern Linux installations. The examples should cause a message to popup from your desktop panel. Note that, like Telepathy, this service is available on the <indexterm><primary>Session Bus</primary></indexterm><literal>Session Bus</literal> rather than the <indexterm><primary>System Bus</primary></indexterm><literal>System Bus</literal>. Services on the <literal>Session Bus</literal> are for the current user's session only. Services on the <literal>System Bus</literal> are shared between all users.</para>
- -->
-
- <warning id="warning.dbus.sync">
- <title>Always Avoid Synchronous D-Bus Calls</title>
- <!-- this information came from
- http://smcv.pseudorandom.co.uk/2008/11/nonblocking/ -->
-
- <para>
- The <ulink
- url="http://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
- specification</ulink> defines D-Bus as an asynchronous
- message-passing system, and provides no mechanism for blocking calls
- at the protocol level. However <literal>libdbus</literal> and most
- D-Bus bindings (dbus-glib, dbus-python and QtDBus) provide a
- "blocking" API
- (<function>dbus_do_something_and_block</function>) that implements a
- "pseudo-blocking" behaviour. In this mode only the D-Bus
- socket is polled for new I/O and any D-Bus messages that are not the
- reply to the original message are put on a queue for later
- processing once the reply has been received.
- </para>
-
- <para>
- This causes several major problems:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Messages can be reordered. Any message received before the reply and
- placed on the queue will be delivered to the client after the reply,
- which violates the ordering guarentee the D-Bus daemon provides.
- </para>
- <para>
- This can cause practical problems where a signal indicating an
- object's destruction is delayed. The client gets a method reply
- "UnknownMethod" and doesn't know why until the signal is
- delivered with more information.
- </para>
- </listitem>
- <listitem><para>
- The client is completely unresponsive until the service replies
- (include the user interface). If the service you're calling into has
- locked up (this can happen, even in services that are designed to be
- purely non-blocking and asynchronous), the client will be
- unresponsive for 25 seconds until the call times out.
- </para></listitem>
- <listitem><para>
- The client cannot parallelize calls — if a signal causes
- method calls to be made, a client that uses pseudo-blocking calls
- can't start processing the next message until those method calls
- return.
- </para></listitem>
- <listitem>
- <para>
- If two processes make pseudo-blocking calls on each other, a
- deadlock occurs.
- </para>
- <para>
- This sort of scenario occurs with plugin architectures and shared
- D-Bus connections. One plugin "knows" it's a client, not a service;
- and another plugin, shaing the same connection, "knows" it's a
- service, not a client. This results in a process that is both a
- service and a client (and hence deadlock-prone).
- </para>
- </listitem>
- </itemizedlist>
- </warning>
-
- <tip>
- <title>Introspecting a Bus</title>
- <para>
- Many services on a D-Bus bus provide a mechanism to introspect their
- available objects and associated interfaces. A good utility for doing
- this in an interactive way is
- <ulink url="https://fedorahosted.org/d-feet/">D-Feet</ulink>.
- </para>
- <figure id="fig.dbus.d-feet">
- <title>
- D-Feet D-Bus Introspection Tool
- </title>
- <mediaobject><imageobject>
- <imagedata fileref="figures/dfeet-dbus-introspection-tool.png"
- format="PNG" />
- </imageobject></mediaobject>
- </figure>
- <para>
- D-Feet shows each service connected to the bus and the objects,
- interfaces, methods and signals available for that service.
- It allows (synchronous) method calls to be made.
- </para>
- </tip>
-
- <sect2 id="sect.basics-dbus-glib.types">
- <title>D-Bus Type Signatures</title>
-
- <para>
- D-Bus methods and signals are strongly typed with types given by a
- D-Bus type signature. The complete documentation for D-Bus type
- signatures is presented in the
- <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures">D-Bus specification</ulink>.
- </para>
-
- <!-- FIXME: should write more here -->
- </sect2>
-
- <sect2 id="sec-basics-dbus-glib">
- <title>Using D-Bus from C, with glib</title>
-
- <!-- FIXME: something about dbus-glib
- link to
- http://dbus.freedesktop.org/doc/dbus-tutorial.html#glib-client
- -->
-
- <para>
- Before any method calls can be made or signals connected, via
- D-Bus, we need to make a connection to the message bus we wish to
- use (e.g. the system bus, the session bus or some private bus).
- Generally an application only makes one connection to each bus.
- <xref linkend="dbus-glib-methods-get-bus"/> shows how to create a
- connection to a user's session bus.
- </para>
-
- <example id="dbus-glib-methods-get-bus"
- file="basics_dbus_glib_methods/main.c">
- <title>Connecting to a Message Bus</title>
- </example>
-
- <para>
- In order to interact with a D-Bus object (i.e. call methods or
- connect signals) we need to create a proxy object for it. A proxy
- object is a <classname>GObject</classname> that we call methods on
- in our application. <xref linkend="dbus-glib-methods-get-proxy"/>
- shows connecting up a proxy object for the desktop notification
- service.
- </para>
- <example id="dbus-glib-methods-get-proxy"
- file="basics_dbus_glib_methods/main.c">
- <title>Acquiring a Proxy Object</title>
- </example>
-
- <sect3 id="sect-basics-dbus-glib-methods">
- <title>Calling Methods</title>
- <para>
- Method calls in D-Bus should <emphasis>always</emphasis> be made
- asynchronously, for the reasons
- outlined in <xref linkend="warning.dbus.sync"/>.
- <literal>dbus-glib</literal> offers a synchronous way
- to make method calls, but you should never use it,
- </para>
- <para>
- In <literal>dbus-glib</literal>, method calls are made with the function
- <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-begin-call"><function>dbus_g_proxy_begin_call</function></ulink>,
- which takes as its arguments the name of a D-Bus method to call,
- a callback function to handle the reply, optional user data and the
- parameters (and types) for the D-Bus method.
- </para>
- <para>
- <xref linkend="dbus-glib-methods-call-method"/> shows calling the
- D-Bus method <methodname>Notify</methodname> on the previously
- acquired proxy.
- </para>
-
- <example id="dbus-glib-methods-call-method"
- file="basics_dbus_glib_methods/main.c">
- <title>Calling a Method</title>
- </example>
-
- <para>
- In your reply callback, use the function
- <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-end-call"><function>dbus_g_proxy_end_call</function></ulink>
- to collect the return values from the method call. This function can
- be called outside of the reply callback, but if it is called before
- the reply has been received, it will block; causing the same problems
- as synchronous D-Bus calls.
- </para>
- <para>
- <xref linkend="dbus-glib-methods-call-method-subroutine"/> shows a
- reply callback for the method call above.
- </para>
-
- <example id="dbus-glib-methods-call-method-subroutine"
- file="basics_dbus_glib_methods/main.c">
- <title>Calling a Method: Reply Callback</title>
- </example>
- </sect3>
-
- <sect3 id="sect-basics-dbus-glib-properties">
- <title>Using Properties</title>
- <para>
- D-Bus properties are available via an additional
- <ulink url="&url_dbus_spec_base;standard-interfaces-properties"><interfacename>org.freedesktop.DBus.Properties</interfacename></ulink>
- interface on some objects, which provides the methods
- <methodname>Get</methodname>, <methodname>Set</methodname> and
- <methodname>GetAll</methodname> to get or set property values for the
- object's other interfaces.
- </para>
- <para>
- Currently <literal>dbus-glib</literal> has no specific API for handling
- properties, so they can only be accessed using the D-Bus method calls.
- <xref linkend="dbus-glib-properties"/> is therefore very
- similar to <xref linkend="dbus-glib-methods-call-method"/> presented
- above.
- </para>
-
- <example id="dbus-glib-properties"
- file="basics_dbus_glib_properties/main.c">
- <title>Accessing D-Bus Properties Using Methods</title>
- </example>
- </sect3>
-
- <sect3 id="sect-basics-dbus-glib-signals">
- <title>Handling Signals</title>
- <para>
- Handlers for D-Bus signals may be connected with the function
- <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-connect-signal"><function>dbus_g_proxy_connect_signal</function></ulink>.
- As when calling D-Bus methods, you must specify the expected
- types, but for signals you must do this in a previous call to
- <ulink url="&url_dbus_glib_base;dbus-glib-DBusGProxy.html#dbus-g-proxy-add-signal"><function>dbus_g_proxy_add_signal</function></ulink>.
- The specified callback function will then be called when the signal is
- emitted.
- </para>
- <para>
- <xref linkend="dbus-glib-signals"/>
- connects to the "DeviceAdded" signal of
- the <interface>org.freedesktop.Hal.Manager</interface> interface so it
- can print a message to the terminal when, for instance, you plug in a
- USB stick.
- </para>
-
- <example id="dbus-glib-signals"
- file="basics_dbus_glib_signals/main.c">
- <title>Connecting and Receiving a Signal</title>
- </example>
- </sect3>
-
- </sect2>
-
- <sect2 id="sec-basics-dbus-python">
- <title>Using D-Bus from Python</title>
-
- <para>
- Using D-Bus from Python is done using the <literal>dbus</literal>
- module. If you're planning on using the GLib mainloop you'll also
- need the <literal>dbus.mainloop.glib</literal> module.
- </para>
-
- <para>
- <xref linkend="dbus-python-get-bus"/> shows how to configure D-Bus to
- use the GLib mainloop for its event dispatching and then makes a
- connection to the session bus.
- </para>
-
- <example id="dbus-python-get-bus"
- file="basics_dbus_python_methods/example.py">
- <title>Connecting to a Message Bus</title>
- </example>
-
- <para>
- In order to interact with a D-Bus object (i.e. call methods or
- connect signals) we need to create a proxy object for it. A proxy
- object is a Python object that we call methods on
- in our application.
- </para>
-
- <para>
- <xref linkend="dbus-python-get-proxy"/> shows how to acquire a proxy
- object <classname>/org/freedesktop/Notifications</classname> binding
- the <interfacename>org.freedesktop.Notifications</interfacename>
- interface.
- </para>
-
- <example id="dbus-python-get-proxy"
- file="basics_dbus_python_methods/example.py">
- <title>Acquiring a Proxy Object</title>
- </example>
-
- <sect3 id="sect-basics-dbus-python-methods">
- <title>Calling Methods</title>
- <para>
- <xref linkend="dbus-python-call-method"/>
- uses <indexterm><primary>Python</primary></indexterm>
- Python to call the <methodname>Notify</methodname> method on the
- proxy object acquired in <xref linkend="dbus-python-get-proxy"/>
- above. Proxy objects in Python bind D-Bus methods into their local
- namespace (unlike when using dbus-glib, where the method name is
- passed as a string).
- </para>
-
- <para>
- The <literal>reply_handler</literal> and
- <literal>error_handler</literal> keywords are important to make your
- method call asynchronous. Method calls in D-Bus should
- <emphasis>always</emphasis> be made asynchronously, for the reasons
- outlined in <xref linkend="warning.dbus.sync"/>. Python features
- such as inline functions and lambdas are permitted as callback
- functions.
- </para>
-
- <example id="dbus-python-call-method"
- file="basics_dbus_python_methods/example.py">
- <title>Calling a Method</title>
- </example>
- </sect3>
-
- <sect3 id="sect-basics-dbus-python-properties">
- <title>Using Properties</title>
- <para>
- D-Bus properties are available via an additional
- <ulink url="&url_dbus_spec_base;standard-interfaces-properties"><interfacename>org.freedesktop.DBus.Properties</interfacename></ulink>
- interface on some objects, which provides the methods
- <methodname>Get</methodname>, <methodname>Set</methodname> and
- <methodname>GetAll</methodname> to get or set property values for the
- object's other interfaces.
- </para>
- <para>
- Python D-Bus currently has no specific API for dealing with
- properties, so they must be accessed through the D-Bus method calls.
- <xref linkend="dbus-python-properties"/> is therefore very similar to
- <xref linkend="dbus-python-call-method"/> presented above.
- </para>
- <example id="dbus-python-properties"
- file="basics_dbus_python_properties/example.py">
- <title>Accessing D-Bus Properties Using Methods</title>
- </example>
- </sect3>
-
- <sect3 id="sect-basics-dbus-python-signals">
- <title>Handling Signals</title>
- <para>
- D-Bus signal handlers may be specified in Python with the proxy object's
- <ulink url="&url_dbus_python_base;dbus.proxies.Interface-class.html#connect_to_signal"><methodname>connect_to_signal</methodname></ulink>
- method. The specified callback function will then be called when the
- signal is emitted. <xref linkend="dbus-python-signals"/> connects to
- the "DeviceAdded" signal of the
- <interfacename>org.freedesktop.Hal.Manager</interfacename> interface
- so it can print a message to the terminal when, for instance, you plug
- in a USB stick.
- </para>
-
- <example id="dbus-python-signals"
- file="basics_dbus_python_signals/example.py">
- <title>Connecting and Receiving a Signal</title>
- </example>
- </sect3>
-
- </sect2>
- </sect1>
-
- <sect1 id="sec-basics-language-bindings">
- <title>Language Bindings</title>
- <para>As mentioned in the <link linkend="sec-basics-dbus">Using D-Bus</link> section, many programming languages have their own generic ways of using D-Bus APIs. In addition, there are some Telepathy-specific APIs to make the use of Telepathy even easier. For instance, <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink> provides an API that is familiar to users of Glib and GTK+, using the GObject system and related conventions.</para>
- <para>Likewise, the <ulink url="http://telepathy.freedesktop.org/wiki/TelepathyQt">Telepathy-Qt</ulink> project provides a more Qt-like API for Telepathy and <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20Python">Telepathy-Python</ulink> does the same for Python.</para> <!-- TODO: Link to Telepathy-Qt4 when it is ready. -->
-
- <para>Remember that, like raw use of D-Bus from these programming languages, the Telepathy language bindings only create <literal>proxies</literal> to the D-Bus objects, providing a way to use their API. The actual objects are instantiated in the service's process.</para>
-
- <sect2 id="sec-basics-language-bindings-telepathy-glib">
- <title>telepathy-glib</title>
- <para>The C examples in this book will use telepathy-glib, which provides a GObject-based API for the Telepathy framework.</para>
-
- <!-- TODO: Mention this?
- <para>The reference documentation only makes sense in terms of the Telepathy D-Bus Specification.</para>
- -->
-
- <sect3 id="sec-basics-language-bindings-telepathy-glib-async">
- <title>Asynchronous Calls</title>
- <para>For each Telepathy D-Bus method, telepathy-glib generally provides both a "run" and a "call" function. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_run_connect()</ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-call-connect">tp_cli_connection_call_connect()</ulink>. The "run" function is synchronous, blocking until the D-Bus service has returned the value, whereas the "call" function is asynchronous, immediately returning and later providing the result to a callback function.</para>
- <para>
- However, the use of the "run" functions is strongly
- discouraged (see <xref linkend="warning.dbus.sync"/>), so all
- examples in this book will use the asynchronous "call"
- functions. While this might seem to complicate the examples,
- it is more robust and means the applications will be more responsive.
- </para>
- </sect3>
-
- <sect3 id="sec-basics-language-bindings-telepathy-glib-generated">
- <title>Generated Functions</title>
- <para>telepathy-glib provides both hand-coded and generated API. The generated functions have these prefixes:</para>
-
- <variablelist>
-
- <varlistentry>
- <term>tp_cli_</term>
- <listitem>
- <para>These functions are useful for client applications. For instance, <ulink url="&url_telepathy_glib_base;connection.html#tp-cli-connection-run-connect">tp_cli_connection_run_connect()</ulink>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>tp_svc_</term>
- <listitem>
- <para>These functions are useful for service implementations, such as connection managers. For instance, <ulink url="&url_telepathy_glib_base;svc-connection.html#tp-svc-connection-implement-connect">tp_svc_connection_implement_connect()</ulink>.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>The generated functions make simple direct calls to the D-Bus methods, without any additional logic and without using more appropriate types. For instance, they use unsigned integers for parameters because D-Bus does not have a concept of enumerations. However, the Telepathy D-Bus Specification does describe enumerations of possible values for these parameters, so the hand-written functions do use enums. Likewise, raw D-Bus methods can only identify object instances in terms of a <literal>bus name</literal> and <literal>object path</literal> combination, but telepathy-glib can directly provide a GObject instance that is a proxy for a D-Bus object without exposing those intermediate details.</para>
- <para>Hand-coded functions have a simple <literal>tp_</literal> prefix and should be preferred whenever they exist. The generated functions exist only because hand-written functions have not yet been implemented for all Telepathy D-Bus methods.</para>
- <para>In addition to more pleasant syntax, some hand-written objects contain a large amount of useful logic which can simplify application code. For instance, <ulink url="&url_telepathy_glib_base;contact.html"><classname>TpContact</classname></ulink> uses GObject signals. <!-- TODO: Finish this sentence. --></para>
- </sect3>
-
- <sect3>
- <title>Instantiation and Readiness</title>
- <!-- TODO: Keep any eye on http://bugs.freedesktop.org/show_bug.cgi?id=13422 -->
- <para>Some of the hand-coded objects, such as <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> and <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpChannel</classname></ulink>, call additional D-Bus methods to acquire necessary information. When they have received this information they are then "ready", meaning that other hand-written functions can then be called. This concept of "readiness" does not exist in the raw D-Bus API because it describes the status of the hand-written behaviour. For instance, you should call <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-call-when-ready">tp_connection_call_when_ready()</ulink> after instantiating a TpConnection, or <ulink url="&url_telepathy_glib_base;channel.html#tp-channel-call-when-ready">tp_channel_call_when_ready()</ulink> after instantiating a TpChannel.</para>
-
- </sect3>
-
- <sect3>
- <title>Headers and Linking</title>
- <para>To use the telepathy-glib API, you must include the headers for the library, and link to its shared library. The necessary compiler and linker commands can be obtained from the <literal>pkg-config</literal> utiltity like so:</para>
- <para>
-<programlisting>
-pkg-config telepathy-glib --cflags
-pkg-config telepathy-glib --libs
-</programlisting>
- </para>
- <para>However, if you are using the "autotools" (automake, autoconf, etc) build system, you will find it more convenient to use the <function>PKG_CHECK_MODULES</function> macro in your <literal>configure.ac</literal> file.
- </para>
- <para>
-<programlisting>
-PKG_CHECK_MODULES(EXAMPLE, telepathy-glib)
-AC_SUBST(EXAMPLE_CFLAGS)
-AC_SUBST(EXAMPLE_LIBS)
-</programlisting>
- </para>
- <para>You should then use the generated _CFLAGS and _LIBS definitions in your Makefile.am files.</para>
- </sect3>
-
- </sect2>
-
- </sect1>
-
- <!-- TODO: Notes: The interfaces are often called their type, particularly for channels. Explain. -->
- <sect1 id="sec-basics-optional-interfaces">
- <title>Optional Interfaces</title>
- <para>Although a core set of D-Bus interfaces is provided by all connection managers, some extra D-Bus interfaces are optional. For instance, some connection managers only provide extra interfaces when they discover that the remote server provides that optional functionality. Therefore, when using these interfaces, application code should first check that the interface is available, sometimes falling back to alternative interfaces.</para>
- <para>For instance, use the <interfacename>Connection</interfacename> interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>GetInterfaces()</methodname></ulink> method. For <interfacename>ConnectionManager</interfacename>s and <interfacename>Channel</interfacename>s use their <property>Interfaces</property> D-Bus property. Eventually <interfacename>Connection</interfacename> will also have an <property>Interfaces</property> property, when its <methodname>GetInterfaces()</methodname> method will be deprecated.</para>
-
- <para>When using telepathy-glib, you can simply call the <ulink url="&url_telepathy_glib_base;proxy.html#tp-proxy-has-interface"><function>tp_proxy_has_interface()</function></ulink> function for <classname>TpConnectionManager</classname>, <classname>TpConnection</classname>, or <classname>TpChannel</classname>.</para>
- <para>Actually, the core interfaces are only "recommended" by the Telepathy D-Bus specification so you should check before using any interface even if it is not commonly considered to be optional.</para>
-
- <note>
- <para>Note that the <property>Interfaces</property> property (or the <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>Connection.GetInterfaces()</methodname></ulink> method) does more than the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><methodname>Introspectable.Introspect()</methodname></ulink> method. The Telepathy-specific mechanism allows tools and language bindings to know about the possible availability of interfaces via <methodname>Introspect()</methodname> while providing an additional check that the interface is really supported for the particular connection manager with the particular remote server to which that connection manager is connected.
- </para>
- </note>
-
- <!-- TODO: Add dbus-glib and Python examples of checking-for and using an Interface. -->
- </sect1>
-
- <!-- TODO: Should we even mention this before the new (5?) version is ready?
- <sect1 id="sec-basics-mission-control">
- <title>Mission Control</title>
- <para>TODO: Notes: desktop-wide accounts and dispatching to applications.
- </para>
- </sect1>
- -->
-
- <sect1 id="sec-basics-handles">
- <title>Handles</title>
- <para>The Telepathy D-Bus API does not have D-Bus objects to represent contacts, groups, or rooms. These are instead identified by numeric <literal>handles</literal>. This is for performance reasons, and because it is easier to compare numeric handles than to discover if two D-Bus proxy objects refer to the same object instance.</para>
- <para>These numeric handles are only unique within a Telepathy Connection. For instance, don't try to use a Connection's contact handle with a different Connection. The handles also only make sense when combined with a <ulink url="&url_spec;#type-Handle_Type">handle type</ulink>, telling the API whether it represents a contact, group, or list. In fact, two handles may be numerically identical but be for different types.</para>
-
- <sect2>
- <title>Hold and Release</title>
- <para>When a Telepathy object has finished with a handle that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to "hold" the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><methodname>HoldHandles()</methodname></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><methodname>ReleaseHandles()</methodname></ulink> when you have finished with the handle. However, a single <methodname>ReleaseHandles()</methodname> call will release a handle regardless of how many times <methodname>HoldHandles()</methodname> has been called, so be careful not to call it while other code may be using the handle.</para>
-
- <para>This is less necessary when using Telepathy <link linkend="sec-basics-language-bindings">language bindings</link>, such as telepathy-glib, because they may automatically hold and release handles for the lifetime of their objects, such as telepathy-glib's <classname>TpContact</classname> object. Additionally, telepathy-glib wraps the <methodname>HoldHandles()</methodname> and <methodname>ReleaseHandles()</methodname> D-Bus methods with the <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-hold-handles"><function>tp_connection_hold_handles()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-unref-handles"><function>tp_connection_unref_handles()</function></ulink> functions which reference-count the client-side handle "hold", allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
-
- <!-- TODO: On irc, smcv said: "perhaps "the user types in the name of a chatroom to join" would be a better example of when you want to use tp_connection_request_handles/tp_connection_unref_handles". Explain that more fully. -->
-
- <para>In the later sections we will mention when it actually makes sense to do this when using specific parts of the Telepathy API.</para>
- </sect2>
-
- </sect1>
-
- <sect1 id="sec-basics-api-conventions">
- <title>API conventions</title>
-
- <para>
- There is a general convention for method names in Telepathy.
- </para>
-
- <para>
- Many method names begin with <emphasis>Get</emphasis> (e.g.
- <methodname>GetAliases</methodname>, <methodname>GetParameters</methodname>,
- <methodname>GetInterfaces</methodname>, etc.).
- <emphasis>Get</emphasis> methods
- will only ever return immutable or cached data. They never block on a
- network request to a remote service; so data should be available
- immediately (see <xref linkend="note.basics-api-conventions.get-triggers"/>
- below).
- </para>
- <para>
- Method names beginning with <emphasis>Request</emphasis> (e.g.
- <methodname>RequestAliases</methodname>,
- <methodname>RequestAvatars</methodname>,
- <methodname>RequestContactInfo</methodname>, etc.) may make network
- requests (but not always, this depends on the Connection Manager).
- Depending on the network service, its latency and the size of the
- reply, it may be some time before data is available (or the network
- might fail and eventually an error will be returned).
- </para>
- <!-- FIXME: should Ensure/Create methods be mentioned?
- what about any types of signals? -->
-
- <warning>
- <title>Always Use Asynchronous Method Calls</title>
- <para>
- Even when using a <emphasis>Get</emphasis> call, for which the
- information will already be available, you must
- <emphasis>always</emphasis> make asynchronous requests via D-Bus for the
- reasons outlined in <xref linkend="warning.dbus.sync"/>.
- </para>
- </warning>
-
- <note id="note.basics-api-conventions.get-triggers">
- <title>Get Calls Can Trigger Network Traffic</title>
-
- <para>
- Telepathy interprets <emphasis>Get</emphasis> calls as a way for a
- client to show interest in information.
- </para>
- <para>
- In the case where there is no information cached in a Connection
- Manager, <emphasis>Get</emphasis> calls may choose to trigger a
- network request. The current (empty) cache will be returned as the
- reply, but upon completion of the request a signal will be emitted to
- indicate new data is available.
- </para>
- <para>
- For example, if there is no cached data,
- <methodname>GetAliases</methodname> will return no information, but a
- request for alias information will be made to the remote service.
- Once that information has been retrieved the AliasesChanged signal will be
- emitted.
- </para>
- </note>
-
- </sect1>
-
-</chapter>
-
-<chapter id="chapter-accounts">
- <title>Accounts and AccountManager</title>
- <note>
- <para>
- The <interfacename>AccountManager</interfacename> and
- <interfacename>Account</interfacename> interfaces are not implemented
- in <application>Mission Control 5</application> exactly as they are
- specified in the Telepathy API specification.
- </para>
-
- <para>
- <application>Mission Control 4</application> implements a completely
- different interface which is not documented here.
- </para>
- </note>
-
- <para>
- The Account Manager is implemented as part of Mission Control and is
- responsible for keeping a list of accounts (e.g. XMPP/Jabber, IRC, MSN).
- The service is available on the session bus via the well-known bus name
- <literal>org.freedesktop.Telepathy.AccountManager</literal>, object
- <literal>/org/freedesktop/Telepathy/AccountManager</literal> and
- interface <literal>org.freedesktop.Telepathy.AccountManager</literal>.
- </para>
-
- <para>
- To get a list of all accounts known to the Account Manager, you can
- access the <property>ValidAccounts</property> and
- <property>InvalidAccounts</property> properties, both of which return an
- array of D-Bus objects. Valid accounts are accounts that are complete
- and usable for establishing a connection to a remote service. Invalid
- accounts are incomplete or otherwise unusable and cannot be used to
- establish a connection.
- </para>
-
- <!-- FIXME: example listing accounts -->
-
- <sect1 id="sect.accounts.accounts">
- <title>Accounts</title>
- <para>
- Account objects store off of the information that is used for making a
- <link linkend="chapter-connection">Connection</link> to a remote
- service. Mission Control can be used to establish connections for valid
- accounts.
- </para>
-
- <para>
- <interfacename>Account</interfacename> objects have object paths of the form
- <literal>/org/freedesktop/Telepathy/Account/cm/proto/acct</literal>
- where <literal>cm</literal> is the Connection Manager name (e.g. gabble,
- salut) and <literal>proto</literal> is the protocol name (as used in the
- object path of a <interfacename>Connection</interfacename>). Account
- objects implement the interface
- <literal>org.freedesktop.Telepathy.Account</literal>.
- </para>
-
- <para>
- Settings for an account are managed through D-Bus properties. To reduce
- D-Bus roundtrips: bulk read the properties with the standard
- <methodname>org.freedesktop.DBus.Properties.GetAll</methodname> method;
- bulk set properties with the
- <methodname>org.freedesktop.Telepathy.Account.UpdateParameters</methodname>
- method. <xref linkend="table.accounts.account-properties"/> shows the
- properties of an <interfacename>Account</interfacename> object.
- </para>
-
- <table id="table.accounts.account-properties">
- <title>Account Properties</title>
- <tgroup cols="4">
- <colspec colname="property"/>
- <colspec colname="type"/>
- <colspec colname="description"/>
- <colspec colname="example"/>
- <thead>
-
- <row>
- <entry namest="property" nameend="example">
- Read/Write Properties
- </entry>
- </row>
- <row>
- <entry>Property</entry><entry>Type</entry>
- <entry>Description</entry><entry>Example</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>DisplayName</entry><entry>String</entry>
- <entry>
- The user-visible name of this account. This is how the account is
- referred to in the user interface, and should be able to be set by
- the user.
- </entry>
- <entry>Jabber (bob at example.com), Work</entry>
- </row>
-
- <row>
- <entry>Icon</entry><entry>String</entry>
- <entry>
- The name of an icon in the system's icon theme or the empty string to
- not specify an icon (in which case one may be automatically chosen).
- </entry>
- <entry>im-msn</entry>
- </row>
-
- <row>
- <entry>Enabled</entry><entry>Boolean</entry>
- <entry>
- Whether or not an account is enabled (whether or not it can be used
- to go online). N.B. this is different from whether or not it is
- Valid.
- </entry>
- <entry>True</entry>
- </row>
-
- <row>
- <entry>Nickname</entry><entry>String</entry>
- <entry>
- The nickname to set on this account for display to other contacts,
- as set by the user.
- </entry>
- <entry>
- Bob McBadgers
- </entry>
- </row>
-
- <row>
- <entry>AutomaticPresence</entry><entry><type>SimplePresence</type></entry>
- <entry>
- The presence status that this account should have if it is brought
- online.
- </entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>ConnectAutomatically</entry><entry>Boolean</entry>
- <entry>
- Whether or not the Account Manager should automatically establish a
- <link xref="chapter-connection">Connection</link> for this account.
- </entry>
- <entry>True</entry>
- </row>
-
- <row>
- <entry>RequestedPresence</entry><entry><type>SimplePresence</type></entry>
- <entry>
- The requested presence for this account.
- </entry>
- <entry></entry>
- </row>
-
- </tbody>
- </tgroup>
-
- <tgroup cols="4">
- <colspec colname="property"/>
- <colspec colname="type"/>
- <colspec colname="description"/>
- <colspec colname="example"/>
- <thead>
- <row>
- <entry namest="property" nameend="example">
- Read-Only Properties
- </entry>
- </row>
- <row>
- <entry>Property</entry><entry>Type</entry>
- <entry>Description</entry><entry>Example</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>Interfaces</entry><entry><type>DBus_Interface[]</type></entry>
- <entry>
- A list of the extra interfaces provided by this account.
- </entry>
- <entry>
- <interfacename>org.freedesktop.Telepathy.Account.Interface.Avatar</interfacename>
- </entry>
- </row>
-
- <row>
- <entry>Valid</entry><entry>Boolean</entry>
- <entry>
- Whether this account is considered by the Account Banager to be
- complete and usable.
- </entry>
- <entry>True</entry>
- </row>
-
- <row>
- <entry>Parameters</entry><entry>Map</entry>
- <entry>
- A map from connection manager parameter names (as in the
- <interfacename>ConnectionManager</interfacename> interface) to their
- values.
- </entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>Connection</entry><entry><interfacename>Connection</interfacename></entry>
- <entry>
- Either the object path of the Connection to this account, or the
- special value '/' if there is no connection.
- </entry>
- <entry>
- /org/freedesktop/Telepathy/Connection/gabble/jabber/bob_40example_2ecom_2fwork
- </entry>
- </row>
-
- <row>
- <entry>ConnectionStatus</entry><entry>integer</entry>
- <entry>
- If the Connection property is non-empty, the status of that
- connection.
- </entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>ConnectionStatusReason</entry><entry>integer</entry>
- <entry>
- The reason for the last change to ConnectionStatus.
- </entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>CurrentPresence</entry><entry><type>SimplePresence</type></entry>
- <entry>
- The actual presence of the account.
- </entry>
- <entry></entry>
- </row>
-
- <row>
- <entry>NormalizedName</entry><entry>String</entry>
- <entry>
- The normalized user ID of the local user on this account.
- </entry>
- <entry></entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </sect1>
-
- <!-- para>TODO:
- Notes:
- - This is described in the telepathy specification but only partially
- implemented in Nokia mission control.
- - AccountManager contains a list of my accounts (my jabber account, my
- ICQ account, etc)
- - This is a desktop-wide list of accounts shared by all applications (via
- the Mission Control service)
- - most developers probably won't need to deal with them much.
- - This is not a list of remote accounts held by my contacts.
- - Includes the parameters which are passed to RequestConnection().
- - Includes some other parameters such as your avatar/your alias, which the
- AccountManager takes care of setting for you
- - Responds to connectivity events/requests.
- </para -->
-</chapter>
-
-<chapter id="chapter-channel-dispatcher">
- <title>TODO: ChannelDispatcher</title>
- <para>TODO:
- Notes:
- - This is in mission control.
- - This dispatches some events to applications that care about them, by
- calling a method on the ChannelHandler interface (that the application
- implements). This API is currently in flux.
- </para>
-</chapter>
-
-<chapter id="chapter-connection-manager">
- <title>Connection Manager</title>
-
-<!-- these paragraphs came from Basics -->
- <para>Support for the various communication protocols is provided by several <literal>Connection Managers</literal>. For instance, the <literal>telepathy-gabble</literal> Connection Manager provides support for the <acronym>XMPP</acronym> protocol, also known as <literal>Jabber</literal>.</para>
- <para>There is no central &app; D-Bus service. Instead there are several connection manager services, activated on demand, and each of these connection managers provide the same core set of D-Bus interfaces, such as <ulink url="&url_spec_base;Connection"><interfacename>Connection</interfacename></ulink> and <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink>, allowing application code to be written generically for all connection managers.</para>
-
-<!-- these paragraphs have always been here -->
-<!--
- <para>As mentioned in the <link linkend="sec-basics-connection-managers">Basics</link> chapter, each <ulink url="&url_spec_base;ConnectionManager"><interfacename>ConnectionManager</interfacename></ulink> provides support for a communication protocol.</para>
- -->
-
- <para>All Telepathy Connection Managers have <literal>bus name</literal>s that begin with "org.freedesktop.Telepathy.ConnectionManager" so you can discover all available connection managers by calling the D-Bus <ulink url="&url_dbus_spec_base;bus-messages-list-activatable-names"><methodname>ListActivatableNames()</methodname></ulink> method and then comparing the names with that prefix. telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers()</function></ulink> function that conveniently does this.</para>
- <para>You may then discover what protocols are provided by each connection manager by calling the ConnectionManagers's <ulink url="&url_spec_base;ConnectionManager.ListProtocols"><methodname>ListProtocols()</methodname></ulink> D-Bus method. telepathy-glib's <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink> object calls this automatically and emits the <literal>got-info</literal> signal when it has returned. You can examine the TpConnectionManager::protocols struct field in your signal handler.</para>
- <para>Applications, such as IM clients, might choose to offer the user a choice from that list of protocols and then use the appropriate connection manager. Others might use only one protocol and therefore hard-code the connection manager's <literal>bus name</literal>.</para>
-
- <sect1>
- <title>Protocols Listing Example</title>
- <para>This example list all available connection managers and the protocols they support.</para>
- <para><ulink url="&url_examples_base;list_all_protocols">Source Code</ulink></para>
- </sect1>
-
-</chapter>
-
-<chapter id="chapter-connection">
- <title>Connection</title>
-
- <para>
- A <interfacename>Connection</interfacename> object in Telepathy
- represents an active (or activatable) protocol session. Connections are
- created by the appropriate
- <link xref="chapter-connection-manager">Connection Manager</link>.
- </para>
-
- <para>
- A connection can be located on the D-Bus session bus via the well-known name
- <literal>org.freedesktop.Telepathy.Connection.cm.proto.account</literal>,
- where <literal>cm</literal> is the name of the Connection Manager that
- created the connection (e.g. gabble, salut) and <literal>proto</literal>
- is the name of a Telepathy <type>Protocol</type> (e.g. jabber, msn, irc).
- The connection object can then be retrieved from the path
- <literal>/org/freedesktop/Telepathy/Connection/cm/proto/account</literal>.
- </para>
-
- <para>
- Depending on what features are supported by the protocol, a given
- connection will implement more interfaces than just
- <interfacename>Connection</interfacename>. The interfaces supported by
- a given connection can be retreived using the
- <methodname>GetInterfaces</methodname> method once the connection is in
- the <literal>CONNECTED</literal> state. The supported list of interfaces
- doesn't change during the life on a connection, so it is expected that a
- client will retreive this once the connection is
- <literal>CONNECTED</literal>.
- </para>
-
- <para>
- Interfaces that a connection might support are:
- </para>
- <itemizedlist>
- <listitem>
- <para><interfacename>Requests</interfacename></para>
- <para>
- The <interfacename>Requests</interfacename> interface is used to
- obtain <link linkend="chapter-channel">channels</link>, which are how
- data is exchanged in Telepathy. Its use is documented in
- <xref linkend="sec-channel-requesting"/>.
- </para>
- </listitem>
- <listitem>
- <para><interfacename>Contacts</interfacename></para>
- <para>
- 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"/>.
- </para>
- </listitem>
- <listitem>
- <para><interfacename>SimplePresence</interfacename></para>
- <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"/>.
- </para>
- </listitem>
- <listitem>
- <para>Avatars</para>
- <para>
- Describe me
- </para>
- </listitem>
- <listitem>
- <para>Capabilities</para>
- <para>
- Describe me
- </para>
- </listitem>
- <!--
- <listitem>
- <para>ContactCapabilities</para>
- <para>
- Draft
- </para>
- </listitem>
- -->
- <!--
- <listitem>
- <para>ContactInfo</para>
- <para>
- Draft
- </para>
- </listitem>
- -->
- <!--
- <listitem>
- <para>Location</para>
- <para>
- Draft
- </para>
- </listitem>
- -->
- <!--
- <listitem>
- <para>Presence</para>
- <para>
- Deprecated with extreme prejudice.
- </para>
- </listitem>
- -->
- <listitem>
- <para>Renaming</para>
- <para>
- Describe me
- </para>
- </listitem>
- </itemizedlist>
-
- <sect1>
- <title>Obtaining a Connection</title>
-
- <sect2>
- <title>From the Account Manager</title>
-
- <note>
- <para>
- The <interfacename>AccountManager</interfacename> and
- <interfacename>Account</interfacename> interfaces are not implemented
- in <application>Mission Control 5</application> exactly as they are
- specified in the Telepathy API specification.
- </para>
- <para>
- <application>Mission Control 4</application> implements a completely
- different interface which is not documented here.
- </para>
- </note>
-
- <para>
- In general, Telepathy clients will want to share the same set of
- already-configured accounts rather than managing their own accounts
- and setting up their own connections. The
- <link linkend="chapter-accounts">Account Manager</link> manages
- connections for configured accounts which can be retrieved as a
- property from each <interfacename>Account</interfacename> object.
- </para>
- </sect2>
-
- <sect2>
- <title>From a Connection Manager</title>
- <para>
- There might be times when you are using Telepathy without an
- Account Manager and need to manually set up your own connections using
- the Connection Manager. For example, a status reporting client that
- runs as its own user without a desktop session might only run itself,
- <application>dbus-daemon</application> and a Connection Manager.
- </para>
-
- <para>
- To setup your own connection to the remote server (e.g. your Jabber
- IM account) you need to call <methodname>RequestConnection</methodname>
- on the appropriate <link xref="chapter-connection-manager">Connection
- Manager</link> (e.g. gabble), providing a map of connection details.
- Assuming the connection succeeds this method will return the
- <literal>bus name</literal> and <literal>object path</literal>
- of a newly created Telepathy <interfacename>Connection</interfacename>
- object.
- </para>
-
- <para>
- To determine what parameters are required or optional for a given
- Connection Manager its <methodname>GetParameters</methodname> method
- should be called with the relevant protocol.
- <xref linkend="example.connection.get_parameters"/> shows how this is
- done. Some common, "well-known" parameters names are shown
- in <xref linkend="table.connection.well_known_parameters"/>.
- </para>
-
- <example id="example.connection.get_parameters"
- file="python_get_parameters/example.py">
- <title>Getting Connection Parameters</title>
- </example>
-
- <table id="table.connection.well_known_parameters">
- <title>Well-Known Connection Parameters for RequestConnection</title>
- <tgroup cols="4">
- <colspec colname="property"/>
- <colspec colname="type"/>
- <colspec colname="description"/>
- <colspec colname="example"/>
-
- <thead>
- <row>
- <entry>Property</entry><entry>Type</entry>
- <entry>Description</entry><entry>Example</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>account</entry><entry>String</entry>
- <entry>
- The identifier for the user's account on the server.
- </entry>
- <entry>bob at example.com</entry>
- </row>
-
- <row>
- <entry>server</entry><entry>String</entry>
- <entry>
- A fully qualified domain name or numeric IPv4 or IPv6 address.
- </entry>
- <entry>xmpp.example.com</entry>
- </row>
-
- <row>
- <entry>port</entry><entry>uint16</entry>
- <entry>
- A TCP/UDP network port.
- </entry>
- <entry>8080</entry>
- </row>
-
- <row>
- <entry>require-encryption</entry><entry>Boolean</entry>
- <entry>
- Require encryption for this connection.
- </entry>
- <entry>False</entry>
- </row>
-
- <row>
- <entry>register</entry><entry>Boolean</entry>
- <entry>
- This account should be created on the server if it does not
- already exist.
- </entry>
- <entry>False</entry>
- </row>
-
- <row>
- <entry>ident</entry><entry>String</entry>
- <entry>
- The local username to report to the server.
- </entry>
- <entry>bmcbadgers</entry>
- </row>
-
- <row>
- <entry>fullname</entry><entry>String</entry>
- <entry>
- The user's full name.
- </entry>
- <entry>Bob McBadgers</entry>
- </row>
-
- <row>
- <entry>stun-server</entry><entry>String</entry>
- <entry>
- A fully qualified domain name or numeric IPv4 or IPv6 address of a
- STUN server to use for NAT traversal.
- </entry>
- <entry>stun.example.com</entry>
- </row>
-
- <row>
- <entry>stun-port</entry><entry>uint16</entry>
- <entry>
- A UDP network port for the STUN server.
- </entry>
- <entry>1337</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- The new connection will not actually attempt to establish a network
- connection until its <methodname>Connect</methodname> method has been
- called. The connection will be ready to use after the
- <methodname>StatusChanged</methodname> signal returns a
- <type>Connection_Status</type> of <literal>Connected</literal>.
- </para>
-
- <para>
- <xref linkend="example.connection.establish-connection"/> shows how to
- manually establish a connection.
- </para>
-
- <!--
- <para>As of this writing, there is no hand-coded telepathy-glib function to request the connection and directly provide a <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> proxy. However, you may use the generated <ulink url="&url_telepathy_glib_base;connection-manager.html#tp_cli_connection_manager_call_request_connection"><function>tp_cli_connection_manager_call_request_connection()</function></ulink> function. In the callback, you can then use the provided <literal>bus name</literal> and <literal>object path</literal> to instantiate a TpConnection proxy object.</para>
-
- <note><para>See the <link linkend="sec-basics-language-bindings-telepathy-glib-generated">Basics</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
-
- <para>See the <link linkend="chapter-channel">Channels</link> section about obtaining and using <interfacename>Channel</interfacename>s from the <interfacename>Connection</interfacename> with which you can list groups of contacts .</para>
- -->
-
- <example id="example.connection.establish-connection">
- <title>Establishing a Connection</title>
- <!--
- <para><ulink url="&url_examples_base;connect">Source Code</ulink></para>
- -->
- </example>
-
- </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>ContractAttributeInterfaces</property> property.
- </para>
- </sect1>
-
- <sect1 id="sect.connection.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 accounts
- the on the user's roster).
- </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>
-
- <sect2>
- <title>Setting the User's Presence</title>
-
- <sect3>
- <title>Via the Account Manager</title>
- <note>
- <para>
- The <interfacename>AccountManager</interfacename> and
- <interfacename>Account</interfacename> interfaces are not implemented
- in <application>Mission Control 5</application> exactly as they are
- specified in the Telepathy API specification.
- </para>
-
- <para>
- <application>Mission Control 4</application> implements a completely
- different interface which is not documented here.
- </para>
- </note>
-
- <para>
- If this Connection was obtained from the
- <link linkend="chapter-accounts">Account Manager</link>, then the
- user's presence can be set on the appropriate
- <link linkend="sect.accounts.accounts">Account</link> object using
- the <property>RequestPresence</property> property of the
- <interfacename>Account</interfacename> interface. This property takes
- a <type>SimplePresence</type> as its value.
- </para>
- </sect3>
-
- <sect3>
- <title>Via the Connection</title>
- <para>
- The user sets their own presence via the
- <methodname>SetPresence</methodname> method. Parameters are a status
- identifier (e.g. available, away, hidden) and an optional status message
- (e.g. "At the Movies"). Valid status identifiers for this
- connection can be retrieved using the <property>Statuses</property>.
- </para>
- </sect3>
- </sect2>
-
- <!--
- <sect2>
- <title>Presence Example</title>
- <para>This example sets the presence for a jabber account, by calling the <methodname>SetPresence()</methodname> method of the <interfacename>Connection</interfacename>'s <interfacename>SimplePresence</interfacename> interface, using telepathy-glib.</para>
- <para><ulink url="&url_examples_base;set_presence">Source Code</ulink></para>
- </sect2>
- -->
-
- </sect1>
-
-</chapter>
-
-<chapter id="chapter-channel">
- <title>Channel</title>
- <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.
- </para>
- <para>
- Channels always provide at least two D-Bus interfaces interfaces:
- <interfacename>org.freedesktop.telepathy.Channel</interfacename>,
- and another interface according to the type of channel it is (which can
- be retrieved using the <property>ChannelType</property> property).
- For instance, a text channel provides the
- <interfacename>org.freedesktop.telepathy.ChannelType.Text</interfacename>
- interface.
- </para>
-
- <!-- para>
- Channels are created using a connection's RequestChannel method, or are
- created by the connection manager in response to communication
- initiated by someone else, in which case their advent is heralded by
- the NewChannel signal.
- </para -->
-
- <para>
- The channel types currently available in Telepathy are:
- </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.
- </para>
- <para>
- See <xref linkend="sect-channel-contactlist"/>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary>RoomList</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.RoomList"><interfacename>RoomList</interfacename></ulink>
- </term>
- <listitem>
- <para>
- A channel type for listing named channels (e.g. chatrooms)
- available on the server.
- </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.
- </para>
- <para>
- See <xref linkend="sect-channel-text"/>.
- </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>Tubes</primary></indexterm>
- <ulink url="&url_spec_base;Channel.Type.Tubes"><interfacename>Tubes</interfacename></ulink>
- </term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry-->
-
- <varlistentry>
- <term>
- <indexterm><primary>FileTransfer</primary></indexterm>
- <ulink
- url="&url_spec_base;Channel.Type.FileTransfer"><interfacename>FileTransfer</interfacename></ulink>
- </term>
- <listitem>
- <para>
- A channel type for transferring files.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <sect1 id="sec-channel-requesting">
- <title>Requesting Channels</title>
-
- <para>
- Channels are requested from a <classname>Connection</classname> object
- using the <ulink url="&url_spec_base;Connection.Interface.Requests"><interfacename>Requests</interfacename></ulink>
- interface.
- </para>
-
- <para>
- This interface provides two methods:
- <methodname>CreateChannel</methodname> and
- <methodname>EnsureChannel</methodname>.
- Both methods take the same parameter, a dictionary containing the
- desired properties for the channel.
- </para>
-
- <para>
- <methodname>CreateChannel</methodname> will attempt to create a new
- channel with the requested properties. Depending on the protocol, some
- types of channels are exclusive, and only one such channel can exist at
- a time (e.g. a XMPP chatroom). If a second channel is requested, the
- error <errorname>NotAvailable</errorname> is returned.
- </para>
-
- <para>
- Conversely, <methodname>EnsureChannel</methodname> will attempt to reuse an
- existing channel with the same properties wherever possible, else it
- will create a new channel. It's possible that another client is also
- utilising this channel. <!-- FIXME: write more on this -->
- </para>
-
- <tip>
- <title>When to Create and when to Ensure</title>
- <para>
- Choosing when to always create a new channel, or when to use an
- existing channel can usually be deduced based on the function of the
- channel. If it would make sense to reuse an existing channel then
- use <methodname>EnsureChannel</methodname>, otherwise use
- <methodname>CreateChannel</methodname>.
- </para>
- <para>
- <methodname>EnsureChannel</methodname> is usually used for
- <interfacename>Text</interfacename>,
- <interfacename>StreamedMedia</interfacename> and
- <interfacename>ContactList</interfacename> channels.
- </para>
- <para>
- <methodname>CreateChannel</methodname> is usually used for
- <interfacename>FileTransfer</interfacename>,
- <interfacename>Tubes</interfacename>,
- <interfacename>RoomList</interfacename> and
- <interfacename>ContactSearch</interfacename> channels.
- </para>
- </tip>
-
- <para>
- The properties argument for <methodname>RequestChannel</methodname> and
- <methodname>EnsureChannel</methodname> is a map of property names on
- the desired channel, and their values.
- In general every channel requires at least three channel
- properties: the type of channel we wish to create
- (<property>ChannelType</property>), the handle/id of the contact/room/list
- we wish to create a channel for (<property>TargetHandle</property> or
- <property>TargetID</property>) and the type of that handle
- (<property>TargetHandleType</property>). Specific channel types may
- require additional properties in order to be created, this is noted in
- the specification.
- </para>
-
- <para>
- For example, to create a <interfacename>ContactList</interfacename>
- channel (this is the type of channel that is used to get a list of
- subscribed contacts from a service), we might provide a map like so:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>org.freedesktop.Telepathy.Channel.ChannelType</entry>
- <entry>org.freedesktop.Telepathy.Channel.Type.ContactList</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Channel.TargetHandleType</entry>
- <entry>Handle_Type_List</entry>
- </row>
- <row>
- <entry>org.freedesktop.Telepathy.Channel.TargetID</entry>
- <entry>"subscribe"</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <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>
-
- <warning>
- <title>RequestChannel</title>
- <para>
- Some Connection Managers might not yet implement the
- <interfacename>Requests</interfacename> interface on their
- <classname>Connection</classname>s. In these cases you can
- use the <methodname>RequestChannel</methodname> method on the
- <interfacename>Connection</interfacename> interface, but you do so at
- your own risk.
- </para>
- <para>
- <methodname>CreateChannel</methodname> and
- <methodname>EnsureChannel</methodname> fix several flaws that were
- present in <methodname>RequestChannel</methodname>:
- </para>
- <itemizedlist>
- <listitem><para>
- <methodname>RequestChannel</methodname> doesn't provide a way to insist
- on a new channel or prefer an existing channel;
- </para></listitem>
- <listitem><para>
- If <methodname>RequestChannel</methodname> returns an existing
- channel, the caller is not told whether the channel can be safely
- handled or if something else is handling it already;
- </para></listitem>
- <listitem><para>
- <methodname>RequestChannel</methodname> can request a channel type,
- a handle type and a handle, but nothing more elaborate
- (e.g. you can't request a <interfacename>RoomList</interfacename>
- with a particular server); and
- </para></listitem>
- <listitem><para>
- <methodname>RequestChannel</methodname> doesn't return the channel's
- immutable properties (which is a useful optimization).
- </para></listitem>
- </itemizedlist>
-
- <para>
- If you must call <methodname>RequestChannel</methodname>, XXX WRITE ME
- </para>
- </warning>
-
- </sect1>
-
- <sect1 id="sect-channel-contactlist">
- <title>ContactList Channel</title>
- <indexterm><primary>ContactList</primary></indexterm>
-
- <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 <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>
- 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. -->
-
- <!-- 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.) -->
-
- <sect2 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>
- </sect2>
-
- <sect2>
- <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>
- </sect2>
-
- </sect1>
-
- <sect1 id="chapter-group">
- <title>Group Interface</title>
- <para>TODO:
- (used in lots of different channels)
- - This is partitioned into:
- - Current members
- - Local pending members, awaiting approval (by doing Add or Remove) by the
- local user.
- - Remote pending members, awaiting approval remotely by the other user)
- - Unusually, one-to-one calls use the <ulink url="&url_spec_base;Channel.Interface.Group">Group</ulink> interface to indicate call
- progression (explain in call section?).
- </para>
- </sect1>
-
- <sect1 id="sect-channel-text">
- <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>
- (<property>TargetHandle</property>) or identifier
- (<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: Password interfaces
- </para>
-
- <sect2 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>
- Some 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>
-
- <sect3>
- <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>
- </sect3>
- </sect2>
-
- <sect2 id="sec-channel-text-receiving">
- <title>Receiving Messages</title>
- <para>TODO</para>
-
- <para>TODO: Notes: - Text channels may have ChatState (typing notification).</para>
-
- <sect3>
- <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> -->
- </sect3>
- </sect2>
-
- </sect1>
-
-</chapter>
-
-<chapter id="chapter-tubes">
- <title>Tubes</title>
- <para>TODO:
- - Helps me to implement an ad-hoc protocol or data-exchange structure above
- what the IM protocol does.
- - You wouldn't need a tube for a chat, because the IM protocol has that
- already, but you'd need to implement more for some custom thing like
- networking of a game.
- - Streamed Media Channels
- </para>
-</chapter>
+<xi:include href="introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<xi:include href="basics.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<xi:include href="accounts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<xi:include href="channel-dispatcher.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<xi:include href="connection-manager.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="tubes.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<!--
Note: The following sections are more tutorial-like, describing how to implement
diff --git a/docs/book/C/tubes.xml b/docs/book/C/tubes.xml
new file mode 100644
index 0000000..f568609
--- /dev/null
+++ b/docs/book/C/tubes.xml
@@ -0,0 +1,39 @@
+<?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" [
+
+ <!-- These entities are used in the generated .omf files,
+ along with the author tags,
+ allowing the Yelp help browser to know about the document.
+
+ The legal.xml file contains legal information, there is no need to edit the file.
+ Use the appversion entity to specify the version of the application.
+ Use the manrevision entity to specify the revision number of this manual.
+ Use the date entity to specify the release date of this manual.
+ Use the app entity to specify the name of the application. -->
+ <!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-tubes">
+ <title>Tubes</title>
+ <para>TODO:
+ - Helps me to implement an ad-hoc protocol or data-exchange structure above
+ what the IM protocol does.
+ - You wouldn't need a tube for a chat, because the IM protocol has that
+ already, but you'd need to implement more for some custom thing like
+ networking of a game.
+ - Streamed Media Channels
+ </para>
+</chapter>
diff --git a/docs/examples/.gitignore b/docs/examples/.gitignore
new file mode 100644
index 0000000..b330614
--- /dev/null
+++ b/docs/examples/.gitignore
@@ -0,0 +1,3 @@
+*/.deps/
+*.o
+example
--
1.5.6.5
More information about the telepathy-commits
mailing list