diff options
36 files changed, 2102 insertions, 0 deletions
diff --git a/Bugs.mdwn b/Bugs.mdwn new file mode 100644 index 0000000..7663b4d --- /dev/null +++ b/Bugs.mdwn @@ -0,0 +1,7 @@ + +Most (but not all) Telepathy components use the [[freedesktop bugzilla|http://bugs.freedesktop.org/]]. + +* [[Empathy|http://live.gnome.org/Empathy]] uses the [[Gnome Bugzilla|http://bugzilla.gnome.org/buglist.cgi?query=product%3Aempathy+]]. +* See [[all open Telepathy bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Telepathy&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&query_based_on=haze+bugs&field0-0-0=noop&type0-0-0=noop&value0-0-0=]] in the freedesktop bugzilla. +* File a [[new bug|https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy]] against the Telepathy component in the freedesktop bugzilla. +If you're looking for some bugs to fix as a starting point for getting involved, take a look at the [[Empathy bugs tagged with ‘gnome-love’|https://bugzilla.gnome.org/buglist.cgi?quicksearch=keywords:gnome-love+product:%22empathy%22+]] or [[Telepathy bugs tagged with ‘love’|https://bugs.freedesktop.org/buglist.cgi?quicksearch=product:Telepathy+keywords:love]]. Feel free to drop by #empathy on Gnome IRC or #telepathy on Freenode! diff --git a/Components.mdwn b/Components.mdwn new file mode 100644 index 0000000..ee91588 --- /dev/null +++ b/Components.mdwn @@ -0,0 +1,63 @@ +## Clients + +As a user, you interact with a Telepathy Client. + +* **[[Empathy|http://live.gnome.org/Empathy]]**: a Gnome IM/voice/video client +* **[[KDE-Telepathy|http://community.kde.org/KTp]]**: a collection of components providing IM capabilities to the KDE desktops +* Many OLPC activities do collaboration using telepathy, including [[Paint|http://wiki.laptop.org/go/Paint_%28Oficina%29]] and [[Chat|http://wiki.laptop.org/go/Chat]]. + +## Connection Managers + +Connection Managers are the components responsible for actually connecting to the Jabber/AIM/... server. Your distribution probably has packages for most or all of the current CMs, so you don't need to install from source unless you're on a weird distro or want to hack on them. + + +### Stable + +* **Gabble:** A Jabber/XMPP connection manager that handles single- and multi-user chats and voice/video calls. + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-gabble` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-gabble]] + * [[Releases (source code)|http://telepathy.freedesktop.org/releases/telepathy-gabble/]] +* **Salut:** A link-local XMPP connection manager ([[XEP-0174|http://www.xmpp.org/extensions/xep-0174.html]]). [[CategorySalut|CategorySalut]] + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-salut` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-salut]] + * [[Releases (source code)|http://telepathy.freedesktop.org/releases/telepathy-salut/]] +* **Idle**: A IRC connection manager. + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-idle` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-idle]] + * [[Releases (source code)|http://telepathy.freedesktop.org/releases/telepathy-idle/]] +* **Rakia:** A SIP connection manager based around the [[Sofia-SIP|http://sofia-sip.sourceforge.net/]] library (formerly known as _Telepathy-SofiaSIP_) + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-rakia` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-rakia]]; + * [[Releases (source code, development branch only)|http://telepathy.freedesktop.org/releases/telepathy-rakia/]]; stable and historical releases can be found under the [[old name|http://telepathy.freedesktop.org/releases/telepathy-sofiasip/]], and yet older ones on the [[SF.net project page|http://sourceforge.net/projects/tp-sofiasip]]. + +### Incomplete + +* **Haze:** A connection manager based on Pidgin's libpurple, supporting all protocols in Pidgin (AIM, ICQ, Yahoo, MSN, etc) at a basic level, but already very usable. + * [[Releases (source code)|http://telepathy.freedesktop.org/releases/telepathy-haze/]]; new releases are announced on the Telepathy mailing list. + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-haze` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-haze]] + * [[Bugs|https://bugs.freedesktop.org/buglist.cgi?product=Telepathy&component=telepathy-haze]] + * Requires libpurple and [[Telepathy GLib|Components/Telepathy GLib]] + * [[Haze FAQ|Haze FAQ]] + +### Unmaintained + +* **[[telepathy-ring|http://cgit.freedesktop.org/telepathy/telepathy-ring]]:** GSM support via Ofono. + +## Libraries + +* **[[Telepathy GLib|Components/Telepathy GLib]]**: A GLib/GObject-based library for clients and connection managers +* **[[Telepathy Qt|Components/Telepathy Qt]]**: Qt4/Qt5 library for use in Telepathy clients, including a Qt binding for [[Telepathy-Farstream|Components/Telepathy-Farstream]]. Renamed from [[Telepathy-Qt4|Components/Telepathy-Qt4]] since version 0.9.0 +* **[[Telepathy-Farstream|Components/Telepathy-Farstream]]**: a GLib/GObject library that uses [[Farstream|https://www.freedesktop.org/wiki/Software/Farstream/]] to handle the media streaming part of channels of type [[Call|https://telepathy.freedesktop.org/spec/Channel_Type_Call.html]] +* **[[Wocky|Components/Wocky]]**: an XMPP library that is built entirely asynchronously, makes it easier to provide more modern XMPP features, and takes advantage of the latest GLib features, such as gnio. Wocky source is directly in the gabble tree (via a git submodule). + +### Related + +* **[Folks](http://live.gnome.org/Folks)**: a library that aggregates people from multiple sources (eg, Telepathy connection managers for IM contacts, Evolution Data Server for local contacts, libsocialweb for web service contacts, etc.) to create metacontacts + +## Other Components + +* **[[Mission Control|Components/Mission Control]]**: an Account Manager and Channel Dispatcher implementation, which stores accounts and coordinates the launching of connection managers and clients. +* **[[SSH Contact|Components/SSH-Contact]]**: a client/service tool that makes it easy to connect to your telepathy IM contacts via SSH, using [[Stream Tubes|Documentation/Tubes]] + +See also the [[Dead Components|Components/Dead]] page for some history. diff --git a/Components/Dead.mdwn b/Components/Dead.mdwn new file mode 100644 index 0000000..1a55a4e --- /dev/null +++ b/Components/Dead.mdwn @@ -0,0 +1,49 @@ +This page lists **old and dead** components of the Telepathy framework for historical reasons. None of them is developed anymore and in most cases it doesn't make sense to revive any of them due to use of deprecated API or libraries. + +## Connection Managers + +* **Wilde**: An AOL/ICQ (Oscar) connection manager, this handles single direct messaging, presence, conversations and simple buddy list (add/remove). +* **Butterfly:** An MSN connection manager that handles presence, conversations, avatars, personal messages, server-side aliases, and full contact management (including groups). + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-butterfly` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-butterfly]] + * [[Releases (source code)|http://telepathy.freedesktop.org/releases/telepathy-butterfly/]] + * Requires Papyon and Telepathy Python. +* **Sunshine:** A connection manager with support for Gadu-Gadu network that handles basic GG 10 protocol features. + * `git clone git://anongit.freedesktop.org/telepathy/telepathy-sunshine` + * [[Browse git history|http://cgit.freedesktop.org/telepathy/telepathy-sunshine]] + * Requires [[Twisted Framework|http://twistedmatrix.com/]] and Telepathy Python. +* **[[telepathy-mixer|http://code.google.com/p/telepathy-mixer/]]:** support for the MXit protocol. + +## Clients + +* The instant messaging, address book and VoIP user interfaces on Nokia's [[Maemo|http://maemo.org/]]-powered internet tablets/phones (such as the N810 and N900) are Telepathy clients. +* **Ereseva**: VOIP-capable webphone, based on tapioca-python and GTK+ libraries. ([[Ereseva SVN repository|https://tapioca-voip.svn.sourceforge.net/svnroot/tapioca-voip/trunk/ereseva]]) +* **Landell**: a GNOME Instant Messenger built around Tapioca# (C#/Mono) +* **Cohoba**: a UI for GNOME desktops by Raphaël Slinckx (Python) +* **GnomeUI**: an experimental UI for Gnome desktops by Adam Lofts (C#/Mono) +* **[[Banter|https://wiki.gnome.org/Apps/Attic/Banter]]**: a Gnome IM/voice/video client with a rich user interface (C#/Mono) + +## Tools + +* **Telepathy Inspector**: A telepathy client (GTK+) whose objective is to expose all interfaces and functionalities implemented by a given connection manager along with its connections, channels, etc. + +## Libraries + +* **Telepathy-Farsight**: a GLib/GObject library that uses [[Farsight2|http://farsight.freedesktop.org]] to handle the streaming part of media streaming for channels with the [[MediaSignalling|http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.Channel.Interface.MediaSignalling]] interface + * renamed to [[Telepathy-Farstream|Components/Telepathy-Farstream]], following Farsight2's rename to Farstream +* **[[Telepathy-Qt4|Components/Telepathy-Qt4]]**: High-level binding for Telepathy, similar to [[telepathy-glib|Components/Telepathy GLib]] but for Qt4. + * renamed to [[Telepathy Qt|Components/Telepathy Qt]] and now also supports Qt5 +* **Telepathy Python**: Python libraries for use in Telepathy clients (e.g. Cohoba) and connection managers (e.g. Butterfly) + * deprecated in favour of [[GObjectIntrospection|GObjectIntrospection]] bindings based on [[Telepathy GLib|Components/Telepathy GLib]] +* **TelepathySharp**: A .NET library for use in Telepathy clients +* **TapiocaSharp**: A high-level .NET library on top of [[TelepathySharp|TelepathySharp]] for use in Telepathy clients (e.g. landell) +* **TelepathyQt**: Older Qt4 libraries for use in Telepathy clients and connection managers + * deprecated in favour of [[Telepathy Qt4|Components/Telepathy Qt4]], which was later renamed to [[Telepathy Qt|Components/Telepathy Qt]] again, but is a completely different library. +* **TapiocaQt**: A high-level Qt4 library on top of TelepathyQt for use in Telepathy clients (e.g. decibel, kopete) +* **libtelepathy:** A GLib library to ease writing Telepathy clients in glib + * deprecated in favour of [[Telepathy GLib|Components/Telepathy GLib]]. [[releases|http://telepathy.freedesktop.org/releases/libtelepathy/]] + +## Other Components + +* **Stream engine:** The part of the Maemo UI that handles the streaming aspects of a Telepathy client, it uses Telepathy-Farsight, [[Farsight2|http://farsight.freedesktop.org]] and [[GStreamer|http://gstreamer.freedesktop.org/]] to handle media streaming for channels with the [[MediaSignalling|http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.Channel.Interface.MediaSignalling]] interface. +* **telepathy-feed:** A [[Galago|http://www.galago-project.org/]] feed for Telepathy. [[http://telepathy.freedesktop.org/releases/telepathy-feed|http://telepathy.freedesktop.org/releases/telepathy-feed]] diff --git a/Components/Mission_Control.mdwn b/Components/Mission_Control.mdwn new file mode 100644 index 0000000..5d830f4 --- /dev/null +++ b/Components/Mission_Control.mdwn @@ -0,0 +1,20 @@ +## Overview
+
+Mission Control—or MC for short—is a Telepathy component implementing both the [Account Manager](http://telepathy.freedesktop.org/spec/Account_Manager.html) and [Channel Dispatcher](http://telepathy.freedesktop.org/spec/Channel_Dispatcher.html) specifications. It stores your IM account settings, deals with talking to the relevant connection managers to bring accounts online where necessary, and dispatches incoming and outgoing communication channels to the relevant applications.
+
+For example, your address book can ask Mission Control to create a call channel to bob@example.com from your Google Talk account. MC relays that request to the connection manager (Gabble) and, when the connection manager responds, passes the call channel to the application on your system which presents UI for calls (launching it if necessary).
+
+Mission Control is licensed under the LGPL v2.1; it was originally written by Naba Kumar and Alberto Mardegan at Nokia Corporation for the Maemo platform, and is currently maintained by Collabora Ltd.
+
+## Resources
+
+Your favourite distribution probably already provides packages of Mission Control. Alternatively, you can obtain the source code by a variety of different means:
+
+* [Releases (source code)](http://telepathy.freedesktop.org/releases/telepathy-mission-control)
+* `git clone git://anongit.freedesktop.org/telepathy/telepathy-mission-control`
+* [Git web](http://cgit.freedesktop.org/telepathy/telepathy-mission-control/)
+
+## See also
+
+* The other [[Components]] of the Telepathy framework.
+* The [Accounts and AccountManager](http://telepathy.freedesktop.org/doc/book/chapter.accounts.html) and [Channel Dispatcher and Clients](http://telepathy.freedesktop.org/doc/book/chapter.channel-dispatcher.html) chapters of the [Telepathy Developer’s Manual](http://telepathy.freedesktop.org/doc/book/).
diff --git a/Components/SSH-Contact.mdwn b/Components/SSH-Contact.mdwn new file mode 100644 index 0000000..65dd231 --- /dev/null +++ b/Components/SSH-Contact.mdwn @@ -0,0 +1,34 @@ + + +# Description + +SSH-Contact is a client/service tool that makes it easy to connect to your telepathy IM contacts via SSH. No need to care about dynamic IP, NAT, port forwarding, or firewalls anymore; if you can chat with a friend, you can also SSH to their machine. + + +# Links + +* [[SSH-Contact releases|http://telepathy.freedesktop.org/releases/ssh-contact/]] +* [[SSH-Contact git|http://cgit.freedesktop.org/telepathy/telepathy-ssh-contact/]] +* [[Report a bug|https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=ssh-contact]] + +# FAQ + + +## Does it work if I'm using pidgin? + +No. You and the contact you are sshing must be online using a Telepathy client (like Empathy). + + +## Which IM protocols are supported? + +Currently only Jabber (using telepathy-gabble) is supported. But ssh-contact could work with any protocol if its telepathy backend supports [[StreamTube|StreamTube]]. + + +## Why some of my contacts are not listed in ssh-contact menu? + +Only contacts with ssh-contact service installed and connected using telepathy are listed + + +## Is there security risks? + +If you install the ssh-contact service, your ssh daemon is exposed to all your IM contacts. Of course they still have to make the ssh authentication (password, ssh key, etc). This means that your sshd is not "protected" anymore behind a NAT or firewall. It is equivalent to have ssh daemon running with a public IP address and port 22 open. So ssh-contact-service security == sshd security. It is your choice to trust sshd or not. diff --git a/Components/Telepathy-Farstream.mdwn b/Components/Telepathy-Farstream.mdwn new file mode 100644 index 0000000..d91843a --- /dev/null +++ b/Components/Telepathy-Farstream.mdwn @@ -0,0 +1,17 @@ + +telepathy-farstream is a GObject-based C library that uses [[Telepathy GLib|Components/Telepathy GLib]], [[Farstream|https://www.freedesktop.org/wiki/Software/Farstream/]] and GStreamer to handle the media streaming part of channels of type [[Call|https://telepathy.freedesktop.org/spec/Channel_Type_Call.html]] + +* [[Releases (Source code)|http://telepathy.freedesktop.org/releases/telepathy-farstream/]] +* [[Browse source|https://cgit.freedesktop.org/telepathy/telepathy-farstream/]] + +[[!format txt """ +git://anongit.freedesktop.org/telepathy/telepathy-farstream +ssh://git.freedesktop.org/git/telepathy/telepathy-farstream +"""]] +[[API documentation|http://telepathy.freedesktop.org/doc/telepathy-farstream/]] + + +## Bugs + +* [[Submit a telepathy-farstream bug|https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=tp-farstream]] (A component in the telepathy bugzilla component) +* [[Open tp-farstream bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Telepathy&component=tp-farstream&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=VERIFIED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=]] diff --git a/Components/Telepathy-Qt4.mdwn b/Components/Telepathy-Qt4.mdwn new file mode 100644 index 0000000..b7aaca3 --- /dev/null +++ b/Components/Telepathy-Qt4.mdwn @@ -0,0 +1,13 @@ + +Telepathy-Qt4 is a high-level binding for Telepathy, similar to [[telepathy-glib|Components/Telepathy GLib]] but for Qt 4. + +0.2.0, the first shared-library release with stable API and ABI, was announced on 10th November 2009. + +Development is done in [[the telepathy-qt4 git repository|http://cgit.freedesktop.org/telepathy/telepathy-qt4/]]. + +Since 0.9.0 release, renamed to [[Telepathy-Qt|Components/Telepathy Qt]]. +## Differences between [[TelepathyQt (Tapioca)]] and Telepathy-Qt4 + +The older [[TelepathyQt|TelepathyQt]] library maintained by the Tapioca project only contains low-level 1:1 bindings of the D-Bus interfaces; the separate Tapioca-Qt library builds on that to provide high-level API. + +In the same way as telepathy-glib, Telepathy-Qt4 provides both the low-level (1:1) auto-generated API, and a high-level API built on that, in the same library. diff --git a/Components/Telepathy_GLib.mdwn b/Components/Telepathy_GLib.mdwn new file mode 100644 index 0000000..51ae0ca --- /dev/null +++ b/Components/Telepathy_GLib.mdwn @@ -0,0 +1,57 @@ + +The telepathy-glib library is a GObject-based C binding for the Telepathy D-Bus API. It may be used by client applications. It is also used by connection managers, because it contains code common to GLib-based connection managers such as Gabble, Idle, Sofia-Sip and Salut. + +* [[Releases (Source code)|http://telepathy.freedesktop.org/releases/telepathy-glib/]] +* [[gitweb|http://cgit.freedesktop.org/telepathy/telepathy-glib/]] + +[[!format txt """ +git://anongit.freedesktop.org/telepathy/telepathy-glib +ssh://git.freedesktop.org/telepathy/telepathy-glib +"""]] +[[API documentation for the development branch|http://telepathy.freedesktop.org/doc/telepathy-glib/]] + +[[API documentation for the 0.10.x stable branch|http://telepathy.freedesktop.org/doc/telepathy-glib-0.10.x/]] + +[[older API documentation is also available|http://telepathy.freedesktop.org/doc/]] + + +## What's provided + + +### For client authors + +* `TpConnection` — an asynchronous interface to Telepathy connections +* `TpContact` — an object representing a Telepathy contact +* `TpChannel` — an asynchronous interface to Telepathy channels +* `TpConnectionManager` — an asynchronous interface to Telepathy connection managers +* `TpProxy` — an base class for extensible D-Bus client objects, used by `TpConnection`, `TpChannel` and `TpConnectionManager` + +### For connection manager authors + +* `TpBaseConnectionManager` — a connection manager base class (implements `Telepathy.ConnectionManager`, you subclass it and specify a protocol and its arguments, and it will handle the listing/argument validation/connection object creation, etc) +* `TpBaseConnection` — a connection base class (implements Telepathy.Connection, subclass it to teach it how to connect to the given protocol and which factories to make) +* `TpChannelManagerIface` — a channel manager interface (used by the connection to see if any channel managers can service an incoming channel request) +* handle repositories (provide it with validation/normalisation functions, and off you go...): `TpHandleRepoIface`, `TpDynamicHandleRepo`, `TpStaticHandleRepo` +* `TpPropertiesMixin` — a properties mixin +* `TpGroupMixin` — a groups mixin +* `TpTextMixin` — a text mixin - ported from Gabble + +### For everyone + +* miscellaneous constants +* error domain and enumeration +* debug and other shared utilities (util.*, handles.*) + +## Things to add + +* a channel base class (implements Telepathy.Channel, you subclass it w/ mixins to implement certain channel types) - deferred for the moment + +## Dependencies + +Telepathy-GLib depends on the last release of the Glib bindings (0.72), since then implementing these mixins as interfaces & doing inheritance & adding in interfaces becomes a lot more practical. Telepathy-GLib looks for D-Bus glue data on all of the GInterfaces and superclasses a given object has, so we no longer have to produce one `.xml` file for e.g. `GabbleConnection` and the particular combination of interfaces it has. + + +## Bugs + +* [[Submit a telepathy-glib bug|https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=telepathy-glib]] (A component in the telepathy bugzilla component) +* [[Open telepathy-glib bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Telepathy&component=telepathy-glib&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=VERIFIED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=]]
\ No newline at end of file diff --git a/Components/Telepathy_Qt.mdwn b/Components/Telepathy_Qt.mdwn new file mode 100644 index 0000000..cd805fd --- /dev/null +++ b/Components/Telepathy_Qt.mdwn @@ -0,0 +1,8 @@ + +A high-level binding for Telepathy, similar to [[telepathy-glib|Components/Telepathy GLib]] but for [[Qt|http://qt-project.org]]. Supports Qt4 and (not yet released) Qt5. + +Development is done in [[the telepathy-qt git repository|http://cgit.freedesktop.org/telepathy/telepathy-qt/]]. + +[[API documentation|http://telepathy.freedesktop.org/doc/telepathy-qt/]] + +Before the 0.9.0 release, this library was named [[Telepathy-Qt4|Components/Telepathy-Qt4]]. diff --git a/Components/Wocky.mdwn b/Components/Wocky.mdwn new file mode 100644 index 0000000..1afc827 --- /dev/null +++ b/Components/Wocky.mdwn @@ -0,0 +1,15 @@ +**Wocky** is the [XMPP](http://xmpp.org) library used by telepathy-gabble (the regular XMPP backend) and telepathy-salut (the iChat-compatible link-local XMPP backend as specified in [XEP-0174](http://xmpp.org/extensions/xep-0174.html)). It uses GObject, GIO, libxml2, plus your choice of [GnuTLS](http://www.gnutls.org/) or [OpenSSL](http://www.openssl.org/). It is distributed under the GNU LGPL version 2.1, or (at your option) any later version. + +It supports, among other features: + +* Jingle ([XEP-0166](http://xmpp.org/extensions/xep-0166.html), [XEP-0167](http://xmpp.org/extensions/xep-0167.html), [XEP-0176](http://xmpp.org/extensions/xep-0176.html), [XEP-0177](http://xmpp.org/extensions/xep-0177.html)) +* Data Forms ([XEP-0004](http://xmpp.org/extensions/xep-0004.html)) +* Multi-User Chat ([XEP-0045](http://xmpp.org/extensions/xep-0045.html)) +* PEP ([XEP-0163](http://xmpp.org/extensions/xep-0163.html)) and certain other parts of PubSub ([XEP-0060](http://xmpp.org/extensions/xep-0060.html)) +* HTTP CONNECT proxies +* Pluggable SASL authentication + +At present, Wocky does not receive its own independent releases. It is included as a Git submodule in the Gabble and Salut repositories, and is distributed as part of their releases. + +* [Git](http://cgit.freedesktop.org/wocky) +* [Bug tracker](https://bugs.freedesktop.org/buglist.cgi?product=Wocky&component=General&resolution=---&list_id=277038) diff --git a/Components/Yafono.mdwn b/Components/Yafono.mdwn new file mode 100644 index 0000000..36c02b8 --- /dev/null +++ b/Components/Yafono.mdwn @@ -0,0 +1,9 @@ + +Wireless (mobile/cellular/GSM etc.) modem support for Telepathy via [[Ofono|http://www.ofono.org]]. + +Currently abandoned and obsoleted by telepathy-ring ; supports sending and receiving SMS. + +Links + +* [[Code|http://git.collabora.co.uk/?p=telepathy-yafono.git;a=summary]] +* [[Bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Telepathy&component=yafono&long_desc_type=allwordssubstr&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&field0-0-0=bug_status&type0-0-0=notequals&value0-0-0=UNCONFIRMED]]
\ No newline at end of file diff --git a/DbusSpec.mdwn b/DbusSpec.mdwn new file mode 100644 index 0000000..c009009 --- /dev/null +++ b/DbusSpec.mdwn @@ -0,0 +1,233 @@ + +The latest draft specification can be found at [[http://telepathy.freedesktop.org/spec/|http://telepathy.freedesktop.org/spec/]]. Older stable versions of the specification available at: + +* [[http://telepathy.freedesktop.org/spec-0.20/|http://telepathy.freedesktop.org/spec-0.20/]] +* [[http://telepathy.freedesktop.org/spec-0.18/|http://telepathy.freedesktop.org/spec-0.18/]] +* [[http://telepathy.freedesktop.org/spec-0.16.html|http://telepathy.freedesktop.org/spec-0.16.html]] +* [[http://telepathy.freedesktop.org/spec-0.14.html|http://telepathy.freedesktop.org/spec-0.14.html]] +* [[http://telepathy.freedesktop.org/spec-0.12.html|http://telepathy.freedesktop.org/spec-0.12.html]] +<a name="extensions-v0"></a> + + +# Specification D-Bus introspect format extensions, version 0 + +As of version 0.14 the spec is written in an embraced-and-extended form of the D-Bus introspection format. + +The spec consists of a main XML all.xml file which incorporates other files using XInclude. + + +## Document structure + + +[[!format txt """ +<!-- all.xml --> +<tp:spec xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:title>The Telepathy specification</tp:title> + <tp:version>a.b.c</tp:version> + + <!-- each node is actually in a separate document, using XInclude --> + <node><interface>...</interface></node> + + <!-- tp:errors is actually in a separate document errors.xml, using XInclude --> + <tp:errors namespace="org.freedesktop.Telepathy.Error"> + <tp:error name="...">...</tp:error> + </tp:errors> +</tp:spec> +"""]] + +## XHTML + +Some elements are noted below as containing XHTML. These may either contain a single paragraph of plain text, or some XHTML - in the latter case you need an xmlns="[[http://www.w3.org/1999/xhtml|http://www.w3.org/1999/xhtml]]" attribute on the element. Some spec processing tools may just ignore the tags and write out the plain text, so bear that in mind when you format it. + + +## Copyright and stuff + +tp:copyright elements may appear anywhere, to describe the copyright of nodes below that point. They contain character data like "Copyright (C) 2005, 2006, 2007 Collabora Limited". If there is more than one copyright holder there must be multiple tp:copyright elements. + +tp:license elements may appear anywhere. They contain XHTML. + +(FIXME: it would be somewhat saner to have the license and copyright holders only appear in one place, or something.) + + +## Docstrings + +Many elements can contain a tp:docstring. This is the text of the spec; it may contain XHTML. + +Any interface, method or signal can contain something like <tp:added version="0.14.1"/> which has the obvious meaning. + + +## Interface definitions + +Each interface is wrapped in a separate node element: this is to make it easier to generate ordinary D-Bus introspection XML for tools that need that. It's also in a separate XML file, which is XIncluded into all.xml. + +The node's name is required to be in the format "/Some_API_Name". This is mangled in various ways to make constants, class names, etc.: + +* for camel-case names like Python and GLib classes, remove the "/" and the underscores: SomeAPIName +* for upper- or lower-case underscore-separated names like C constants and functions, remove the "/" and translate to upper- or lower-case: SOME_API_NAME, some_api_name +The filename is the same as the node name, without the leading '/'. + +The interface element has a tp:docstring and some D-Bus method and signal elements. + +The interface element can also include tp:requires elements whose interface attribute is the full D-Bus name of an interface which must be implemented as a prerequisite. + +The method and signal elements, and their arg elements, are extended to contain a tp:docstring too. Also, methods can contain a tp:possible-errors element. + +The tp:possible-errors element contains tp:error elements whose name attribute is the full D-Bus name of an error. Each of these may optionally contain a tp:docstring specifying when the error is raised. If it doesn't, the generic docstring from the error definition will be used in documentation instead. + +For example, here's the definition of the Connection.[[InspectHandles|InspectHandles]] method, which illustrates errors with custom reasons as well as an error using the default description: + + +[[!format txt """ +<method name="InspectHandles" tp:name-for-bindings="Inspect_Handles"> + <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> + <tp:docstring> + The type of handle to be inspected + </tp:docstring> + </arg> + + <arg direction="in" name="Handles" type="au" tp:type="Handle[]"> + <tp:docstring> + An array of integer handles of this type + </tp:docstring> + </arg> + + <arg direction="out" type="as" name="Identifiers"> + <tp:docstring> + An array of identifiers corresponding to the given handles, in the same order. + </tp:docstring> + </arg> + + <tp:docstring> + Return a string representation for a number of handles of a given + type. + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + The handle type is invalid + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + One of the given handles is not valid + </tp:error> + </tp:possible-errors> +</method> +"""]] + +## Simple type synonyms + +You can declare and document semantically-relevant synonyms for simple types using the tp:simple-type elemnt, as follows: + + +[[!format txt """ +<tp:simple-type name="Handle" type="u" array-name="Handle_List"> + <tp:docstring>An unsigned 32-bit integer representing a handle</tp:docstring> +</tp:simple-type> +"""]] +This example also illustrates the array-name attribute, which suggests a sensible name for arrays or lists of this type to binding generators. + + +## Flags and enumerations + +Enumerations are represented by a tp:enum element with a name attribute; sets of flags which are to be bitwise-OR'd together are represented by a tp:flags element with a name attribute. The name must be in mixed case with underscores between words: this will be mangled into various formats in the same way the node names are. Either may contain an optional tp:docstring. + +There may also be a value-prefix attribute which sets the string used for the beginning of a value's name, as described below; if omitted, the name is used. + +Typically, enums don't need a value-prefix, and for a flag set Foo_Flags the value-prefix is Foo_Flag. + +Enums may have a plural attribute giving the plural form of the name. If not given, it may be assumed to be the name with "s" appended (we assume that any specification in this format is likely to be in English :-)) + +(FIXME: We should replace @value-prefix and @name with @singular and @plural) + +tp:enum elements contain tp:enumvalue elements, and tp:flags elements contain tp:flag elements. Both have attributes suffix and value, and may contain a tp:docstring. + +(FIXME: Alp suggests we should replace @suffix with @name) + +The suffix is in mixed case with underscores between words, and is mangled into the appropriate format (in practice, usually upper-case with underscores) and appended to the value-prefix of the enumeration (separated by an underscore if appropriate; the name is used if there is no value-prefix). The value is the numeric value, typically 0, 1, ... for enumerations and 1, 2, 4, ... for sets of flags. + +In enumerations, the tp:enumvalue elements must appear in ascending numeric order, so tools can generate a constant for "highest value" in a straightforward way. + + +## Structs and Maps + +Aliases for D-Bus structs and dictionaries are represented by tp:struct and tp:mapping elements, respectively. They are identical, except that the latter must contain exactly two tp:member children, documenting the key and value types of the dictionary. The members may be annotated with tp:type attributes if appropriate. Here are a pair of examples from the [[SimplePresence|SimplePresence]] interface: + + +[[!format txt """ +<tp:struct name="Simple_Presence"> + <tp:docstring> + A struct representing the presence of a contact. + </tp:docstring> + <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"> + <tp:docstring> + The presence type, e.g. Connection_Presence_Type_Away. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Status"> + <tp:docstring> + The string identifier of the status, e.g. "brb", as defined in the + <tp:member-ref>Statuses</tp:member-ref> property. + </tp:docstring> + </tp:member> + <tp:member type="s" name="Status_Message"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The user-defined status message, e.g. "Back soon!".</p> + + <p>Clients SHOULD set the status message for the local + user to the empty string, unless the user has actually provided + a specific message (i.e. one that conveys more information than the + Status).</p> + + <p>User interfaces SHOULD regard an empty status message as unset, + and MAY replace it with a localized string corresponding to the + Status or Type.</p> + + <tp:rationale> + Use case: Daf sets his status in Empathy by choosing the Welsh + translation of "Available" from a menu. + It is more informative for his English-speaking colleagues + to see the English translation of "Available" (as localized + by their own clients) than to see "Ar Gael" (which they don't + understand anyway). + </tp:rationale> + </tp:docstring> + </tp:member> +</tp:struct> + +<tp:mapping name="Simple_Contact_Presences"> + <tp:docstring> + Mapping returned by <tp:member-ref>GetPresences</tp:member-ref> + and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>, + indicating the presence of a number of contacts. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact + </tp:docstring> + </tp:member> + <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence"> + <tp:docstring> + The contact's presence + </tp:docstring> + </tp:member> +</tp:mapping> +"""]] + +## Properties + +The tp:property elements document the name and meaning of properties which can be accessed on the org.freedesktop.Telepathy.Properties interface of the object implementing the documented interface. This is primarily intended to associate certain named properties with particular channel types. The name attribute is the string name of the property as found in the [[ListProperties|ListProperties]] method, and the type attribute is the single complete D-Bus type of this property. Each tp:property element should have a tp:docstring element associated. + +(FIXME: we should probably provide a Camel_Case_With_Underscores name for each property, as well or instead) + + +## Error definitions + +The tp:errors element has a namespace attribute and contains a number of tp:error-def elements, each with a tp:docstring and a name attribute. + +The namespace attribute is the part of the namespace that's assumed for all errors - this won't appear in class names etc. since the language's namespacing (modules in Python, prefixes like TP_ in C, etc.) is used instead. + +The name attribute on each error-def is written like "Example [[SubNamespace|SubNamespace]].Sample Error". This is mangled in various ways to generate names: + +* for D-Bus error names, the spaces are removed and it's appended to the assumed namespace after a dot: e.g. org.freedesktop.Telepathy.Error.[[ExampleSubNamespace|ExampleSubNamespace]].[[SampleError|SampleError]] +* for "camel-case" names, like classes in Python, the spaces and dots are removed: e.g. [[ExampleSubNamespaceSampleError|ExampleSubNamespaceSampleError]] +* for UPPER_CASE or lower_case names, like constants and functions in C, the spaces and dots are converted to underscores, and the case is normalized: e.g. EXAMPLE_SUBNAMESPACE_SAMPLE_ERROR or the lower-case equivalent
\ No newline at end of file diff --git a/Debugging.mdwn b/Debugging.mdwn new file mode 100644 index 0000000..f50d02e --- /dev/null +++ b/Debugging.mdwn @@ -0,0 +1,110 @@ +## If you are using Empathy... + +Empathy has a debug console which shows you the debug output from components of your choice. See [[the Empathy wiki|http://live.gnome.org/Empathy/Debugging]] for more details. + +If you're not using Empathy, or you're debugging a crash, or you're just feeling old-school, read on! + + +## Connection managers + +Many Telepathy problems are not directly the fault of the user interface (such as Empathy), but of the connection managers (Gabble, Idle, Salut, Haze, Butterfly, Telepathy-SofiaSIP, ...), which are the services responsible for actually connecting to your IM accounts. CMs generally run in the background, with no visible output; in order to get debugging output from them, you'll need to run them manually. + +Connection manager executables don't generally live in your `$PATH`, so you'll need to provide the full path in the following commands (rather than just `telepathy-foo`) to invoke them. + +* on Fedora-like systems, connection managers live in `/usr/libexec/` +* on recent Debian-like systems connection managers live in `/usr/lib/telepathy/` +* if you have installed from source, the default location is `/usr/local/libexec/` + +### Obtaining logs + +First, quit your IM client (such as Empathy), and wait a few seconds for the connection managers to quit of their own accord. Then, in a terminal, run: + + G_MESSAGES_DEBUG=all FOO_PERSIST=1 FOO_DEBUG=all /path/to/telepathy-foo 2>&1 | tee foo.log + +(where `foo` should be `gabble` for Jabber, and the name of the relevant CM for the protocol you're having trouble with, as listed on [[Components|Components]]). Now, start your IM client again, and reproduce the problem; debugging output should appear in your terminal, and be written to `foo.log`. (You can set the `_DEBUG` variable to values other than `all` if you only want the debugging output from a certain part of the CM, but usually this is unnecessary.) + +If the connection manager complains about "name already or use" and quits immediately, you should `kill` any existing instances of it and try again. + + +### Gabble + +When debugging Gabble, it's usually a good idea to set `WOCKY_DEBUG=xmpp` (Gabble 0.9) or `LM_DEBUG=net` (Gabble 0.8) so that the XML stanzas are also captured in the logfile. + + +### SRV records (Gabble, SIP) + +If you're having difficulty connecting to a SIP or Jabber/XMPP server, and you're using Linux, you can check whether SRV DNS lookups are broken on your network using the `host` command-line tool. Collabora's XMPP server has a SRV record, which you can use to try this out, by running: `host -t SRV _xmpp-client._tcp.collabora.co.uk` + +If it works correctly, you'll see something like this: + +`_xmpp-client._tcp.collabora.co.uk has SRV record 0 0 5222 jalfrezi.collabora.co.uk.` + +If SRV lookups don't work on your network you might see an error like this, for instance: + +`Host _xmpp-client._tcp.collabora.co.uk not found: 3(NXDOMAIN)` + + +### Mission Control 5 + +In versions of MC older than 5.3.1 (notably, on Maemo 5), due to [[Bug #22705|https://bugs.freedesktop.org/show_bug.cgi?id=22705]] it is necessary to set `MC_DEBUG=1` to get Mission Control to output debug messages for itself, and something like `MC_TP_DEBUG=all` to output debug messages for telepathy-glib. See the mission-control-5 man page for more details. + + +## Debugging crashes + + +### General + +If you are experiencing crashes, it's a good idea to install any Telepathy debug packages provided by your distribution. + +On Debian-like systems, debugging packages include: + +* libtelepathy-glib0-dbg +* libtelepathy-dbg +* telepathy-gabble-dbg + +### GDB + +You might be able to obtain debug information using gdb (for connection managers, you probably also want to use the X_PERSIST variable for this): + + $ GABBLE_PERSIST=1 gdb telepathy-gabble + GNU gdb 6.7.1-debian + Copyright (C) 2007 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. Type "show copying" + and "show warranty" for details. + This GDB was configured as "i486-linux-gnu"... + Using host libthread_db library "/lib/i686/cmov/libthread_db.so.1". + (gdb) r + Starting program: /usr/bin/telepathy-gabble + ** (telepathy-gabble:17666): DEBUG: started version 0.6.0 (telepathy-glib version 0.7.0) + +If the program crashes while running under gdb, use the "bt" command to obtain a backtrace. + +If you can't make it crash while running under gdb (this is not an uncommon state of affairs, for reasons I won't go into here): + +* make sure core dumps are enabled + * `ulimit -c unlimited` +* launch the telepathy component in question (as above) + * `FOO_PERSIST=1 FOO_DEBUG=all /path/to/telepathy-foo 2>&1 | tee foo.log` +* do whatever it is you do to produce a crash +* inspect the core file (it's normally called "core") + * `gdb /path/to/telepathy-foo core` + * at the gdb prompt: `bt full` +NOTE: If you are running more than one component to debug, either tun them in different directories so their core files don't overwrite one another in the event of a crash, or `sudo sysctl -w kernel.core_uses_pid=1` to make the core file name contain the PID + + +### Valgrind + +Valgrind can find many bugs. + +* [[Valgrind home page|http://valgrind.org/]] +* [[suppression file|http://projects.collabora.co.uk/~robtaylor/glib+glibc.supp]] to stop it complaining about glibc and glib oddities. + +### Electric Fence + +Electric Fence can find some memory allocation bugs. + +To use it, run Programs with LD_PRELOAD=/usr/lib/libefence.so.0.0. + +* [[Electric Fence home page|http://perens.com/FreeSoftware/]]. diff --git a/DeveloperNotes.mdwn b/DeveloperNotes.mdwn new file mode 100644 index 0000000..78da787 --- /dev/null +++ b/DeveloperNotes.mdwn @@ -0,0 +1,33 @@ + + +# Developer Notes + +Unsorted (and unverified) developer notes for Telepathy: + +* [[Telepathy buildbot|http://buildbot.telepathy.im]]: Automated compilation and testing + * If something's up with the buildbot, nag _sjoerd_ or _kov_ on `#telepathy` to fix it. +* [[Streamed Media|Streamed Media]] +* [[Tubes|Tubes]] +* [[Tutorial|Tutorial]]: an introduction to Telepathy and D-Bus basics +* [[Language Bindings|LanguageBindings]] +* [[File Formats|File Formats]]: specification for Telepathy's file formats +* [[Recipes|Recipes]]: how to accomplish various tasks with the Telepathy API +* For developers interested in Telepathy within KDE, the [[Techbase Project Page|http://techbase.kde.org/Projects/Telepathy]] provides more information. +* [[Specification TODO|Specification TODO]] +* [[DBus Rapid Application Development enablers research project|DBusRAD]] +* [[Gabble TODO|Gabble TODO]] +* [[Gabble XEP|Gabble XEP]] +* [[Release Checklist|Release Checklist]]: things to do when making a release +* [[GabbleReleaseBlockers|GabbleReleaseBlockers]] and [[SalutReleaseBlockers|SalutReleaseBlockers]] +* [[Versions of various Telepathy components currently in several Linux distributions|http://people.collabora.co.uk/~cassidy/tp-versions.html]] +* [[Folks|Folks]]: the high-level library for manipulating people + +### Miscellany + +* [[Suggestions|Suggestions]] +* [[Python Example|Python Example]] is a very simple, unpractical example of doing things with Telepathy in Python +* [[DTube Tutorial|DTube Tutorial]] is a tutorial (and example) for doing one-to-one D-Tubes +* [[Perl Example|Perl Example]] is a very simple, unpractical implementation of [[Python Example|Python Example]] in Perl +* [[Telepathy and other Projects|Telepathy and other Projects]]: try to list integration of Telepathy in other projects +* [[Usage_Scenarios|Usage_Scenarios]] +* [[Telepathy/Empathy BOF at GCDS 2009|Telepathy/Empathy BOF at GCDS 2009]]
\ No newline at end of file diff --git a/Documentation.mdwn b/Documentation.mdwn new file mode 100644 index 0000000..5e0ca76 --- /dev/null +++ b/Documentation.mdwn @@ -0,0 +1,32 @@ +Here are some links to documentation resources related to Telepathy. + +## APIs + +* [[DBus API Spec|DbusSpec]] +* [Telepathy Glib API docs](https://telepathy.freedesktop.org/doc/telepathy-glib/) +* [Telepathy Qt API docs](https://telepathy.freedesktop.org/doc/telepathy-qt/) +* [Telepathy Farstream API docs](https://telepathy.freedesktop.org/doc/telepathy-farstream/) + +## Tutorials & HOWTOs + +* [Telepathy Developer's Manual](https://telepathy.freedesktop.org/doc/book/) (*slightly outdated*) +* [[Documentation/Recipes]]: how to accomplish various tasks with the Telepathy API + +## Development + +* [[Coding Style|Documentation/Style]] + +## Features + +* [[Documentation/Tubes]] +* [[Documentation/Protocols Support]] +* [[Documentation/Gabble XEP]] + +## Formats + +* [[Documentation/File Formats]]: specification for Telepathy's file formats +* [[service-profile-v1]] + +## Misc + +* For developers interested in Telepathy within KDE, the [KDE Community Project Page](https://community.kde.org/KTp) provides more information. diff --git a/Documentation/File_Formats.mdwn b/Documentation/File_Formats.mdwn new file mode 100644 index 0000000..29af160 --- /dev/null +++ b/Documentation/File_Formats.mdwn @@ -0,0 +1,172 @@ + + +# File Formats + +[[!toc ]] + + +## Introduction + +This page describes the various file formats that Telepathy applications use. These files should be installed with the components they describe. + +These file formats are based on the XDG desktop file format. All keys and values are case sensitive. Unknown values are considered to be an error and the file may be ignored completely, unless otherwise specified. + +Where this document discusses names, they are required to be of the form `[a-z][a-z0-9-]*`, and must not end in a hyphen (`-`). + +When fields in a file are prefixed with an underscore (_) this means the field is translatable using the mechanisms defined for XDG desktop files format. + + +## File Locations + +Packages should install the files in `PREFIX/share/telepathy`, in a subdirectory depending on the file type. For example, a connection manager named "foo" should install a file `PREFIX/share/telepathy/managers/foo.manager`. `PREFIX` is typically `/usr` or `/usr/local`. + +Users of these files should search in directories listed in the `$XDG_DATA_HOME` and `$XDG_DATA_DIRS` variables, as specified in the [[XDG Base Directory Specification|http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html]]. + +Historically, the `$HOME/.telepathy` location was used; implementations supporting this location should search it before other locations. New implementations do not need to support this location. + +When searching for connection managers, channel handlers and profiles by name, the first file found should be used, given that directories are searched in descending order of importance. When a file cannot be read because of an error, the next file is used in order, until no more files are left, in which case it should be considered that no matching file was found. + +For example, assuming that `$XDG_DATA_HOME` and `$XDG_DATA_DIRS` are unset, an implementation looking up a connection manager called "badger" would look for the following files: + +* `$HOME/.telepathy/managers/badger.manager` (legacy; optional) +* `$HOME/.local/share/telepathy/managers/badger.manager` (`$XDG_DATA_HOME` default) +* `/usr/local/share/telepathy/managers/badger.manager` (`$XDG_DATA_DIRS` default) +* `/usr/share/telepathy/managers/badger.manager` (`$XDG_DATA_DIRS` default) + +## Connection Manager Files + +These are documented by [[the ConnectionManager section of the Telepathy specification|http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.ConnectionManager]]. + + +## Profile Files + +This section is a **DRAFT**. + + +### Purpose + +Each connection manager can provide one or more protocols. Each protocol can have different 'profiles'. + +A profile is a set of default key-value to be used as parameters in a connection manager for a particular (connection manager, protocol) pair. + +For example a connection manager providing jabber protocol, can also provide a profile for a Google talk connection (pre-setting ssl connection, stun server and jabber server). Another example can be an enterprise-deployed profile pre-setting some proxy and server foo, or stun server inside the enterprise. + +The MC should reason in terms of profiles rather than protocols. Each profile can have a translatable name and description (key prefixed with underscore as defined at the beginning of the document). + +Profiles without any key-value definitions are said to be 'vanilla' profiles. MC can choose to filter two equivalent profiles (same connection manager and protocol). A mechanism to filter out same protocols with different connection managers for a vanilla profile is up to the MC implementation, it can be just 'Take the first available one', or user-configurable prioritization. + +Non-vanilla profiles should all be presented, since there is no way to determine equivalence. + + +### Format + +Location: these files are located in the `profiles` subdirectory. + +Naming: the file name must end in `.profile`. + +The file must contain a section called "Profile". This section should contain all of the following keys: + +* `_Name`: the short name of the profile (=protocol most of the times). +* `_Description`: the description of the profile in free text. +* `Manager`: the connection manager on which this profile is defined. +* `Protocol`: the protocol name to use for this profile's defaults. The connection + * manager defined above must support this protocol +* `IconPath`: the path to the base icon for this profile. It should be in svg format to allow for + * several sizes and compositions to be generated. +Followed by any number of key-value for option defaults as follows: + +* Default-$name=$value + * $name is the name of the parameter to be set, as found in the corresponding +connection manager's .manager file + + * $value is the value to be set for the key while connecting. + +### Example + + +[[!format txt """ +[Profile] +Manager=gabble +Protocol=jabber +_Name=Google Talk +_Description=Google's Jabber Network +Icon=/usr/share/icons/googletalk.svg +Default-old-ssl=true +Default-server=talk.google.com +Default-old-ssl=true +Default-ignore-ssl-errors=true +Default-port=5223 +"""]] +This `.profile` file defines the profile for a Google Talk connection using Gabble's Jabber support. The UI can then display Google Talk as 'protocol' when one has to choose a protocol, and the configuration for the connection parameter values will be preset as defaults. + + +[[!format txt """ +[Profile] +Manager=salut +Protocol=link-local +_Name=Salut +_Description=Avahi Link-local messaging +Icon=/usr/share/icons/butterfly.svg +"""]] +This could be for example a vanilla profile for the link-local connection-manager using Avahi discovery. It is a vanilla profile because it doesn't contain any key-value definitions. + + +## Channel Handler Files + +This section is a **DRAFT**. + + +### Purpose + +These files are installed by telepathy components other than connection managers. Current examples include end-user clients, programs that need to sync incoming buddy-lists with anything, global logger program. + +The MC will read every available .chandler file and generate a list of activatable processes for each existing type of incoming channel. + +For example, if a logger program wants to be invoked each time a [[TextChannel|TextChannel]] is created, it will need to put a .chandler file stating the process dbus name to be invoked, the channel type on which to react. + +In the long term, this mechanism may be complemente or replaced by a full featured configurable process activation API, to allow the user or developper to choose with more fine-grain control what gets activated, maybe through match rules on more than the channel type, or any other mechanism. + + +### Format + +Location: these files live in the `chandlers` subdirectory. + +Naming: these files are named _name_.`chandler`. + +The file must contain a section called "[[ChannelHandler|ChannelHandler]]". This section should contain all of the following keys: + +* `BusName`: the dbus name of the activatable service to be triggered +* `ObjectPath`: the dbus object path of the activatable service +* `ChannelType`: the channel type string that will trigger the activation (as + * defined in the telepathy spec) to be matched against incoming channels. +* `HandleType`: a comma separated list of handle types (as strings defined in the telepathy spec, ie group/contact/...) to be matched against incoming channels. +For a channel handler to be activated, both [[ChannelType|ChannelType]] and [[HandleType|HandleType]] have to be matching. + + +### Example + + +[[!format txt """ +[ChannelHandler] +BusName=org.freedesktop.Telepathy.Cohoba.BigBrotherChannelHandler +ObjectPath=/org/freedesktop/Telepathy/Cohoba/BigBrotherChannelHandler +ChannelType=org.freedesktop.Telepathy.Channel.Type.Text +HandleType=contact,room +"""]] +The dbus service 'org.freedesktop.Telepathy.Cohoba.[[BigBrotherChannelHandler|BigBrotherChannelHandler]]' will be activated on each occurence of a Text channel. + + +### Invoked Method (FIXME) + +Each activatable channel handler service should implement the 'org.freedesktop.Telepathy.[[ChannelHandler|ChannelHandler]]' interface + + +[[!format txt """ +HandleChannel(s:conn_name, o:conn_obj, s:channel_type, o:chan_obj, u:handle_type, u:handle) -> void + conn_name: the telepathy connection dbus name + conn_obj: the telepathy connection dbus object path + channel_type: the channel type of the incoming channel as defined in the spec + chan_obj: the telepathy channel dbus object path of the incoming channel + handle_Type: the type of the handle as defined in the spec for the 'handle' argument + handle: the handle, when applicable, for the incoming channel +"""]]
\ No newline at end of file diff --git a/Documentation/Gabble_XEP.mdwn b/Documentation/Gabble_XEP.mdwn new file mode 100644 index 0000000..b1b3296 --- /dev/null +++ b/Documentation/Gabble_XEP.mdwn @@ -0,0 +1,81 @@ +# XEP status in gabble + +All XEP are available at: [[http://www.xmpp.org/extensions/|http://www.xmpp.org/extensions/]] + +* [[XEP-0004|http://www.xmpp.org/extensions/xep-0004.html]]: Data Forms + * Implemented, used internally for MUC configuration, registration, etc +* [[XEP-0020|http://www.xmpp.org/extensions/xep-0020.html]]: Feature Negotiation + * Implemented, used internally for stream initiation +* [[XEP-0030|http://www.xmpp.org/extensions/xep-0030.html]]: Service Discovery (Disco) + * Implemented, used for capabilities, MUC room listing, discovering components, server features, etc +* [[XEP-0045|http://www.xmpp.org/extensions/xep-0045.html]]: Multi-User Chat (MUC) + * Implemented, chat and room configuration, missing role support +* [[XEP-0047|http://www.xmpp.org/extensions/xep-0047.html]]: In-Band Bytestreams (IBB) + * Implemented, used by tubes +* [[XEP-0054|http://www.xmpp.org/extensions/xep-0054.html]]: vcard-temp + * Implemented, used for avatars and nicknames, contact info is WIP +* [[XEP-0055|http://www.xmpp.org/extensions/xep-0055.html]]: Jabber Search + * WIP +* [[XEP-0060|http://www.xmpp.org/extensions/xep-0060.html]]: Publish-Subscribe ([[PubSub|PubSub]]) + * Implemented partially, used internally for PEP +* [[XEP-0065|http://www.xmpp.org/extensions/xep-0065.html]]: SOCKS5 Bytstreams + * Implemented partially, used by tubes, relay support is WIP +* [[XEP-0077|http://www.xmpp.org/extensions/xep-0077.html]]: In-Band Registration + * Implemented +* [[XEP-0080|http://www.xmpp.org/extensions/xep-0080.html]]: User Location + * WIP +* [[XEP-0084|http://www.xmpp.org/extensions/xep-0084.html]]: User Avatar + * Implemented +* [[XEP-0085|http://www.xmpp.org/extensions/xep-0085.html]]: Chat State Notifications + * Implemented +* [[XEP-0095|http://www.xmpp.org/extensions/xep-0095.html]]: Stream Initiation + * Implemented, used by tubes +* [[XEP-0096|http://www.xmpp.org/extensions/xep-0096.html]]: File Transfer + * WIP +* [[XEP-0115|http://www.xmpp.org/extensions/xep-0115.html]]: Entity Capabilities + * [[Version 1.3 (legacy format)|http://www.xmpp.org/extensions/attic/xep-0115-1.3.html]] implemented + * Version 1.5 implemented +* [[XEP-0128|http://www.xmpp.org/extensions/xep-0128.html]]: Service Discovery Extensions + * Implemented, used internally for MUC room listing and configuration +* [[XEP-0153|http://www.xmpp.org/extensions/xep-0153.html]]: vCard-based Avatars + * Implemented +* [[XEP-0163|http://www.xmpp.org/extensions/xep-0163.html]]: Personal Eventing via Pubsub + * Implemented, used internally for nicknames, location, avatars, OLPC extensions, etc +* [[XEP-0166|http://www.xmpp.org/extensions/xep-0166.html]]: Jingle + * Implemented (mid-2007 and current drafts), used for audio/video calls +* [[XEP-0167|http://www.xmpp.org/extensions/xep-0167.html]]: Jingle RTP Sessions + * Implemented (mid-2007 and current drafts) implemented, used for audio/video calls +* [[XEP-0172|http://www.xmpp.org/extensions/xep-0172.html]]: User Nickname + * Implemented +* [[XEP-0174|http://www.xmpp.org/extensions/xep-0174.html]]: Serverless Messaging + * Implemented in [[Salut|Salut]] +* [[XEP-0176|http://www.xmpp.org/extensions/xep-0176.html]]: Jingle ICE-UDP Transport + * WIP +* [[XEP-0177|http://www.xmpp.org/extensions/xep-0177.html]]: Jingle Raw-UDP Transport + * WIP +* [[XEP-0249|http://www.xmpp.org/extensions/xep-0249.html]]: Direct MUC Invitations + * Implemented +* [[XEP-0276|http://www.xmpp.org/extensions/xep-0276.html]]: Temporary Presence Sharing + * Implemented, used automatically for audio/video calls + +## Vendor Extensions + +* Google Session (Voice and Video) + * Similar to Jingle +* Google P2P Transport + * Similar to ICE +* Google Jingle Info + * STUN and relay server discovery +* Google Roster + * For blocking +* Telepathy + * Tubes + * MUC bytestreams + * SI multiple (for falling back between SI methods) +* OLPC + * Buddy and Activity Info + * Gadget (server component for indexing buddies and activities) + +### Note + +This list is far for being complete, feel free to add informations diff --git a/Documentation/Protocols_Support.mdwn b/Documentation/Protocols_Support.mdwn new file mode 100644 index 0000000..53a694a --- /dev/null +++ b/Documentation/Protocols_Support.mdwn @@ -0,0 +1,37 @@ + + +## Protocol features supported by Telepathy implementations +[[!table header="no" class="mointable" data=""" + **Protocol name** | **Audio Chat** | **Video Chat** | **File transfer** | **Invisible mode** +AIM | No | No | No | No +[[GaduGadu|GaduGadu]] | No | No | No | Yes +Google Talk | Yes | Yes | Yes¹ | Yes +Groupwise | No | No | No | No +ICQ | No | No | No | No +IRC | N/A⁴ | N/A⁴ | No | N/A⁴ +Jabber | Yes | Yes | Yes | Yes (see below) +MSN | No³ | No³ | Yes | Yes +myspace | No | No | No | No +qq | No | No | No | No +Link-Local XMPP (People Nearby, Salut, Bonjour) | No² || | Yes | N/A⁴ +sametime | No | No | No | No +silc | No | No | No | No +SIP | Yes | Yes | No | No +Yahoo! | No | No | No | No +zephyr | No | No | No | No +"""]] + +1. Works with desktop Google Talk client, not iGoogle yet +1. This may change once parts of Gabble's Jingle code have been migrated to Wocky, and Salut ported to Wocky. +1. Audio/Video chat no longer works in MSN due to Microsoft removing the necessary servers. +1. Non Applicable, this feature don't exist in this protocol + +## Methods of being invisible on Jabber + +Gabble supports: + +* Google Talk's [[shared status extension|http://code.google.com/apis/talk/jep_extensions/shared_status.html]]; +* [[XEP-0186: Invisible Command|http://xmpp.org/extensions/xep-0186.html]]; +* [[becoming invisible using privacy lists|http://xmpp.org/extensions/xep-0126.html]]; +* the pre-XMPP [[<presence type='invisible'/> extension|http://xmpp.org/extensions/xep-0018.html]]. +This should mean, in practice, that Gabble supports being invisible on any Jabber server where it's possible to be invisible. (This, notably, does not include Facebook.) diff --git a/Documentation/Recipes.mdwn b/Documentation/Recipes.mdwn new file mode 100644 index 0000000..ff6abab --- /dev/null +++ b/Documentation/Recipes.mdwn @@ -0,0 +1,45 @@ + + +# Telepathy Recipes + +Simple overviews of how to accomplish various tasks with the Telepathy API. + + +## Register an account + +* Protocols which have accounts that can be registered automatically have a boolean "register" parameter. +* Call `RequestConnection` with `register=True`. +* If `Connect()` succeeds, registration has succeeded. +* Don't rely on the connection being usable after registretion is finished. + +## Send a text message + +* TODO + +## Make an audio call + +* `RequestHandle` +* `RequestChannel` +* (no longer necessary since spec 0.17.6: `AddMember`) +* `RequestStreams` +* handle `MembersChanged` +* handle `StreamError` +See also: [[Streamed Media|Streamed Media]] + + +## Block a contact + +* TODO + +## Look for installed connection managers + +* Call [[ListNames|ListNames]]() and [[ListActivatableNames|ListActivatableNames]]() on the D-Bus daemon +* Search in the results for names beginning with `org.freedesktop.Telepathy.ConnectionManager.` +* The rest of the bus name is the connection manager name +* tp_list_connection_managers() in telepathy-glib >= 0.7.1 implements this correctly + +## Reuse an existing connection + +* Search for names on the bus beginning with `org.freedesktop.Telepathy.Connection.` +* tp_list_connection_names() in telepathy-glib >= 0.7.1 implements this correctly +* If you want presence information, you can call `GetPresence` on the `subscribe` contact list to get cached presence information
\ No newline at end of file diff --git a/Documentation/Style.mdwn b/Documentation/Style.mdwn new file mode 100644 index 0000000..40d38e7 --- /dev/null +++ b/Documentation/Style.mdwn @@ -0,0 +1,262 @@ +This coding style is (or should be) used for all the core Telepathy components, notably telepathy-glib, libtelepathy, telepathy-gabble and telepathy-stream-engine. + +These are guidelines only; there are always exceptional circumstances. Consistency and readability are usually the most important considerations. + + +## C code using GLib/GObject + + +### Filenames + +* Don't put a common prefix on all files in a project - we like our tab completion to work. `<telepathy-glib/connection.h>` is good, `<telepathy-glib/tp-connection.h>` would be bad. +* If you're writing a library where headers will be included like `<foo/bar.h>`, put the headers (and probably corresponding sources) in a directory called `foo` (probably top-level). + * This way the library and its examples/tests can be compiled with `-I$(top_srcdir) -I$(top_builddir)` (or possibly `-I$(top_srcdir)/src -I$(top_builddir)/src` or something) and use `#include <foo/bar.h>` throughout, so that examples in the source tree have the same source code that they'd need in a third-party project. +* Code generation tools (copied from telepathy-glib) typically go in `./tools` +* autoconf macros usually go in `./m4`. This requires `AC_CONFIG_MACRO_DIR([m4])` in `configure.ac` **and** `ACLOCAL_AMFLAGS = -I m4` in the top-level `Makefile.am` (use both). + +### `#include`s + +If you're going to `#include "config.h"`, do that first, in case it defines things like `inline` or `_GNU_SOURCE`. + +Next, `#include` the header in which this .c file's API is declared. This guarantees that all public headers are self-contained. + +Next, `#define` any extra libc feature-test macros you need (`_GNU_SOURCE` etc.) and `#include` any C/POSIX standard library headers you need, in alphabetical order. + +Next, `#include` any headers you need from non-standard libraries (GLib, Gtk, telepathy-glib, Avahi, ...) in alphabetical order. + +Finally, `#include` any private (non-installed) headers from the library or program you're writing. + +For example: + + /* Example 1: foo.c + * ... insert copyright etc. here ... + */ + #include "config.h" + + #include "foo.h" + + #ifndef _POSIX_C_SOURCE + #define _POSIX_C_SOURCE 200112L /* for posix_memalign */ + #endif + #include <stdlib.h> + #include <string.h> + #include <sys/types.h> + + #include <avahi-common/address.h> + #include <glib-object.h> + #include <telepathy-glib/bar.h> + + #define DEBUG_FLAG DEBUG_FOO + #include "bar.h" + #include "debug.h" + #include "foobar.h" + +(Try to avoid using non-standard functions that need feature test macros - I've just used `posix_memalign` here for the sake of an example.) + +### Layout + +* Indentation is GNU-style: + + /* Example 2 */ + while (foo) + { + if (badger != NULL) + bar (); + + if (mushroom != NULL) + { + do_stuff (); + } + else + { + do_more_stuff (); + do_yet_more_stuff (); + } + } + +* Function _declarations_ (with `;` at the end) are in the style: + + /* Example 3 */ + static void badger_mushroom (Mushroom *self, + const gchar *reason, + gint another_param, + ..., + gpointer omg_so_many_params); + + but function _definitions_ (i.e. implementations, with `{}` and code) are in the style: + + /* Example 4 */ + static void + badger_mushroom (Mushroom *self, + const gchar *reason, + gint another_param, + ..., + gpointer omg_so_many_params) + { + ... + } + + (Rationale: that way you can grep for ^function_name and you'll only find the definition, without any clutter caused by declarations). + +* Function calls have a space after the function name. + +* Long lines (>79 chars) should be wrapped with a four-space indent and line-breaks between arguments in any sensible place, like this: + + /* Example 5 */ + static void + do_some_stuff (Mushroom *self) + { + do_some_other_stuff (self, 123, 42, TP_TYPE_MUSHROOM, + OTHER_STUFF_ADD_BADGERS | OTHER_STUFF_NO_SNAKES, + "this example has too many parameters", + CARROTS | HANDBAGS | CHEESE, + TABLET, BRICK, POTATO, LLAMA); + } + + * Exception: definitions (but not declarations) have exactly one parameter per line, with second and subsequent lines indented to match first line, like Example 4 + +* Pairs or triples of arguments (as seen in g_object_new, g_object_get, tp_value_array_unpack etc.) should always be one pair/triple to a line, even if the line is short enough to fit more: + + m = g_object_new (G_TYPE_MUSHROOM, + "species", "Badger Agaric", + "flags", SPOTTED | POISONOUS, + NULL); + + even if the number of pairs in a particular invocation is zero: + + m = g_object_new (G_TYPE_MUSHROOM, + NULL); + +### Naming + +General rules are not defined yet. See [[telepathy-glib specific rules|TelepathyGLib]]. + +### configure.ac + +Use AS_IF and AS_CASE instead of shell conditionals: + + # don't do this... + if test "x$with_badgers" = "xyes"; then + AC_MSG_NOTICE([Badgers enabled]) + else + AC_MSG_NOTICE([Badgers not enabled]) + fi + case "x$with_mushrooms" in + (*poison*) + AC_MSG_ERROR([Poisonous mushrooms selected]) + ;; + (*magic*|*hallucinogen*) + AC_MSG_WARN([Hallucinogenic mushrooms selected]) + ;; + (*) + AC_MSG_NOTICE([Ordinary mushrooms selected]) + ;; + esac + + # ... do this instead (in this case it's equivalent, but + # the difference matters in more complicated situations) + AS_IF([test "x$with_badgers" = "xyes"], + [echo "with badgers"], + [echo "without badgers"]) + AS_CASE(["x$with_mushrooms"], + [*poison*], + [AC_MSG_ERROR([Poisonous mushrooms selected])] + [*magic*|*hallucinogen*], + [AC_MSG_WARN([Hallucinogenic mushrooms selected])] + [*], + [AC_MSG_NOTICE([Ordinary mushrooms selected])]) + +See <https://bugzilla.gnome.org/show_bug.cgi?id=681413> for more info. + +### Makefiles (including Automake Makefile.am) + +List include directories (`CFLAGS`/`CPPFLAGS`) and libraries (`LDADD`/`LIBS`) in stack order, with lowest in the stack first (so one can link against highest in the stack somewhere else without picking up everything from the somewhere else). (This guideline was borrowed from gstreamer.) + +As an exception, any libraries or `CFLAGS` within the same source tree (e.g. `-I$(top_srcdir)`) must come before external `CFLAGS`. This is necessary to compile against uninstalled libraries correctly, if they have directories that conflict with directories in your project (e.g. Gabble and telepathy-glib both have `/extensions`), and to prefer linking against the library you just compiled instead of a system-wide copy. + + # Example 6 + AM_CFLAGS = \ + -I$(top_srcdir) -I$(top_builddir) \ + -I$(top_srcdir)/src \ + $(DBUS_CFLAGS) \ + $(GLIB_CFLAGS) \ + $(DBUS_GLIB_CFLAGS) \ + $(TP_GLIB_CFLAGS) + + something_LDADD = \ + $(top_builddir)/src/libmiscutils.la \ + $(DBUS_LIBS) \ + $(GLIB_LIBS) \ + $(DBUS_GLIB_LIBS) \ + $(TP_GLIB_LIBS) + +### Misc + +* Use glib types for preference. +* Pointer types look like `Type *variable`, not `Type* variable`, so that the whitespace suggests the correct C precedence: `int *foo, bar;` and `int bar, *foo` and `int* foo, bar` all declare `foo` to be an `int *`, and `bar` to be an `int`. +* Don't declare variables of type `int` and `int *`, or `gchar *` and `gchar **`, or similar, in the same declaration: it's possible but needlessly confusing. +* Casts look like this: + + Fungus *fungus; + Mushroom *mushroom; + + mushroom = MUSHROOM (fungus); + /* or if there's no suitable asserting macro or if the cast is from + * a subclass to a superclass, */ + mushroom = (Mushroom *) fungus; + +* Use `gchar *` for strings that should be freed with `g_free`, but `char *` for strings that should be freed with something else, such as libc `free` or `avahi_free`. +* Use the `G_GNUC_*` function annotations where possible. +* Use GSlice allocation for non-GObjects where possible. +* Use `g_set_error` instead of `g_error_new` where possible. +* Never use explicit comparisons with `TRUE` and `FALSE` for booleans - if have_value is a `gboolean`, use `if (have_value)` instead of `if (have_value == TRUE)`. +* Always use explicit comparisons for non-boolean integers and for pointers - if `i` is an integer and `p` is a pointer, use `if (i != 0)` instead of `if (i)`, and `if (p != NULL)` instead of `if (p)`. + +### Telepathy-GLib specific rules + +See [[Style/TelepathyGLib]] + +### GNU Indent + +This command line doesn't exactly produce Telepathy style (and please do not run it over any existing codebase without very specific maintainer approval!), but it's a reasonable first approximation: + + indent -bad -bap -cdb -sc -bl -bli2 -cli0 -cbi2 -cs -bs -saf -sai -saw -di1 \ + -nbc -psl -bls -blf -ci4 -ip4 -ppi2 -il0 -l78 -bbo + +## Python + +See [[PEP 8|http://www.python.org/dev/peps/pep-0008/]]. + +Indentation should always be 4 spaces. + +## C++ code using Qt + +telepathy-qt is meant to be in the [kdelibs coding style](https://community.kde.org/Policies/Kdelibs_Coding_Style). + +The same Makefile, `#include` and filename guidelines as for C/GLib/GObject (above) apply to C++. + +## Emacs C Mode + +Adding the following to your `.emacsrc` creates a Telepathy style for you: + + (defun telepathy-c-initialization-hook () + (c-add-style "telepathy" + '("gnu" + (indent-tabs-mode . nil) + (c-offsets-alist + (arglist-intro . 4) + (arglist-cont-nonempty . 4))))) + + (add-hook 'c-initialization-hook 'telepathy-c-initialization-hook) + +You can also set telepathy style as default: + + (setq c-default-style "telepathy") + +## Vim Configuration + +Adding the following to your `.vimrc` should help with adherence to these guidelines: + + set cinoptions=>2s,{1s,n-s,^-s + autocmd FileType python setlocal textwidth=78 tabstop=4 softtabstop=4 shiftwidth=4 expandtab + autocmd FileType c setlocal textwidth=78 tabstop=4 softtabstop=2 shiftwidth=2 expandtab cindent diff --git a/Documentation/Style/TelepathyGLib.mdwn b/Documentation/Style/TelepathyGLib.mdwn new file mode 100644 index 0000000..177e401 --- /dev/null +++ b/Documentation/Style/TelepathyGLib.mdwn @@ -0,0 +1,26 @@ + + +# Telepathy-GLib specific coding style + +Those policies have been discussed on bug [[#39189|https://bugs.freedesktop.org/show_bug.cgi?id=39189]]. Those are not global rules we want to apply on all our projects, but rather a compromise given the history of existing telepathy-glib API. They could change in a distant future if we decide it is important to be threadsafe (maybe after porting to gdbus). + + +## Transfer policy + +* tp_foo_get_bar() must return the internal pointer/value. No copy is made. +* tp_foo_dup_bar() must return a new ref or deep-copy. +* tp_foo_borrow_bar() should not be used. +* tp_foo_bar_finish() must return a new ref or deep-copy return value and out args. +* Since _finish() returns a copy, tp_foo_dup_bar_async() should be prefered over tp_foo_get_bar_async(). + +## Container policy + +telepathy-glib uses either GList or GPtrArray, it is left to developer's choice. The most important to keep in mind is to use the most convenient format given the existing APIs. For example it is preferable to return a set of contacts as a GPtrArray because tp_connection_upgrade_contacts_async() takes a C-array + length. + +* GPtrArray must always be used in a way that reffing it is enough to keep the container AND its elements, and unreffing it is enough to 'unown' the container AND its elements. In most case this means that the array must own its elements and have a free_func set, and g_ptr_array_free() must never be used. Returning such GPtrArray, if not retunring the internal pointer, must be annotated with "transfer container" and the function name must be tp_foo_dup_bar(). +* GHashTable is similar to GPtrArray case. +* When returning a GList, if not returning the internal pointer, it must be deep-copied, annotated with "transfer full", and function name must be tp_foo_dup_bar(). + +## Unsure? + +tp_foo_dup_bar() it is! diff --git a/Documentation/Tubes.mdwn b/Documentation/Tubes.mdwn new file mode 100644 index 0000000..9fdec35 --- /dev/null +++ b/Documentation/Tubes.mdwn @@ -0,0 +1,109 @@ + +**Tubes** are Telepathy's mechanism for supporting arbitrary data transfer and remote IPC. + +Tubes are contact-to-contact networking. Tubes enable one-to-one, one-to-many or many-to-many communication between contacts using either network sockets (stream tubes) or a private D-Bus bus (D-Bus tubes). This allows applications to support collaboration between users, with a minimal amount of effort on the part of both application developers and the end-user. Application developers can now focus on their application protocols, without having to worry about networking, firewall traversal or service discovery. End users no longer have to configure collaboration accounts, share IP addresses or forward ports on their firewalls. + +Here’s how it works. An application implements the Client.Handler interface, handling channels matching: + + { "...TargetHandleType": Contact, + "...ChannelType": "...StreamTube", + "...StreamTube.Service": "sudoku", + } + +Or, if the application uses D-Bus tubes: + + { "...TargetHandleType": Contact, + "...ChannelType": "...DBusTube", + "...DBusTube.Service": "org.gnome.sudoku", + } + +While the application is running, all connections will advertise that the user supports Sudoku tubes to contacts subscribed to the user's presence. (To advertise support while the application is not running, it must be made service-activatable and install a .client file.) + +If Alice wants to play Sudoku against Bob, her Sudoku client requests a list of all her contacts who advertise the Sudoku Tube capability. She selects Bob; his Channel Dispatcher receives an incoming channel and passes it to an Approver which displays a dialog to Bob asking if he would like to play a game of Sudoku against Alice. Assuming he approves the channel, his Channel Dispatcher then passes the channel to the recommended Handler (the game client) which can then accept the Tube. At this point their two Sudoku applications are now connected via the Internet. + +[The Telepathy Connection Manager takes care of the precise method of connection, utilising whatever technologies are available with the given communications protocol.] + + +## XMPP XEP + +[[XEP-proto-tubes: Tubes over XMPP|http://telepathy.freedesktop.org/xmpp/tubes.html]] + + +## Support +[[!table header="no" class="mointable" data=""" + Old API | **One-to-one** | **Group** + **D-Bus tubes** | Gabble | Gabble, Salut + **stream tubes** | Gabble | Gabble, Salut +"""]] +[[!table header="no" class="mointable" data=""" + New API | **One-to-one** | **Group** + **D-Bus tubes** | Gabble | Gabble + **stream tubes** | Gabble | Gabble +"""]] + +**Stream tubes** are useful for applications that already uses TCP because the application protocol does not need to be changed to use Telepathy tubes. Applications that uses **D-Bus tubes** need to have a specific protocol. Applications can use several types of tubes. + +**Stream tubes** currently means TCP. UDP tubes may be added in the future. + +When a contact A offer a stream tube in a chatroom, it's equivalent to listening on a TCP socket with listen()/accept(). Then anyone in the chatroom who can see the stream tube can connect to that socket as a client. For 1-1 stream tubes only one person can see the tube, but the applications can still connect to contact A multiple times. So it's really a factory for 1-1 connections. If the contact A is offering httpd over a tube, the other contact's firefox instance can open multiple tcp connections to the httpd. + +IB means **In Band**. The tubes' data use the same path as other messages. For XMPP (Gabble) it means the tubes' data is encapsulated in XML stanza and sent to a jabber server. It could be very slow for applications like VNC. + +OOB means **Out Of Band**. The tubes' data use a different path than other messages. The tubes' data is sent directly to the remote contact. + + +### Gabble + +One-to-one D-Bus tubes +: +[[Stream initiation|http://www.xmpp.org/extensions/xep-0095.html]] and [[SOCKS5|http://xmpp.org/extensions/xep-0065.html]] if possible; [[In Band Bytestream|http://www.xmpp.org/extensions/xep-0047.html]] (<message>s containing base64) if not. + + +Group D-Bus tubes +: +Some kind of In Band Bytestream in a MUC. See [[the pseudo XEP|http://people.collabora.co.uk/~smcv/muc-bytestream.html]]. + + +One-to-one stream tubes +: +For each tube connection: [[Stream initiation|http://www.xmpp.org/extensions/xep-0095.html]] and [[SOCKS5|http://xmpp.org/extensions/xep-0065.html]] if possible; [[In Band Bytestream|http://www.xmpp.org/extensions/xep-0047.html]] if not. + + +Group D-Bus tubes +: +For each tube connection: [[Stream initiation|http://www.xmpp.org/extensions/xep-0095.html]] and [[SOCKS5|http://xmpp.org/extensions/xep-0065.html]] if possible; [[In Band Bytestream|http://www.xmpp.org/extensions/xep-0047.html]] if not. + + +### Salut + +One-to-one D-Bus tubes +: not implemented + +One-to-one stream tubes +: for each tube connection: direct TCP connection + +Group D-Bus tubes +: raw data using the Clique protocol + +Group Stream tubes +: +for each tube connection: [[Stream initiation|http://www.xmpp.org/extensions/xep-0095.html]] and P2P connections (ab)using the [[OOB protocol|http://www.xmpp.org/extensions/xep-0066.html]] + + +### Properties of D-Bus MUC Tubes + +Total ordering +: Yes + +No message loss +: Yes + +Ordering in membership change by DBusNamesChanged +: ? - does all participants receive the changes of membership in the same order? (except the one who just joins of course) + +Atomicity in membership change by DBusNamesChanged +: ? - when several participants join or leave "at the same time", does all participants receive the same content of DBusNamesChanged? Are they grouped in the same manner? (except the one who just joins of course) + +Ordering between membership change by DBusNamesChanged and messages on the d-tube +: No. It cannot, it is not the same socket + diff --git a/Download.mdwn b/Download.mdwn new file mode 100644 index 0000000..1d82705 --- /dev/null +++ b/Download.mdwn @@ -0,0 +1,6 @@ + +Here are [[tarball releases|http://telepathy.freedesktop.org/releases/]] of the source code for the various telepathy modules. + +Telepathy is packaged officially by major Linux distributions, so you should rarely need to build Telepathy from source code yourself. + +People developing the telepathy source code itself should see our [[Source Code Repository|Git]]. diff --git a/FAQ.mdwn b/FAQ.mdwn new file mode 100644 index 0000000..be597a8 --- /dev/null +++ b/FAQ.mdwn @@ -0,0 +1,45 @@ + + +## Frequently Asked Questions + +See also the [[Empathy FAQ|http://live.gnome.org/Empathy/FAQ]] + + +### Do telepathy and empathy support voice calls between more than 2 people at the same time using jingle? + +Not yet, but there is work going on to support it. See [[Muji|http://telepathy.freedesktop.org/wiki/Muji]] + + +### How can I get the logs for Telepathy applications? + +See the [[Empathy debugging page|http://live.gnome.org/Empathy/Debugging]] on live.gnome + + +### Is File Transfer compatible with the GTalk desktop client? + +Not yet, but there is work going on to support their dialect of Jingle file transfers. + + +### Does Telepathy support audio and video chat with the GTalk web client (the one embedded in Gmail)? + +Audio works, as does video if you install H.264 codecs. + + +### Does empathy support end to end encryption? + +Implementation of end to end encryption is in progress. The plan is to implement [[XEP-0246|http://xmpp.org/extensions/xep-0246.html]] ([[current API sketch|http://lists.freedesktop.org/archives/telepathy/2009-October/003936.html]]). + + +### Where can I find documentation on how to develop with Telepathy? + +The [[Telepathy Developer Manual|http://people.collabora.co.uk/~davyd/telepathy-book/]] which is still a WIP. It is also useful to always have the [[Telepathy Specification|http://telepathy.freedesktop.org/spec/]] under the hand as a reference. + + +### Does Telepathy work on Windows? + +Not really, but people are working on it ([[Telepathy On Windows|http://telepathy.freedesktop.org/wiki/Windows]]). + + +### TelepathyQt4 isn't working; I get errors like “QDBusPendingReply: type Tp::UIntList is not registered with QtDBus” + +Make sure you've called `Tp::registerTypes()` from your `main()` function (or at least before you call any [[TelepathyQt4|TelepathyQt4]] methods). diff --git a/Git.mdwn b/Git.mdwn new file mode 100644 index 0000000..d4495f6 --- /dev/null +++ b/Git.mdwn @@ -0,0 +1,100 @@ + +Telepathy uses [[git|http://git.or.cz/]]. + +You can browse the source code via the [[Telepathy gitweb|http://cgit.freedesktop.org/telepathy/]]. That site's "summary" links also list the URLs for both anonymous access (git://) and developer access (git+[[ssh://|ssh://]]) for individual modules. + +[[!toc ]] + + +## Checking out the source code + +If you want bleeding-edge code, (or if you want to help out with development of Telepathy), you can check out the source code from git. Of course, you might prefer to use our [[Source Code Tarballs|Download]]. + +Anybody can checkout the latest source code anonymously with a command such as the following: + + +[[!format txt """ +git clone git://anongit.freedesktop.org/telepathy/telepathy-glib +"""]] +You can commit changes to your local repository but will not be able to push them to the central repository. + +**If you are a developer** with an ssh account in the `telepathy` group and would like to be able to push your changes to the central repository, please clone the main repository on the server to your public_html, to have a public repository of your own, then clone _that_ to your development machine. See "Working on an existing git repository" below. + + +## Help for git beginners + +If you are not familiar with git, these links might be useful. + +* See [["Using Git"|http://www.cairographics.org/cairomm/]] on the cairomm page. + + +## Working on an existing git repository + +(This workflow gives you a personal repository to point people towards for code review, and avoids the problem of accidentally pushing unreviewed changes to the central repository.) + +Replace the values of PROJECT, USERNAME and OTHERUSER as appropriate. + + +[[!format txt """ +# on dhansak: create your personal repository +PROJECT=telepathy-glib +mkdir -p ~/public_html/git +cd ~/public_html/git +git clone --bare git://anongit.freedesktop.org/telepathy/$PROJECT $PROJECT.git + +# on your laptop: check out a copy +PROJECT=telepathy-glib +USERNAME=foo +git clone git+ssh://git.collabora.co.uk/home/$USERNAME/public_html/git/$PROJECT.git $PROJECT +cd $PROJECT +git remote add upstream ssh://git.freedesktop.org/telepathy/$PROJECT +# if you are interested in unreviewed code published by other users, e.g. smcv: +OTHERUSER=smcv +git remote add smcv git+ssh://git.collabora.co.uk/git/user/$OTHERUSER/telepathy-glib.git +git config remote.$OTHERUSER.tagopt --no-tags +git remote update + +# on your laptop: do some work on a new branch, and publish it +git checkout -b bug-12345 master +vim something.c +make check +git commit -a +git push --all + +# on your laptop: (for committers only) once your code is reviewed, merge it +git checkout master +git remote update upstream +git merge upstream/master # this should always be a "fast-forward" merge +git merge bug-12345 +git push upstream master + +# on your laptop: (for committers only) review and merge someone else's code (e.g. smcv's bug-54321 branch) +git remote update smcv +gitk # and look at changes in refs/remotes/smcv/bug-54321 +git checkout master +git remote update upstream +git merge upstream/master +git merge smcv/bug-54321 +git push upstream master +"""]] + +## Setting up a shared git repository + +/!\ **Warning:** previous instructions have been wrong + +Official repositories should be requested from Freedesktop.org admins. + +* Set up an empty Git repo: + * [[!format txt """ +mkdir /srv/git.collabora.co.uk/git/project_name.git +cd /srv/git.collabora.co.uk/git/project_name.git +chgrp telepathy . +git init --bare --shared=group +"""]] +* Make post-update hook executable (for http support) +* Edit telepathy-foo.git/config and add the commits mailing list: + * [[!format txt """ +[hooks] + mailinglist = telepathy-commits@lists.freedesktop.org +"""]] + * Move the old post-receive script out of the way (e.g. post-receive.orig) and replace it with a symlink to /srv/git.collabora.co.uk/hooks/post-receive
\ No newline at end of file diff --git a/Haze_FAQ.mdwn b/Haze_FAQ.mdwn new file mode 100644 index 0000000..5c2ad1a --- /dev/null +++ b/Haze_FAQ.mdwn @@ -0,0 +1,11 @@ + + +## Can I use pidgin-facebookchat/msn-pecan/(insert third-party prpl here) with Haze? + +Kind of. Currently, you'll need to patch `haze.manager`, and add a `.profile` file for the protocol. (This is vaguely outlined on [[this bug report|https://bugs.freedesktop.org/show_bug.cgi?id=17907]].) + +Non-standard protocols will not be added to `haze.manager`. The `.manager` files are intended just to be a cache of what [[ListProtocols()|http://telepathy.freedesktop.org/spec/org.freedesktop.Telepathy.ConnectionManager.html#org.freedesktop.Telepathy.ConnectionManager.ListProtocols]] would return if the CM was running. Since Haze uses libpurple, which loads plugins at runtime, this cache is basically broken. Sadly, current Telepathy clients depend on the presence of a `.manager` file for a CM, so Haze ships the best it can: the set of protocols shipped as standard with libpurple. This means that you can be reasonably sure that if `haze.manager` says a protocol's available, it'll be available when the CM's running. Adding non-standard protocols would break this. + +Correct clients should react to a missing `.manager` file by firing up the CM and interrogating it. `TpConnectionManager` in [[Telepathy GLib|Components/Telepathy GLib]] now does this correctly. Sadly, Mission Control 4 (as used by Empathy) does this wrong. When Empathy moves to Mission Control 5 (which should be in time for Gnome 2.28) then this will all work and `haze.manager` can be deleted. + +Sorry for any inconvenience caused. diff --git a/NewHome.mdwn b/NewHome.mdwn new file mode 100644 index 0000000..531943b --- /dev/null +++ b/NewHome.mdwn @@ -0,0 +1,58 @@ + +[[!img Telepathy.png]] + +Telepathy is a flexible, modular communications framework that enables real-time communication via pluggable protocol backends. Telepathy is a **communications service** that can be accessed by many applications ("clients") simultaneously. + +This allows any application to access presence information, request a communications channel (potentially handled by another client), or collaborate contact-to-contact. + +Telepathy provides protocol backends for most popular protocols including: Jabber/XMPP/Jingle, link-local XMPP, SIP, Yahoo/AIM and IRC via a unified [[D-Bus|http://dbus.freedesktop.org]] API. It also provides convenience libraries for GLib and Qt to simplify using the API from applications. + +Telepathy exposes the available real-time communications capabilities of each protocol: presence, contact rosters, text chat, voice and video over IP, file transfer and [[Telepathy Tubes|Documentation/Tubes]]. + + [[!img TelepathyArchitectureOverview.png]] + +Telepathy is **[[modular|Rationale]]**. Each backend and client runs in a separate process, allowing for much greater security and resilience. It is suitable both for embedded and desktop environments. + +# Using Telepathy + +## End users + +Telepathy is a *framework*, therefore it is mainly targetted to developers that want to enable real-time communication and collaboration features in their applications. + +As an end user, you can make use of one of the *Clients* of Telepathy, which are listed in the Clients section of the [[Components|Components]] page. + +## Developers + +Take a look at: + +* the [Telepathy Developer's Manual](https://telepathy.freedesktop.org/doc/book/) (*slightly outdated*) +* the [[DBus API Spec|DbusSpec]] + +Choose and [[download|Download]] a high-level library to use: + +* [[Telepathy GLib|Components/Telepathy GLib]] +* [[Telepathy Qt|Components/Telepathy Qt]] + +Check out misc useful information for developers: + +* [[Debugging|Debugging]] +* [[Developer Notes|DeveloperNotes]] + +[[Report Bugs|Bugs]] + +# Developing Telepathy + +* Checkout the code from our [[Source Code Repository|Git]] +* Take a look at [[bug reports|Bugs]], especially if you are looking for a good place to start hacking on Telepathy +* [[Debugging]]: how to obtain information when things break +* [[Coding style recommendations|Style]] for Telepathy implementations +* Familiarize with our [[review procedure|Review Procedure]] +* See our [[roadmap|Roadmap]] + +# Discuss Telepathy + +* [Mailing list](http://lists.freedesktop.org/mailman/listinfo/telepathy) +* IRC channel: `#telepathy` on `irc.freenode.net` + + +This wiki is undergoing [[conversion]]. If you have a fd.o shell account, you can help! diff --git a/Rationale.mdwn b/Rationale.mdwn new file mode 100644 index 0000000..4517dd9 --- /dev/null +++ b/Rationale.mdwn @@ -0,0 +1,11 @@ + +Why does Telepathy take a modular approach to real time communications? + +* **Robustness**: one component can crash without crashing others +* **Ease of development**: components can be replaced within a running system; tools like dbus-inspector can trace interactions between components +* **Language independence**: components can be written in any language that has a D-Bus binding; if the best free implementation of the Oscar (AOL) protocol is in Java, you can write your Oscar connection manager in Java to take advantage of that +* **Desktop independence**: D-Bus has been adopted as an IPC mechanism by both GNOME and KDE +* **License independence**: components can be under different licenses that would be incompatible if all components were running in one process +* **Code reuse**: Telepathy allows clients to ignore protocol details as much as possible, easing transitions between different communications systems +* **Connection reuse**: multiple Telepathy components can use the same connection simultaneously +* **Security**: components can run with very limited privileges; a typical connection manager only needs access to the network and to the D-Bus bus, making it possible for an SELinux policy to prevent protocol code from e.g. accessing the disk
\ No newline at end of file diff --git a/Review_Procedure.mdwn b/Review_Procedure.mdwn new file mode 100644 index 0000000..841a088 --- /dev/null +++ b/Review_Procedure.mdwn @@ -0,0 +1,48 @@ + +All patches to Telepathy components are reviewed by (hopefully) more experienced developers of the components to ensure that they meet standards of code quality, understandability and maintainability. + + +# Procedure + +* Record your changes in a Git branch. See [[Git|Git]] for details on how to get started. +* Publish your branch online somewhere; we suggest [[requesting a freedesktop.org account|http://wiki.freedesktop.org/wiki/AccountRequests]], or you can use your own webspace or any public git hosting site (gitorious, github etc.). +* Ping one of the reviewers listed below with your branch URL, on IRC, by e-mail to the mailing list, or in a bug with the 'patch' keyword (using a bug is recommended for complex patches or if we don't respond to IRC pings). The reviewer may ask you some questions and ask you to make some changes to your patch. +* When they approve it, you can commit it if you have access, or the reviewer may commit it for you. + +# Reviewers + +The maintainer is responsible for making or delegating releases, and decides who can be a reviewer. Most reviewers can be found on #telepathy. + +When reviewing, please pay attention to [[Style] and [[Portability|Style] and [[Portability]]. + +To review a patch in a bug, comment on it, and then in the whiteboard mark review+ or review- + +[[All fd.o Telepathy bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] +[[!table header="no" class="mointable" data=""" + **Module** | **Maintainer** | **Other reviewers** | **Bugzilla review queue** + empathy | cassidy | Zdra, danni, sjoerd, jonnylamb, Cosimoc | [[Empathy patch report|https://bugzilla.gnome.org/page.cgi?id=patchreport.html&product=empathy&patch-status=none]] + papyon | lfrb | [[KaKaRoTo|KaKaRoTo]], istaz | [[papyon bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=papyon&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + telepathy-butterfly | jonnylamb | istaz | [[butterfly bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=butterfly&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + telepathy-doc | danni | ... | + telepathy-farsight + telepathy-farstream | ocrete | ... | + telepathy-gabble | smcv | Robot101, cassidy, wjt, ptlo, daf | [[gabble bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=gabble&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + telepathy-glib | smcv | Robot101, wjt, ... | [[tpglib bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=tp-glib&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + telepathy-haze | wjt | jonnylamb, smcv (when he's not busy with all his other components), Robot101 (when he's feeling masochistic), Maiku | + telepathy-idle | wjt | oggis, sjoerd, jonnylamb, smcv | + telepathy-inspector | smcv | sjoerd | + telepathy-logger | stormer | pochu, danni | [[Logger's bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=logger&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + telepathy-mission-control | smcv | mardy, ... | + telepathy-pinnochio | treitter | ... | + telepathy-python | cassidy | jonnylamb | + telepathy-qt4 | smcv | andrunko, oggis | [[tpqt4 bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=tp-qt4&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + telepathy-salut | sjoerd | ... | + telepathy-sofiasip | mikhailz | ptlo | + telepathy-spec | Robot101/smcv | the telepathy-spec cabal¹ | [[spec bugs with patches|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&product=Telepathy&component=tp-spec&keywords_type=allwords&keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] + tictactube | epmf | (none) | +"""]] + + +### Notes + +1. substantial telepathy-spec changes should usually be discussed by several component maintainers diff --git a/Roadmap.mdwn b/Roadmap.mdwn new file mode 100644 index 0000000..d37b870 --- /dev/null +++ b/Roadmap.mdwn @@ -0,0 +1,84 @@ + +Status of planned changes and additions to the Telepathy API. + + +## 6.0 + +The full initial proposal is here: [[http://lists.freedesktop.org/archives/telepathy/2011-May/005525.html|http://lists.freedesktop.org/archives/telepathy/2011-May/005525.html]] + +Summary: Actually, I'm not going to try summarising. Please read the proposal above before continuing. + +telepathy-core version number is higher than the version number of everything in it, and MC is currently on version 5.x. + +Steps to get there: + +* 5.91 -- release everything as one module as-is. + * <wjt> i broadly think that being able to release the components as they currently stand all at once is a good step 1 + * Drive tp-qt4's CMake-based build system from autotools. + * thing to watch out for: support for being recursed into and doing all the things automake wants to do recursively, either in- or out-of-tree ([[https://bugs.freedesktop.org/show_bug.cgi?id=32299|https://bugs.freedesktop.org/show_bug.cgi?id=32299]] --smcv's spec as submodule work) + * Use git-subtree and lots of git-merge to keep everything up to date. + * Directory structure would look like (courtesy of smcv, but not including the CMs): + +[[!format txt """ + ${top_srcdir} + \- configure.ac (top level) + \- doc/ + \- glib/ + \- qt4/ + \- examples/ + \- glib/ + \- qt4/ + \- mission-control/ + \- mission-control-plugins/ + \- m4/ + \- spec/ + \- Account.xml (etc.) + \- telepathy-farstream/ + \- telepathy-glib/ + \- TelepathyQt4/ + \- Farstream/ + \- tests/ + \- lib + \- glib + \- qt4 + \- mc + \- account-manager + \- dispatcher + \- tools/ +"""]] +* 5.93 -- deprecate fragile API/ABI + * Kill off telepathy-glib/svc-* and move them to telepathy-glib-dbus-vX (? see Open Questions below) + * The equivalent change in tp-qt4 + * I'm not sure proxy.h goes to tp-glib-dbus-vX, because that API needs to be exposed by tp-glib high-level. that would mean tp-glib-dbus ABI breakage would break tp-glib too, no? -- Xavier Claessens + * Good point (my memory of what is generated and what isn't is unreliable) Fixed. -- alsuren + * Kill telepathy-glib/tp-cli-* too -- Xavier Claessens + * Kill off telepathy-core/telepathy-python/src/client. + * Kill off fully-qualified property names used in channel requests + * ensureTextChannel()-style methods on accounts and contacts -- (wjt [[http://lists.freedesktop.org/archives/telepathy/2011-June/005556.html|http://lists.freedesktop.org/archives/telepathy/2011-June/005556.html]]) + * Since we are breaking tp-glib API/ABI, consider removing its deprecated APIs and some guarantees: + * tp_account_prepare_async, tp_account_manager_prepare_async are replaced by tp_proxy_prepare_async, I would like those APIs to be modified so preparing AM takes features of account, connection and contacts (See [[https://bugs.freedesktop.org/show_bug.cgi?id=26205#c19|https://bugs.freedesktop.org/show_bug.cgi?id=26205#c19]]) + * Stop [[TpContact|TpContact]] from taking a strong ref on its [[TpConnection|TpConnection]] (See [[https://bugs.freedesktop.org/show_bug.cgi?id=26205#c26|https://bugs.freedesktop.org/show_bug.cgi?id=26205#c26]]) + * Stop emitting "invalidated" signal from [[TpProxy|TpProxy]]'s dispose +* 5.97 -- test API/ABI breakage mechanisms + * Rename the spec namespaces to vX and ensure that the mechanisms for demanding a restart on spec version mismatches work (make no other spec changes here) +* 6.0 -- telepathy-not-1.0 + * Copy-paste code into one big git tree (no submodules going forward: they're far too much of a pain in the ass to work with. Don't make any attempt to preserve history: just refer everyone to the commit id of each submodule that was imported) + * rename the spec namespace to vY just for fun. +* 6.x -- things that would be nice to happen, but shouldn't block 6.0 from happening (?) + * GDbus rewrite of tp-glib + * Rename the spec namespace again, and delete *all* of the deprecated spec stuff. +* 7.0 -- Things that would be nice to do API but may not actually happen + * Kill off [[TpHandle|TpHandle]]? -- (wjt [[http://lists.freedesktop.org/archives/telepathy/2011-June/005556.html|http://lists.freedesktop.org/archives/telepathy/2011-June/005556.html]]) +Open Questions + +* How long do we use submodules for, or do we force everyone to port all of their changes to telepathy-core by hand, from the first day of the project? +* What do we do with the media streaming stuff? Does tpfs get included in tp-core? +* I'm not quite sure how the mechanism for breaking the tp-glib-dbus apis are supposed to work. Here are a few proposals: + * Make each CM author #include <telepathy-glib-dbus-vX/svc-channel.h>, and sed *all of their source code* to update from version X to version Y. + * Same as above, but if the channel interface hasn't changed between vX and vY, generate <telepathy-glib-dbus-vX/svc-channel.h> which #includes <telepathy-glib-dbus-vY/svc-channel.h>. This would avoid too many bullshit sed commits for unchanged files, and encourage users to actually check what's changed on a per-file basis rather than blindly sedding and hoping for the best. + * Let CM authors #include <telepathy-glib-dbus/svc-channel.h> as long as they have defined the macro TP_DBUS_VERSION=X. This would let CM writers simply check their code for compat by hand and bump the version number to assert that it's all correct. + * Same as the above, but (e.g.) #define tp_svc_channel_interface_* so that each function only produces a compiler warning if its semantics has been broken between version X and version Y and it is *actually used* (more fine-grained than the header approach). +Things that I (alsuren) don't think will ever happen: + +* Killing off the enums (xclassens [[http://lists.freedesktop.org/archives/telepathy/2011-June/005540.html|http://lists.freedesktop.org/archives/telepathy/2011-June/005540.html]]). + * We either need to expose enums or strings for things like connection status. I have a bug (alsuren [[https://bugs.freedesktop.org/show_bug.cgi?id=37803|https://bugs.freedesktop.org/show_bug.cgi?id=37803]]) to use GEnum to link the enums and strings more conveniently.
\ No newline at end of file diff --git a/Telepathy.png b/Telepathy.png Binary files differnew file mode 100644 index 0000000..06377cc --- /dev/null +++ b/Telepathy.png diff --git a/TelepathyArchitectureOverview.png b/TelepathyArchitectureOverview.png Binary files differnew file mode 100644 index 0000000..76fc70a --- /dev/null +++ b/TelepathyArchitectureOverview.png diff --git a/conversion.mdwn b/conversion.mdwn new file mode 100644 index 0000000..fd7e189 --- /dev/null +++ b/conversion.mdwn @@ -0,0 +1,9 @@ +# MoinMoin to Ikiwiki conversion + +If you have an account on Annarchy, you can help out with the conversion of this wiki. + +You can follow the [[page conversion|http://wiki.freedesktop.org/sitewranglers/wiki/moin2iki_page_selection/]] instructions using `PROJECT="telepathy"`. + +Here is a list of broken links, which should be a starting place for what needs converting: + +[[!brokenlinks]] diff --git a/index.mdwn b/index.mdwn new file mode 100644 index 0000000..1d9775b --- /dev/null +++ b/index.mdwn @@ -0,0 +1,16 @@ +[[!table header="no" format="dsv" class="mointable" data=""" + Telepathy is a flexible, modular communications framework that enables real-time communication via pluggable protocol backends. Telepathy is a **communications service** that can be accessed by many applications ("clients") simultaneously. + +This allows any application to access presence information, request a communications channel (potentially handled by another client), or collaborate contact-to-contact. | [[!img Telepathy.png]] + | Telepathy provides protocol backends for most popular protocols including: Jabber/XMPP/Jingle, link-local XMPP, SIP, Yahoo/AIM and IRC via a unified [[D-Bus|http://dbus.freedesktop.org]] API. + +It also provides convenience libraries for GLib, Qt4 and Python to simplify using the API from applications. + Telepathy exposes the available real-time communications capabilities of each protocol: presence, contact rosters, text chat, voice and video over IP, file transfer and [[Telepathy Tubes|Documentation/Tubes]]. | + [[!img TelepathyArchitectureOverview.png]] | Telepathy is modular. Each backend and client runs in a separate process, allowing for much greater security and resilience. + Telepathy is suitable for embedded and desktop environments. + + [[!inline pages="FrontPage/UsingTelepathy" quick="yes" raw="yes"]] | [[!inline pages="FrontPage/DevelopingWithTelepathy" quick="yes" raw="yes"]] + [[!inline pages="FrontPage/ContributingToTelepathy" quick="yes" raw="yes"]] | [[!inline pages="FrontPage/ArticlesAndPresentations" quick="yes" raw="yes"]] +"""]] + +This wiki is undergoing [[conversion]]. If you have a fd.o shell account, you can help! diff --git a/service-profile-v1.mdwn b/service-profile-v1.mdwn new file mode 100644 index 0000000..5a0f04d --- /dev/null +++ b/service-profile-v1.mdwn @@ -0,0 +1,255 @@ + + +# Service Profiles + + +## Synopsis + +Service Profiles are intended to describe variants of the basic protocols supported by telepathy CMs (Connection Managers): An example of this would be Google Talk vs Facebook chat vs Jabber/XMPP - Google Talk is a specific case of XMPP with well-known capabilities, quirks and settings, and Facebook chat is a subset of the standard XMPP offering. + +Since there is a lot of common content/use overlap between Telepathy profiles and libaccounts services, the intention here is to describe a single file format that can and will be shared by both. + +A service is uniquely identified by its name: When there is more than one possible choice of CM for a protocol, the preferred CM on any given platform is allowed to name its service profile based on the name of the service alone, and any other CMs profiles that represent the service should be named by prepending the CM name to the service name, separated by a dash '-'. + + + +--- + + + + +## Details + + +### XMLNS Namespace + +The XMLNS for service profiles is [[http://telepathy.freedesktop.org/wiki/service-profile-v1|http://telepathy.freedesktop.org/wiki/service-profile-v1]] A parser/reader/user of a service profile is expected to ignore (for telepathy purposes) any attributes or tags not in this namespace - other users of the file (such as libaccounts) which have their own information storage requirements should use a different namespace for any tags or attributes they add to the service profile file. + +A service profile is expected to provide the following information: + + +### service + + +[[!format txt """ +<service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1" + id="google-talk" + type="IM" + provider="google" + manager="gabble" + protocol="jabber" + icon="gtalk-icon"> +"""]] + +#### id + +**mandatory** + +The unique name of the service. The preferred CM on a given platform is allowed to have a profile identified by service alone (eg "google-talk"). + +Any other CMs on the platform should be named <CM-name>-<service> + +Examples: google-talk, haze-google-talk + + +#### type + +**mandatory** + +The type of the service: In general, services of interest to both libaccounts and telepathy should be of type 'IM': Other service types exist but are unlikely to affect telepathy in any way + + +#### manager + +**mandatory** + +The name of the CM (connection manager) + +Examples: gabble, haze + + +#### protocol + +**mandatory** + +The standard telepathy name for the protocol over which this service is provided. + +Examples: jabber + + +#### provider + +**optional** + +The name of the vendor/organisation/provider who actually runs the service to which this profile applies. + +Examples: google, facebook + + +#### icon + +**optional** + +The base of the icon name for this service (to be looked for in the standard locations for icons used by the rest of the framework). Not explected to include either the type extension or the XxY size information, as these are considered to be entirely the domain of the UI. + +Examples: gtalk-icon, fb-icon + + +### name + +**mandatory** + +Human-readable name (possibly including required branding and so forth) for the service in question + + +[[!format txt """ + <name>Google``Talk™</name> +"""]] + +### parameters + +**optional** + +The CM parameters which describe the service: These can be mandatory, in which case the user shold not be allowed to alter them by the UI, as they define the service (google talk accounts _must_ connect to the actual google server, for example) or optional, in which case they merely specify defaults ehich may differ from the CM's defaults. + +These parameters are typed (with dbus types), so that libaccounts and telepathy can share the information. It is considered an error for the type of a parameter to differ from the type specified by the CM, although parsers are not required to enforce this (as they may be used in a context where the CM is unavailable and cannot be queried) + +Examples: + +* server, port, old-ssl (facebook, mandatory) +* fallback-conference-server (google, optional) + +[[!format txt """ + <parameters> + <parameter name="server" type="s" mandatory="1">talk.google.com</parameter> + <parameter name="port" type="u" mandatory="1">5223</parameter> + <parameter name="old-ssl" type="b" mandatory="1" + label="Use old-style SSL">1</parameter> + <parameter name="fallback-conference-server">conference.jabber.org</parameter> + </parameters> +"""]] +The parameter tag has the following defined attributes: + +* name + * string: The CM's name for this is (necessarily) canonical +* type + * string: (generally one character): the DBus type of the parameter +* label + * string: the human-readable label (if any) for the parameter +* mandatory + * boolean: (0 or 1, default 0): whether the value is fixed for this particular service + +### presences + +**optional** + +A service can support a subset of the presences supported by a given protocol, and/or have service specific names for the standard presences. + +A specified presence in this section is considered to override any properties (label, icon, [default] extended message) of the standard entry for said presence in the CM. + +A presence may also be disabled, in which case the UI should not offer it as a choice to the user at all, as the service is not considered to support it. + +Examples: + + +[[!format txt """ + <presences allow-others="1"> + <presence id="available" label="Online" icon="gtalk-online"/> + <presence id="offline" label="Offline"/> + <presence id="away" label="Gone"/> + <presence id="hidden" disabled="1"/> + </presences> +"""]] +The presences tag has the following attributes: + +* allow-others + * boolean (0 or 1, default 0): whether the any standard CM presences not mentioned here are still supported +The presence tag supports the following attributes: + +* id + * string: the telepathy presence id string +* label + * string: the label for this presence, if it differs from the CM default +* icon + * string: the service specific icon for this presence, if any +* message + * boolean: (0 or 1, default 0): if true, a user-defined text message can be attached to this presence +* disabled + * boolean (0 or 1, default 0): if true, this presence is not supported + +### unsuported channel classes + +**optional** + +Some services do not support the full range of channels that the protocol & CM are (in general) capable of: This item lists those channel classes which are not available on the service. + +Classes are defined (as in an ensure channel or create channel request) by a list of property/value pairs (an a{sv} in DBus terms): + +Example: + + +[[!format txt """ + <unsupported-channel-classes> + <!-- this service doesn't support text roomlists --> + <channel-class> + <property name="org.freedesktop.Telepathy.Channel.TargetHandleType" + type="u">3</property> + <property name="org.freedesktop.Telepathy.Channel.ChannelType" + type="s">org.freedesktop.Telepathy.Channel.Type.Text</property> + </channel-class> + <channel-class> + ⋮ + </channel-class> + </unsupported-channel-classes> +"""]] +The property tag has the following attributes: + +* name + * string: the telepathy DBus property of the channel +* type + * string (generally one character): the [DBus] type of the property + +## Example + + +[[!format txt """ +<service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1" + id="google-talk" + type="IM" + provider="google" + manager="gabble" + protocol="jabber" + icon="gtalk-icon"> + <name>Google``Talk™</name> + + <parameters> + <parameter name="server" type="s" mandatory="1">talk.google.com</parameter> + <parameter name="port" type="u" mandatory="1">5223</parameter> + <parameter name="old-ssl" type="b" mandatory="1" + label="Use old-style SSL">1</parameter> + <parameter name="fallback-conference-server">conference.jabber.org</parameter> + </parameters> + + <parameters> + <parameter name="server" type="s" mandatory="1">profile.com</parameter> + <parameter name="port" type="u" mandatory="1">1111</parameter> + </parameters> + + <presences allow-others="1"> + <presence id="available" label="Online" icon="online"/> + <presence id="offline" label="Offline"/> + <presence id="away" label="Gone"/> + <presence id="hidden" disabled="1"/> + </presences> + + <unsupported-channel-classes> + <!-- this service doesn't support text roomlists --> + <channel-class> + <property name="org.freedesktop.Telepathy.Channel.TargetHandleType" + type="u">3</property> + <property name="org.freedesktop.Telepathy.Channel.ChannelType" + type="s">org.freedesktop.Telepathy.Channel.Type.Text</property> + </channel-class> + </unsupported-channel-classes> +</service> +"""]]
\ No newline at end of file @@ -0,0 +1,27 @@ +tt is a command-line utility which drives `make check` on your behalf. It makes running CM and Mission Control tests much easier, and is ideal if you're lazy. To quote the `--help` output: + + Examples: + # Run all tests, as a shorthand for `make check`: + tt + # Run a single test: + tt muc/banned.py + tt muc/banned + # Run all tests in a directory: + tt muc/ + # Run a bunch of tests: + tt muc/ text/ + +## Get a binary + +Here's [tt 1.1 for amd64](http://people.freedesktop.org/~wjt/tt/tt-1.1.amd64.bz2), or [tt 1.0 for x86](http://people.freedesktop.org/~wjt/tt/tt-1.0.x86.bz2). + +## Build from source + +The source lives on [cgit.freedesktop.org](http://cgit.freedesktop.org/~wjt/tt). Grab it and build it as follows: + + git clone git://people.freedesktop.org/~wjt/tt + cd tt + cabal install --prefix=$HOME + ~/bin/tt --help + +See also, the [README](http://cgit.freedesktop.org/~wjt/tt/plain/README). |
