path: root/docs/book/C/basics.xml

<?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 "&#8212;">
  <!ENTITY url_spec "http://telepathy.freedesktop.org/spec/">
  <!ENTITY url_telepathy_glib_base "http://telepathy.freedesktop.org/doc/telepathy-glib/">
  <!ENTITY url_dbus_spec_base "http://dbus.freedesktop.org/doc/dbus-specification.html#">
  <!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 id="sect.basics.terminology">
   <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="sect.basics.dbus"/>.
    For more indepth information, consult A MANUAL THAT PROBABLY HASN'T BEEN
    WRITTEN YET.<!-- FIXME -->
   </para>

   <sect2 id="sect.basics.terminology.mission-control">
    <title>Mission Control</title>
    <para>
     Mission Control provides the Account Manager and Channel Dispatcher.
    </para>
    <para>
     This manual is specifically concerned with Mission Control 5. There are
     earlier versions of Mission Control, but they are extremely different
     to the version documented here.
    </para>
    <para>
     It's possible that a particular device uses a different Account Manager
     or Channel Dispatcher from Mission Control, but this may still be
     referred to by the name Mission Control.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.account-manager">
    <title>Account Manager</title>
    <para>
     The Account Manager is responsible for maintaining the list of
     configured accounts for a user and setting up Connection's to those
     accounts.
    </para>
    <para>
     In general, a client will request available Accounts and Connections,
     and control the user's online presence via the Account Manager.
    </para>
    <para>
     The Account Manager is documented in
     <xref linkend="chapter.accounts"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.channel-dispatcher">
    <title>Channel Dispatcher</title>
    <para>
     The Channel Dispatcher handles incoming Channels from the various
     Connections known to the Account Manager and dispatches them to the
     appropriate Telepathy Client (e.g. chat client, VoIP client, Tube
     application).
    </para>
    <para>
     The Channel Dispatcher may also be used to request Channels that you
     want another client to handle (e.g. a program wanting to open a
     text-chat to a user, but not wanting to handle the chat itself).
    </para>
    <para>
     The Channel Dispatcher is documented in
     <xref linkend="chapter.channel-dispatcher"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.connection-manager">
    <title>Connection Manager</title>
    <para>
     Connection managers are simply factories for connections.
     In general, there is little need for a client to interact much with
     the <interfacename>ConnectionManager</interfacename> interface. Most of
     the work in obtaining and managing connections should be done via
     the Account Manager.
    </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>
     More about Connection Managers is given in
     <xref linkend="sect.connection.connection-manager"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.client">
    <title>Client</title>
    <para>
     A Client is the name for a program that is registered with the Channel
     Dispatcher to do something with Telepathy Channels. There are three
     types of Clients: Observers, Approvers and Handlers. Most people
     reading this manual will be developing a Telepathy Client.
    </para>
    <para>
     More on Clients is available in
     <xref linkend="sect.channel-dispatcher.clients"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.connection">
    <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
     (<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>

    <para>
     Setting up and using connections is documented in
     <xref linkend="chapter.connection"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.channel">
    <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 of channels is presented in
     <xref linkend="chapter.channel"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.handle">
    <title>Handle</title>
    <para>
     Handles are used to represent various kinds of protocol resources
     (e.g. contacts, chatrooms, contact lists, etc.). Each handle has an
     associated string identifier. Handles are used to avoid
     normalisation problems in string identifiers.
    </para>

    <para>
     The use of handles is documented in <xref linkend="sect.basics.handles"/>.
    </para>
   </sect2>

   <sect2 id="sect.basics.terminology.interface">
    <title>Interface</title>
    <para>
     A D-Bus Interface.
    </para>
    <para>
     Telepathy makes extensive use of D-Bus interfaces. Telepathy uses
     interfaces both to indicate an object's type and its capabilities so
     it is not uncommon for an object to implement several Telepathy
     D-Bus interfaces. For instance, an object might implement
     <interfacename>org.freedesktop.Telepathy.Channel</interfacename>,
     <interfacename>org.freedesktop.Telepathy.Channel.Type.Text</interfacename>,
     <interfacename>org.freedesktop.Telepathy.Channel.Interface.Messages</interfacename>,
     <interfacename>org.freedesktop.Telepathy.Channel.Interface.Group</interfacename>
     and
     <interfacename>org.freedesktop.Telepathy.Channel.Interface.Password</interfacename>,
     which would indicate the object is a password-protected multi-user chat
     (MUC) channel.
    </para>
    <para>
     The <property>Interfaces</property> property says what interfaces a
     given object implements.
    </para>
    <para>
     Because an object can implement so many interfaces, Telepathy API
     bindings do not require you to specify an interface when requesting a
     proxy object. Instead this is done when making a method call or
     connecting a signal. Telepathy API bindings provide named constants for the
     available interfaces.
    </para>
   </sect2>
  </sect1>

  <sect1 id="sect.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="sect.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
	     &quot;well-known&quot; 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 &quot;org.freedesktop.foo.Foo&quot;.
	   </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
	     &quot;/org/freedesktop/foo/jack&quot;
	     (<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
	   &quot;org.freedesktop.foo.Jack&quot;
	   (<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 &quot;Fetch&quot; 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 &quot;Broken&quot; 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>

    <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
	&quot;blocking&quot; API
	(<function>dbus_do_something_and_block</function>) that implements a
	&quot;pseudo-blocking&quot; 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
	 &quot;UnknownMethod&quot; 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
	(including 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 &mdash; 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, sharing 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>
    
    <sect2 id="sect.basics.dbus.naming">
     <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>
    </sect2>

    <sect2 id="sect.basics.dbus.introspecting">
     <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>
    </sect2>

    <sect2 id="sect.basics.dbus.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>
   </sect1>

   <sect1 id="sect.basics.language-bindings">
    <title>Language Bindings</title>
    <para>
     As mentioned in <xref linkend="sect.basics.dbus"/>, 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
     easier. For instance,
     <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20GLib">telepathy-glib</ulink>
     provides an API that aims to be more familiar to users of Glib and GTK+.
     Likewise,
     <ulink url="http://telepathy.freedesktop.org/wiki/TelepathyQt">Telepathy-Qt</ulink>
     provides a Qt API for Telepathy and
     <ulink url="http://telepathy.freedesktop.org/wiki/Telepathy%20Python">Telepathy-Python</ulink> for Python.
    </para>

    <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="sect.basics.dbus.language-bindings.python">
      <title>telepathy-python</title>

      <para>
       <application>telepathy-python</application> builds on top of the
       standard <literal>dbus</literal> module for Python.
       The <literal>telepathy</literal> module provides some convenience
       classes, as well as enumerations and interface names.
       If you're planning on using the GLib mainloop you'll also
       need the <literal>dbus.mainloop.glib</literal> module.
      </para>

      <para>
       The <literal>telepathy.client</literal> provides the client D-Bus
       proxy objects. The <literal>telepathy.interfaces</literal> provides
       the names of Telepathy interfaces (e.g.
       <literal>CONNECTION_MANAGER</literal>,
       <literal>CONNECTION_INTERFACE_REQUESTS</literal>,
       <literal>CHANNEL_TYPE_CONTACT_LIST</literal>, etc.). The
       <literal>telepathy.constants</literal> module provides named
       constants in the Telepathy spec (e.g.
       <literal>CONNECTION_STATUS_CONNECTED</literal>,
       <literal>HANDLE_TYPE_GROUP</literal>).
      </para>

      <para>
       <xref linkend="ex.basics.dbus.language-bindings.python.mainloop"/>
       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="ex.basics.dbus.language-bindings.python.mainloop"
               file="python_simple_presence/example.py">
       <title>Setting Up The Mainloop</title>
      </example>

      <sect3 id="sect.basics.dbus.language-bindings.python.proxies">
       <title>Proxy Objects</title>
       <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. In <application>telepathy-python</application>
	they are provided in the <literal>telepathy.client</literal> module.
       </para>

       <para>
        The proxy objects you will use are <classname>Connection</classname>
	and <classname>Channel</classname>.
       </para>

       <example id="ex.basics.dbus.language-bindings.python.proxies">
        <title>Connection and Channel Proxy Objects</title>
	<programlisting language="python">
<![CDATA[connection = telepathy.client.Connection(bus_name, object_path)

channel = telepathy.client.Channel(connection.service_name, object_path)]]></programlisting>
       </example>

       <!-- FIXME: ready_handler -->

       <para>
        <application>telepathy-python</application> proxies differ from
	regular Python <literal>dbus</literal> proxies in that they aren't
	created with a given D-Bus interface. Instead the interface is
	specified when calling a method or connecting a signal similar to
	how you might look up a key in a dictionary (see
	<xref linkend="ex.basics.dbus.language-bindings.python.methods.call"/>
	below). Interface names are available from the module
	<literal>telepathy.interfaces</literal>.
       </para>
      </sect3>

      <sect3 id="sect.basics.dbus.language-bindings.python.methods">
       <title>Calling Methods</title>
       <para>
        D-Bus method calls on a proxy object look like any other Python
	method call. Python's D-Bus support can automatically convert native
	Python types into D-Bus types and back, so no complicated type
	marshalling is required.
	<xref linkend="ex.basics.dbus.language-bindings.python.methods.call"/>
	shows calling the <methodname>RequestConnection</methodname> method
	(more on this in
	<xref linkend="sect.connection.obtaining.connection-manager"/>).
       </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. The parameters to a callback are specified by the D-Bus
	return type, e.g.
	<xref linkend="ex.basics.dbus.language-bindings.python.methods.cb"/>.
       </para>

       <example id="ex.basics.dbus.language-bindings.python.methods.call"
                file="python_simple_presence/example.py">
        <title>Calling a Method</title>
       </example>
       
       <example id="ex.basics.dbus.language-bindings.python.methods.cb"
                file="python_simple_presence/example.py">
        <title>Method Callback</title>
       </example>
      </sect3>

      <sect3 id="sect.basics.dbus.language-bindings.python.props">
       <title>Using Properties</title>
       <para>
        D-Bus properties are available via the
	<ulink url="&url_dbus_spec_base;standard-interfaces-properties"><interfacename>org.freedesktop.DBus.Properties</interfacename></ulink>
        interface, which provides the
        <methodname>Get</methodname>, <methodname>Set</methodname> and
        <methodname>GetAll</methodname> methods
	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="ex.basics.dbus.language-bindings.python.props"/>
	is therefore very similar to
	<xref linkend="ex.basics.dbus.language-bindings.python.methods.call"/>
	presented above.
       </para>

       <example id="ex.basics.dbus.language-bindings.python.props"
                file="python_simple_presence/example.py">
        <title>Accessing D-Bus Properties Using Methods</title>
       </example>
      </sect3>

      <sect3 id="sect.basics.dbus.language-bindings.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="ex.basics.dbus.language-bindings.python.signals"/>
	connects to the <methodname>NewChannels</methodname> signal in
	Telepathy.
       </para>

       <example id="ex.basics.dbus.language-bindings.python.signals"
	        file="python_simple_presence/example.py">
	<title>Connecting a Signal</title>
       </example>	
      </sect3>

    </sect2>
  
    <sect2 id="sect.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="sect.basics.language-bindings.telepathy-glib.tpproxy">
       <title>TpProxy Objects</title>

       <para>
        <application>telepathy-glib</application> uses what it calls
	<classname>TpProxy</classname> objects to make D-Bus method calls.
	<classname>TpProxy</classname> objects are
	<classname>GObject</classname>s that expose common Telepathy features
	(like the interfaces they implement) as GObject properties and struct
	members.
       </para>

       <para>
        There are several <classname>TpProxy</classname> subclasses that you
	will use when programming with
	<application>telepathy-glib</application>:
	<classname>TpConnectionManager</classname>,
	<classname>TpConnection</classname> and
	<classname>TpChannel</classname>.
       </para>

       <!-- FIXME: mention tp_proxy_has_interface_by_id() somewhere -->
        
        <para>
	 Some proxy objects, such as
	 <classname>TpConnection</classname> and
	 <classname>TpChannel</classname>,
	 make additional D-Bus method calls to acquire additional information
	 (e.g. available interfaces) to populate the properties and structures
	 of the object. When they have received this information
	 they are considered &quot;ready&quot;.
	 Each proxy object provides a method to register a callback for when
	 the object is ready, e.g.
	 <function>tp_connection_call_when_ready</function>
	 for a <classname>TpConnection</classname>, or
	 <function>tp_channel_call_when_ready</function>
	 for a <classname>TpChannel</classname>. See
         <xref linkend="ex.basics.language-bindings.telepathy-glib.ready"/>.
	</para>

        <example id="ex.basics.language-bindings.telepathy-glib.ready"
                 file="glib_get_roster/example.c">
         <title>Readiness Callback</title>
        </example>

	<tip>
	 <title>TpConnection Readiness</title>
	 <para>
	  A <classname>TpConnection</classname> is not considered
	  &quot;ready&quot; until it has been connected (you cannot retrieve
	  all of the available interfaces until connection is complete).
	 </para>
	 <para>
	  See <xref linkend="sect.connection.obtaining"/> for more details
	  on setting up a Connection.
	 </para>
	</tip>
      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.generated">
        <title>Method Calls</title>
        <para>
	 <application>telepathy-glib</application> provides the Telepathy
	 D-Bus API method calls as generated functions. The generated
	 functions have the following prefixes:
	</para>

        <variablelist>

          <varlistentry>
            <term>tp_cli_</term> 
            <listitem><para>
	      These functions are used for client applications. For instance,
	      <function>tp_cli_connection_call_connect</function>.
	    </para></listitem>
          </varlistentry>

          <varlistentry>
            <term>tp_svc_</term> 
            <listitem><para>
	      These functions are used for service implementations, such as
	      connection managers. For instance,
	      <function>tp_svc_connection_implement_connect</function>.
	    </para></listitem>
          </varlistentry>

        </variablelist>

	<important>
         <title>Asynchronous Calls</title>
         <para>
	  For each Telepathy D-Bus method, telepathy-glib generally provides
	  both a &quot;run&quot; and a &quot;call&quot; function.
	  For instance, <function>tp_cli_connection_run_connect</function>
	  and <function>tp_cli_connection_call_connect</function>.
	 </para>
	 <para>
	  The &quot;run&quot; functions are synchronous, and blocks until the
	  D-Bus service has returned the value. They have been deprecated and
	  should <emphasis>never</emphasis> be used in Telepathy programs (see
	  <xref linkend="warning.dbus.sync"/>). Instead use the &quot;call&quot;
	  functions, which are asynchronous; immediately returning and later
	  providing the result to a callback function.
	 </para>
        </important>
	
	<para>
	 The generated client functions have the following general signature:
	</para>
	<itemizedlist>
	 <listitem><para>
	  <classname>TpProxy</classname> object;
	 </para></listitem>
	 <listitem><para>
	  Timeout in milliseconds (<literal>-1</literal> sets the default);
	 </para></listitem>
	 <listitem><para>
	  Method arguments (see
	  <xref linkend="sect.basics.language-bindings.telepathy-glib.types"/>);
	 </para></listitem>
	 <listitem><para>
	  Callback function;
	 </para></listitem>
	 <listitem><para>
	  Optional user data for the callback;
	 </para></listitem>
	 <listitem><para>
	  Optional destroy function for the user data;
	 </para></listitem>
	 <listitem><para>
	  An optional object to weakly reference, if this object is destroyed
	  the call will be cancelled.
	 </para></listitem>
        </itemizedlist>	
        
	<para>
	 Each method call has its own unique callback. The general type
	 signature for a method callback is:
	</para>
	<itemizedlist>
	 <listitem><para>
	  <classname>TpProxy</classname> object;
	 </para></listitem>
	 <listitem><para>
	  Return arguments (see
	  <xref linkend="sect.basics.language-bindings.telepathy-glib.types"/>);
	 </para></listitem>
	 <listitem><para>
	  A possible error condition;
	 </para></listitem>
	 <listitem><para>
	  The supplied user data;
	 </para></listitem>
	 <listitem><para>
	  The supplied weakly-referenced object.
	 </para></listitem>
        </itemizedlist>

	<para>
	 <xref linkend="ex.basics.language-bindings.telepathy-glib.method-call"/>
	 shows a the construction of a <application>telepathy-glib</application>
	 method call, in this case to <function>RequestConnection</function>.
	</para>

	<example id="ex.basics.language-bindings.telepathy-glib.method-call">
	 <title>Example Method Call and Associated Callback</title>
	 <programlisting language="c">
<![CDATA[/* method call for ConnectionManager.RequestConnection */
tp_cli_connection_manager_call_request_connection (
	cm,			/* TpProxy */
	-1,			/* timeout */
	"jabber",		/* method arguments */
	parameters,
	request_connection_cb,	/* callback */
	NULL,			/* user data */
	NULL,			/* destroy notify */
	NULL);			/* weak object */

/* callback for ConnectionManager.RequestConnection */
static void
request_connection_cb (TpConnectionManager      *cm,		/* TpProxy */
                       const char               *bus_name,	/* return args */
		       const char               *object_path,
		       const GError             *in_error,	/* error condition */
		       gpointer                  user_data,	/* user data */
		       GObject                  *weak_object)	/* weak object */]]></programlisting>
        </example>

      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.dbus-properties">
       <title>D-Bus Properties</title>

       <para>
        <application>telepathy-glib</application> provides a convenience API
        for accessing the D-Bus properties of any
        <classname>TpProxy</classname> proxy:
        <function>tp_cli_dbus_properties_call_get</function>,
        <function>tp_cli_dbus_properties_call_get_all</function> and
        <function>tp_cli_dbus_properties_call_set</function>.
        These functions work similar to all other
        <classname>TpProxy</classname>
        <link linkend="sect.basics.language-bindings.telepathy-glib.generated">method calls</link>.
       </para>

       <para>
        For <function>tp_cli_dbus_properties_call_get</function>, the return
        argument is a <classname>GValue</classname> of the type specified by
        the property (see
        <xref linkend="sect.basics.language-bindings.telepathy-glib.types"/>).
        For <function>tp_cli_dbus_properties_call_get_all</function> the return
        value is an
        <link linkend="sect.basics.language-bindings.telepathy-glib.maps">a{sv}
        map</link>.
        <xref linkend="ex.basics.language-bindings.telepathy-glib.dbus-properties"/>
        demonstates how to access a D-Bus property.
       </para>

       <example id="ex.basics.language-bindings.telepathy-glib.dbus-properties">
        <title>Getting a D-Bus Property with telepathy-glib</title>
        <programlisting language="c">
<![CDATA[tp_cli_dbus_properties_call_get (conn, -1,
        TP_IFACE_CONNECTION_INTERFACE_REQUESTS,
        "Channels",
        get_channels_cb,
        NULL, NULL, NULL);


static void
get_channels_cb (TpProxy        *proxy,
                 const GValue   *value,
                 const GError   *in_error,
                 gpointer        user_data,
                 GObject        *weak_obj)
{
        /* handle error */

        GPtrArray *channels = g_value_get_boxed (value);

        /* ... */
}]]></programlisting>
       </example>

      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.types">
       <title>Types</title>

       <para>
        The handling of variant types in
        <application>telepathy-glib</application> is done using GLib's built-in
        <classname>GValue</classname> type system.
       </para>

       <para>
        <classname>GType</classname> types for simple D-Bus types
	are given in
	<xref linkend="table.basics.language-bindings.telepathy-glib.types"/>.
        Telepathy's complex types are all mapped to generated boxed GTypes
        (see
        <ulink url="&url_telepathy_glib_base;telepathy-glib-gtypes.html">the
        telepathy-glib manual</ulink>). For example
        <type>Channel_Details</type> maps to the GType
        <type>TP_STRUCT_TYPE_CHANNEL_DETAILS</type>.
       </para>

       <para>
        To check that a given <classname>GValue</classname> is of the
        correct type, use the macro <function>G_VALUE_HOLDS</function>. To
        retrieve the type of a <classname>GValue</classname> use the macro
        <function>G_VALUE_TYPE</function>.
       </para>

       <table id="table.basics.language-bindings.telepathy-glib.types">
        <title>D-Bus Simple GTypes</title>
	<tgroup cols="6">
	 <colspec colname="sdtype"/>
	 <colspec colname="sgtype"/>
	 <colspec colname="sctype"/>
	 <colspec colname="adtype"/>
	 <colspec colname="agtype"/>
	 <colspec colname="actype"/>
	 <thead>
	  <row>
	   <entry namest="sdtype" nameend="sctype">Single Values</entry>
	   <entry namest="adtype" nameend="actype">Lists/Arrays</entry>
	  </row>
	  <row>
	   <entry>D-Bus Type</entry>
	   <entry>GType</entry>
	   <entry>C type</entry>
	   <entry>D-Bus Type</entry>
	   <entry>GType</entry>
	   <entry>C type</entry>
	  </row>
	 </thead>
	 <tbody>
	  <row>
	   <entry><literal>o</literal></entry>
	   <entry><type>DBUS_TYPE_G_OBJECT_PATH</type></entry>
	   <entry>String (<type>char *</type>)</entry>
	   <entry><literal>ao</literal></entry>
	   <entry><type>TP_ARRAY_TYPE_OBJECT_PATH_LIST</type></entry>
	   <entry>
	    <classname>GPtrArray</classname> of Strings
	    (<type>char *</type>)
	   </entry>
	  </row>
	  <row>
	   <entry><literal>y</literal></entry>
	   <entry><type>G_TYPE_UCHAR</type></entry>
	   <entry><type>guchar</type></entry>
	   <entry><literal>ay</literal></entry>
	   <entry><type>DBUS_TYPE_G_UCHAR_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>guchar</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>u</literal></entry>
	   <entry><type>G_TYPE_UINT</type></entry>
	   <entry><type>guint</type></entry>
	   <entry><literal>au</literal></entry>
	   <entry><type>DBUS_TYPE_G_UINT_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>guint</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>i</literal></entry>
	   <entry><type>G_TYPE_INT</type></entry>
	   <entry><type>int</type></entry>
	   <entry><literal>ai</literal></entry>
	   <entry><type>DBUS_TYPE_G_INT_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>int</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>t</literal></entry>
	   <entry><type>G_TYPE_UINT64</type></entry>
	   <entry><type>guint64</type></entry>
	   <entry><literal>at</literal></entry>
	   <entry><type>DBUS_TYPE_G_UINT64_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>guint64</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>x</literal></entry>
	   <entry><type>G_TYPE_INT64</type></entry>
	   <entry><type>gint64</type></entry>
	   <entry><literal>ax</literal></entry>
	   <entry><type>DBUS_TYPE_G_INT64_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>gint64</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>d</literal></entry>
	   <entry><type>G_TYPE_DOUBLE</type></entry>
	   <entry><type>double</type></entry>
	   <entry><literal>ad</literal></entry>
	   <entry><type>DBUS_TYPE_G_DOUBLE_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>double</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>b</literal></entry>
	   <entry><type>G_TYPE_BOOLEAN</type></entry>
	   <entry><type>gboolean</type></entry>
	   <entry><literal>ab</literal></entry>
	   <entry><type>DBUS_TYPE_G_BOOLEAN_ARRAY</type></entry>
	   <entry>
	    <classname>GArray</classname> of <type>gboolean</type>
	   </entry>
	  </row>
	  <row>
	   <entry><literal>s</literal></entry>
	   <entry><type>G_TYPE_STRING</type></entry>
	   <entry><type>char *</type></entry>
	   <entry><literal>as</literal></entry>
	   <entry><type>G_TYPE_STRV</type></entry>
	   <entry><type>char **</type></entry>
	  </row>
	 </tbody>
	</tgroup>
       </table>


       <para>
        Decoding the contents of the GValue can be done either from the
        <ulink url="&url_telepathy_glib_base;telepathy-glib-gtypes.html">manual</ulink>
        or from the D-Bus type signature. For example the property
        <property>Requests.Channels</property> is of the type
        <type>Channel_Details_List</type> (<literal>a(oa{sv})</literal>). From
        the manual, this is a <classname>GPtrArray</classname> of
        <type>TP_STRUCT_TYPE_CHANNEL_DETAILS</type>, which in turn is a
        <classname>GValueArray</classname> containing a object path and an
        <link linkend="sect.basics.language-bindings.telepathy-glib.maps">a{sv}
        map</link> (hashtable). The complete unpacking is shown in
        <xref linkend="ex.basics.language-bindings.telepathy-glib.types"/>.
       </para>

       <para>
        More generally, the structure of the type can be determined from its
        D-Bus type signature by following several rules:
       </para>
       <itemizedlist>
        <listitem><para>
         Arrays of complex types (e.g. <literal>a(suv)</literal>) and of object
         paths (<literal>ao</literal>) are stored as a
         <classname>GPtrArray</classname>.
        </para></listitem>
        <listitem><para>
         Arrays of strings (<literal>as</literal>), which are stored as a
         <literal>NULL</literal>-terminated <literal>gchar **</literal>.
        </para></listitem>
        <listitem><para>
         Arrays of all other simple types (e.g. <literal>au</literal>) are
         stored as a <classname>GArray</classname>.
        </para></listitem>
        <listitem><para>
         Structures (e.g. <literal>(oa{sv})</literal>) are stored as a
         <classname>GValueArray</classname> where each member of the
         structure is a GValue in the array in the respective order
	 (see <xref linkend="sect.basics.language-bindings.telepathy-glib.structs"/>).
        </para></listitem>
        <listitem><para>
         Maps (e.g. <literal>a{sv}</literal>) are stored as a
         <classname>GHashTable</classname>.
        </para></listitem>
        <listitem><para>
         Object paths (<literal>o</literal>) are stored as a string (e.g.
         when used in a <literal>a{uo}</literal> map), or in a boxed
         <classname>GValue</classname> of type
         <type>DBUS_TYPE_G_OBJECT_PATH</type> (when stored in a struct or
         variant type).
        </para></listitem>
        <listitem><para>
         Variant types (<literal>v</literal>) are stored as
         <classname>GValue</classname>s of type specified by the spec
         (see <xref linkend="sect.basics.language-bindings.telepathy-glib.variant"/>).
        </para></listitem>
       </itemizedlist>

       <para>
        For example, the D-Bus type <literal>a{sa(usuu)}</literal> is a
        <classname>GHashTable</classname> of string keys (<type>char *</type>)
        to <classname>GPtrArray</classname>s containing
        <classname>GValueArray</classname>s. This is shown graphically in
        <xref linkend="fig.basics.language-bindings.telepathy-glib.types.unpacked"/>.
       </para>
    
       <figure id="fig.basics.language-bindings.telepathy-glib.types.unpacked">
        <title>Expanded Type for a{sa(usuu)}</title>
        <mediaobject><imageobject>
         <imagedata fileref="figures/telepathy-glib-type-unpacked.png"
                    format="PNG" />
        </imageobject></mediaobject>
       </figure>

       <tip>
        <title>G_VALUE_TYPE_NAME()</title>
        <para>
         The macro <function>G_VALUE_TYPE_NAME</function> can also be useful
         for unpacking Telepathy types.
        </para>
        <para>
         For example the listed type name of
         <type>TP_STRUCT_TYPE_CHANNEL_DETAILS_LIST</type> is given as
         <literal>GPtrArray_GValueArray_DBusGObjectPath+GHashTable_gchararray+GValue___</literal>.
        </para>
       </tip>

      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.maps">
       <title>a{sv} Maps</title>

       <para>
        Telepathy makes extensive use of a{sv} maps (i.e. a map of string
	keys to variant types) for passing and returning properties from
	calls (this allows for something similar to polymorphic functions
	via D-Bus). Unforunately, C and GLib do not offer many functions for
	convieniently handling this type of map.
       </para>

       <para>
        To make handling these maps easier, Telepathy provides a number of
	functions, <function>tp_asv_*</function> for manipulating these
	maps.
       </para>

       <para>
        Telepathy uses a standard <classname>GHashTable</classname> that is
	set up to use string keys, and GSlice-allocated
	<classname>GValue</classname> values. The easiest way to create a
	new map with <function>tp_asv_new</function>. This function will
	automatically destroy values when they are overwritten, removed or
	the hash table is destroyed. The standard GHashTable functions
	<function>g_hash_table_destroy</function>,
	<function>g_hash_table_ref</function>, etc. can all be used with
	this map.
       </para>

       <para>
        <function>tp_asv_new</function> can optionally take a
	NULL-terminated list of initial values as (key, type, value) tuples,
	as shown in
	<xref linkend="ex.basics.language-bindings.telepathy-glib.tp_asv_new"/>.
       </para>

       <example id="ex.basics.language-bindings.telepathy-glib.tp_asv_new">
        <title>Creating an a{sv} map with tp_asv_new()</title>
	<!-- FIXME: pull from source example? -->
	<programlisting language="c">
<![CDATA[GHashTable *parameters = tp_asv_new (
	"account", G_TYPE_STRING, "bob@mcbadgers.com"
	"password", G_TYPE_STRING, password,
	NULL);]]></programlisting>
       </example>

       <para>
        The map can be further edited or appended to with the
	<function>tp_asv_set_*</function> functions (e.g.
	<function>tp_asv_set_string</function>).
       </para>

       <para>
        To read values from the map, use the
	<function>tp_asv_get_*</function> functions (e.g.
	<function>tp_asv_get_string</function>). These functions return the
	value on success, or NULL/False/0 if the key is unavailable.
	Some accessor functions
	(e.g. <function>tp_asv_get_boolean</function>,
	<function>tp_asv_get_double</function>,
	<function>tp_asv_get_int32</function>, etc.) take an optional
	parameter <parameter>*valid</parameter>, which can be used to
	determine, without ambiguity, if the key exists in the map.
       </para>

       <tip>
        <title>tp_asv_dump()</title>
	<para>
	 The function <function>tp_asv_dump</function> can be used to dump
	 a string representation of the map out to the debugging console.
	</para>
       </tip>

      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.structs">
      	<title>Structs</title>

	<para>
	  Structs (e.g. <literal>ussu</literal>) are stored as a
	  <classname>GValueArray</classname>.
	  To make these easier to create use the utility function
	  <function>tp_value_array_build</function>. This function requires
	  a number of struct entries, followed by (GType, value) pairs, and
	  terminated with the type <type>G_TYPE_INVALID</type>, as shown in
	  <xref linkend="ex.basics.language-bindings.telepathy-glib.tp_value_array_build"/>.
	</para>

        <example id="ex.basics.language-bindings.telepathy-glib.tp_value_array_build">
         <title>Creating an (ussu) struct with tp_value_array_build()</title>
         <!-- FIXME: pull from source example? -->
         <programlisting language="c">
<![CDATA[GValueArray *entry = tp_value_array_build (4,
         G_TYPE_UINT, 12,
         G_TYPE_STRING, "subject",
	 G_TYPE_STRING, "Building a GValueArray",
	 G_TYPE_UINT, 0,
	 G_TYPE_INVALID);]]></programlisting>
        </example>

	<para>
	  <function>tp_value_array_build</function> takes copies/references
	  of all of the supplied data, which can be freed immediately. These
	  copies/references are released when the
	  <classname>GValueArray</classname>
	  is freed.
	</para>

	<para>
	  Structs can be unpacked using the utility function
	  <function>tp_value_array_unpack</function>. This function takes a
	  number of values to unpack (may be less than the number of values
	  in the array) followed by that number of pointers to appropriate
	  variables (NULL may be passed to skip a value you're not interested
	  in). <xref linkend="ex.basics.language-bindings.telepathy-glib.types"/>
	  shows unpacking the object path, and properties for an array of
	  channels.
	</para>

	<para>
	  Values are not copied out of the array, and these pointers will
	  become invalid when the array is freed. If you want to keep a copy
	  of a value you should copy/reference it explicitly.
	</para>

       <example id="ex.basics.language-bindings.telepathy-glib.types">
        <title>Decoding a GValue containing a Channel_Details_List</title>
        <programlisting language="c">
<![CDATA[g_return_if_fail (G_VALUE_HOLDS (value, TP_ARRAY_TYPE_CHANNEL_DETAILS_LIST));

GPtrArray *channels = g_value_get_boxed (value);

int i;
for (i = 0; i < channels->len; i++)
{
        GValueArray *channel = g_ptr_array_index (channels, i);

        char *object_path;
        GHashTable *map;

	tp_value_unpack (channel, 2,
		&object_path,
		&map);

        const char *type = tp_asv_get_string (map, TP_IFACE_CHANNEL ".ChannelType");

        g_print ("Path: %s\n", object_path);
        g_print ("Type: %s\n", type);
}]]></programlisting>
       </example>

       <para>
         Individual values can be retrieved from a structure using
	 <function>g_value_array_get_nth</function> plus the appropriate
	 <function>g_value_get_...</function> function for the returned
	 <classname>GValue</classname>.
	 <xref linkend="ex.basics.language-bindings.telepathy-glib.unpacking-us"/>
	 shows how this is done. Similar to using
	 <function>tp_value_array_unpack</function>, this value is not
	 copied or referenced, however GLib provides several
	 <function>g_value_dup_...</function> functions that do make copies.
       </para>
       <example id="ex.basics.language-bindings.telepathy-glib.unpacking-us">
        <title>Unpacking oa{sv}</title>
        <programlisting language="c">
<![CDATA[GValueArray *channel = ...; /* contains a struct of type (oa{sv}) */

char *object_path;
GHashTable *map;

object_path = g_value_get_boxed (g_value_array_get_nth (channel, 0));
map = g_value_get_boxed (g_value_array_get_nth (channel, 1));]]></programlisting>
       </example>


      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.variant">
       <title>Variant Types</title>
       <para>
        Variant types are stored as a <classname>GValue</classname> of type
        given by the specification. For example,
        <xref linkend="ex.basics.language-bindings.telepathy-glib.variant-unpack"/>
        shows how to unpack the type <literal>a(uv)</literal>.
       </para>

       <example id="ex.basics.language-bindings.telepathy-glib.variant-unpack">
        <title>Unpacking Type a(uv)</title>
	 <programlisting language="c">
<![CDATA[
int i;
for (i = 0; i < properties->len; i++)
{
        GValueArray *property = g_ptr_array_index (properties, i);
        /* the id is a GValue<UINT>
         * the variant is a GValue<GValue<??> */
        guint id = g_value_get_uint (g_value_array_get_nth (property, 0));
        GValue *value = g_value_get_boxed (g_value_array_get_nth (property, 1));

        /* get a string representation of value */
        char *str = g_strdup_value_contents (value);
        g_print ("Property %i: %s\n", id, str);
        g_free (str);
}]]></programlisting>
        </example>

        <example id="ex.basics.language-bindings.telepathy-glib.variant-pack">
         <title>Packing Type a(uv)</title>
         <programlisting language="c">
<![CDATA[GPtrArray *array = g_ptr_array_new_with_free_func ((GDestroyNotify) g_value_array_free);

/* pack structs into array */
GValue value = { 0, };

g_value_init (&value, G_TYPE_STRING);
g_value_set_static_string (&value, "Test Subject");

g_ptr_array_add (array, tp_value_array_build (2,
	G_TYPE_UINT, id,
	G_TYPE_VALUE, value,
	G_TYPE_INVALID);

g_value_unset (&value);

...

/* free array */
g_ptr_array_free (array, TRUE);]]></programlisting>
       </example>
      </sect3>

      <sect3 id="sect.basics.language-bindings.telepathy-glib.linking">
        <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
	 <application>pkg-config</application> utiltity like so:
	</para>

        <informalexample><programlisting language="sh">
pkg-config telepathy-glib --cflags
pkg-config telepathy-glib --libs</programlisting>
        </informalexample>

        <para>
	 However, if you are using the &quot;autotools&quot;
	 (automake, autoconf, etc) build system, you will find it more
	 convenient to use the <function>PKG_CHECK_MODULES</function> macro
	 in your <filename>configure.ac</filename> file.
       </para>

       <informalexample><programlisting>
PKG_CHECK_MODULES(EXAMPLE, telepathy-glib)
AC_SUBST(EXAMPLE_CFLAGS)
AC_SUBST(EXAMPLE_LIBS)</programlisting>
        </informalexample>

        <para>
	 You should then use the generated _CFLAGS and _LIBS definitions in your Makefile.am files.
	</para>
      </sect3>

    </sect2>

  </sect1>

  <sect1 id="sect.basics.optional-interfaces">
    <title>Optional Interfaces</title>

    <para>
     Not all messaging protocols are the same. Different protocols may offer
     different messaging features, for example contact presence, avatars,
     geolocation, Voice-over-IP, etc. Sometimes a particular server
     implementation/version/instance won't have certain features enabled.
     Telepathy exposes the various available features for a connection as
     D-Bus interfaces.
    </para>

    <para>
     The same might apply to channels. A text channel may be a one-to-one
     chat, or it may be a multi-user chat. The interfaces present on the
     channel tell us what its capabilities are.
    </para>

    <para>
     Telepathy objects can be assumed to implement their base interface
     (e.g. <interfacename>Connection</interfacename>,
     <interfacename>Channel</interfacename>).
     The additional interfaces available on a Telepathy object are retreivable
     either via the
     <property>Interfaces</property> property (preferred) or the
     older <methodname>GetInterfaces</methodname> method call (e.g. for
     <interfacename>Connection</interfacename>, deprecated).
    </para>
    
    <note>
     <para>
      Note that the <property>Interfaces</property> property (or the
      <methodname>GetInterfaces</methodname> method) should be used instead
      of the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><interfacename>Introspectable</interfacename></ulink>
      interface.
     </para>

     <para>
      The interfaces for a connection/channel depend on the
      capabilities/type of the object.
      In general, most D-Bus language bindings make it very difficult to
      implement D-Bus objects with a dynamic set of interfaces, thus making
      it difficult for a connection manager to export a dynamic set of
      interfaces via D-Bus introspection.
     </para>

     <para>
      If you use a D-Bus introspection tool (e.g.
      <application>D-Feet</application> to look at a Telepathy connection
      object, you'll find it announces support for all interfaces, even the
      ones it doesn't support. If you query the object's
      <property>Interfaces</property> property, you'll see which interfaces
      really are supported.
     </para>
    </note>

    <para>
     When using telepathy-glib, you can simply call the
     <function>tp_proxy_has_interface</function> function for
     <classname>TpConnectionManager</classname>,
     <classname>TpConnection</classname>, or
     <classname>TpChannel</classname> objects.
    </para>

    <para>
     The Telepathy specification is still being improved and sometimes the
     specification provides two ways to achieve the same goal. Although one
     of the methods/interfaces will be deprecated, it's possible that some
     older connection managers do not yet implement the latest
     specification. In this case, it could be possible for your client to fall
     back to the older method. In general, deprecated interfaces and methods
     are not documented in this manual.
    </para>
    
    <!-- TODO: Add dbus-glib and Python examples of checking-for and using an Interface. -->
  </sect1>

  <sect1 id="sect.basics.handles">
    <title>Handles</title>

    <para>
     Handles in Telepathy are used to represent various protocol resources,
     for example contacts, chatrooms, contact lists and user-defined groups.
     A Handle is simply a numeric id allocated by the connection. Each
     handle has a type (<type>Handle_Type</type>) that defines the sort of
     handle it is. The same numeric handle id can be given for different handle
     types and different connections.
     The tuple of (connection, handle type, handle) is guarenteed unique.
    </para>

    <para>
     Every handle is associated with a string identifier, e.g. the contact
     <literal>bob@example.com</literal>. The strings are normalised per the
     rules of the protocol. For example, if a protocol considers contact
     identifiers to be case insensitive the strings "bob@example.com" and
     "Bob@Example.com" would resolve to the same handle. These handles can
     be tested for integer equality to determine this is in fact the same
     identifier.
    </para>

    <warning>
     <title>Never Compare String Identifiers in the Client</title>
     <para>
      Identifier normalisation rules can be complex and subtle.
      A Telepathy client should never attempt to do any normalisation of
      string identifiers. Nor should it compare string identifiers for
      equality.
     </para>
     <para>
      Instead handles should be requested for the identifiers (via
      <methodname>RequestHandles</methodname>) and the handles compared for
      integer equality. If the normalised string is desired (e.g. for
      display), this can be accessed via the
      <methodname>InspectHandles</methodname> method call.
     </para>
    </warning>

    <para>
     The handle id <literal>0</literal> is never a valid handle for an
     identifier, but may be used some places in the API to indicate a
     special condition. (<type>Handle_Type_None</type>, 0) is referred to as
     the anonymous handle, and also has special meaning.
    </para>

    <sect2 id="sect.basics.handle.lifecycle">
      <title>Handle Lifecycle</title>

      <para>
       The lifetime of handles is managed by each connection based on the
       currently open channels. For example, each contact in a channel has
       an associated handle. If no client has a hold on a handle, and that
       contact leaves all channels, the handle will cease to be valid.
      </para>

      <para>
       Telepathy clients can keep handles around longer using the
       <methodname>HoldHandles</methodname> method. Unlike with reference
       counting, the <methodname>HoldHandles</methodname> method is idempotent,
       meaning that calling it multiple times is equivalent to calling it once.
       Instead of calling <methodname>HoldHandles</methodname>, clients can
       instead pass <literal>True</literal> to the <parameter>Hold</parameter>
       parameter of <methodname>Contacts.GetContactAttributes</methodname>.
      </para>

      <para>
       A handle can be requested directly by its identifier using the
       <methodname>RequestHandles</methodname> method. This method is
       most commonly used when the user directly provides the identifier of
       a resource (e.g. the name of a chatroom) to access. The handle
       returned by <methodname>RequestHandles</methodname> is already held.
      </para>

      <para>
       When a client is finished with a handle, it can be released with
       <methodname>ReleaseHandles</methodname>. This doesn't neccesarily
       mean the handle will instantly become invalid, it could still be
       referenced internally by the connection, but it could become invalid
       at any time.
      </para>

      <warning>
       <title>Handles are Not Referenced Counted</title>
       <para>
        The <methodname>HoldHandles</methodname> D-Bus method is idempotent.
        A single call to <methodname>ReleaseHandles</methodname>
        indicates that a client is no longer interested in a handle, no
        matter how many times <methodname>HoldHandles</methodname> or
        equivalent were called. If required, it is up to the client to
        implement some form of reference counting for handles.
       </para>
       <para>
        Some language bindings however, may provide reference counting.
       </para>
      </warning>

      <para>
       Method calls like <methodname>Group.GetAllMembers</methodname> return
       a list of handles, but do not hold any of the handles for the client.
       Thus, if a contact leaves the channel (e.g. goes offline), it is
       possible for the handle to become invalid in between the reply, and
       the next request using those handles. It is important that clients
       be aware of this possible race condition and handle it appropriately.
       For this reason, method calls like
       <methodname>GetContactAttributes</methodname> do not return the
       <errorname>InvalidHandle</errorname> error if one of the handles has
       already ceased to exist. Clients should listen to the appropriate
       signals (e.g. <methodname>Group.MembersChangedDetailed</methodname>) to
       determine if that handle has been made invalid in the intervening
       time.
      </para>

    </sect2>

    <sect2 id="sect.basics.handles.telepathy-glib">
     <title>Handles in telepathy-glib</title>

     <para>
      The use of <methodname>HoldHandles</methodname> and
      <methodname>ReleaseHandles</methodname> is less necessary when using
      telepathy-glib, because it automatically holds handles for the lifetime
      of its objects, e.g. <classname>TpContact</classname>. When the object
      is destroyed its handle will be dropped.
     </para>

     <para>
      Additionally, telepathy-glib wraps the
      <methodname>HoldHandles</methodname> and
      <methodname>ReleaseHandles</methodname> D-Bus methods with the
      <function>tp_connection_hold_handles</function>
      and <function>tp_connection_unref_handles</function>
      functions which reference-count the client-side handle
      &quot;hold&quot;.
      This requires you to match each call of
      <function>tp_connection_hold_handles</function> with a matching call
      to <function>tp_connection_unref_handles</function>, similar to other
      reference counted resources.
     </para>
    </sect2>

  </sect1>

  <sect1 id="sect.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>

  <sect1 id="sect.basics.tpproperties">
   <title>Telepathy Properties</title>

   <important>
    <para>
     Telepathy Properties should not be mistaken for D-Bus' own built in
     properties.
    </para>
   </important>

   <warning>
    <title>Candidate for Future Deprecation</title>
    <para>
     The Telepathy Properties interface is a little cumbersome to use and is
     a candidate to be replaced by something easier in the future.
    </para>
   </warning>

   <para>
    Telepathy Properties differ from built-in D-Bus properties
    in that their read/write status can change dynamically (unlike D-Bus
    properties, whose permissions are fixed by the specification). This is
    to reflect the dynamic nature of some properties based on the changing
    permissions of a connection or channel.
   </para>

   <para>
    For example, imagine an IRC room. Depending on the current access level
    of the user (i.e. is she/he an operator or moderator) and the
    permissions set on the channel, the user may or may not
    be permitted to change the channel subject at any given time. The
    permission flags of the property change to reflect this status.
   </para>

   <sect2 id="sect.basics.tpproperties.list">
    <title>Listing Properties</title>

    <para>
     Properties have fixed names in the Telepathy specification, but are
     referred to by ID number in the API. These ID numbers are not assigned
     to constant values, instead the method call
     <methodname>ListProperties</methodname> should be used. This returns
     back an array of structs containing the ID number, property name,
     D-Bus type signature and access flags.
    </para>
   </sect2>

   <sect2 id="sect.basics.tpproperties.flags">
    <title>Changing Permissions (Property Flags)</title>
    <para>
     The permissions of a property can change during the lifetime of a
     channel. For example, a user may not be able to set the channel's
     <property>subject</property> until she has been granted special
     privileges on the channel.
    </para>

    <para>
     A change in property permissions is heralded by the
     <methodname>PropertyFlagsChanged</methodname> signal. This signal
     provides an array of property IDs and each property's new list of
     flags.
    </para>

    <note>
     <title>Write-only Properties</title>
     <para>
      It is possible for a channel to have what appear to be write-only
      properties. This happens when there is no data to be read yet for a
      property. For instance, a newly created MUC channel may appear to have
      a write-only property for its <property>subject</property> property
      because there is not yet any data to be read for this property.
      Setting an initial subject will cause the property to change to a
      read-write property.
     </para>
    </note>
   </sect2>

   <sect2 id="sect.basics.tpproperties.get">
    <title>Getting Properties</title>

    <para>
     Accessing properties is done using the
     <methodname>GetProperties</methodname> method call. This method takes
     an array of integer properties (as retrieved by
     <methodname>ListProperties</methodname>) and returns an array of
     integer property IDs and property values (as variant types).
    </para>

    <para>
     Requesting invalid property IDs will result in the
     <errorname>InvalidArgument</errorname> error. Requesting properties
     that do not have the read flag set will result in
     <errorname>PermissionDenied</errorname> being returned.
    </para>
   </sect2>

   <sect2 id="sect.basics.tpproperties.set">
    <title>Setting Properties</title>

    <para>
     Setting properties is done using the
     <methodname>SetProperties</methodname> method. This method takes an
     array of integer property identifiers (as retrieved by
     <methodname>ListProperties</methodname>) and variant types.
    </para>

    <para>
     If the property is of the wrong type, the error
     <errorname>NotAvailable</errorname> will be returned. If the property
     ID is unknown, the error <errorname>InvalidArgument</errorname> will be
     returned. If the write flag is not set on a given property, the error
     <errorname>PermissionDenied</errorname> will be returned. If any error
     condition is triggered, no properties will be updated, even ones that
     would otherwise be valid.
    </para>

    <para>
     When properties have been successfully changed, the
     <methodname>PropertiesChanged</methodname> signal will be emitted with
     the IDs and new values of the changed properties. Be aware that
     changing one property may cause several properties to update. For
     instance, changing <property>subject</property> will cause an update to
     the properties <property>subject</property>,
     <property>subject-timestamp</property> and
     <property>subject-contact</property>.
    </para>
   </sect2>

   <sect2 id="sect.basics.tpproperties.glib">
    <title>telepathy-glib</title>

    <para>
     telepathy-glib provides no specific support infrastructure for
     Telepathy Properties. You can set up some simple infrastructure for
     handling properties in your project and attach it to the
     <classname>TpProxy</classname>.
    </para>

    <sect3 id="sect.basics.tpproperties.glib.setup">
     <title>Setup and Listing Properties</title>

     <example id="ex.basics.tpproperties.setup"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Telepathy Properties Setup</title>
     </example>

     <example id="ex.basics.tpproperties.list"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Listing Telepathy Properties</title>
     </example>
    </sect3>

    <sect3 id="sect.basics.tpproperties.glib.get">
     <title>Getting Properties</title>

     <example id="ex.basics.tpproperties.get"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Getting Telepathy Properties</title>
     </example>

     <example id="ex.basics.tpproperties.getcb"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Get Telepathy Properties Callback</title>
     </example>
    </sect3>

    <sect3 id="sect.basics.tpproperties.glib.set">
     <title>Setting Properties</title>

     <example id="ex.basics.tpproperties.set"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Setting Telepathy Properties</title>
     </example>

     <example id="ex.basics.tpproperties.changecb"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Telepathy Properties Changed Callback</title>
     </example>

     <example id="ex.basics.tpproperties.flagchangecb"
              file="glib_telepathy_properties/example.c">
      <title>telepathy-glib Telepathy Property Flags Changed Callback</title>
     </example>

    </sect3>
   </sect2>

  </sect1>

</chapter>