Overview

                      dxmpp: D-Bus XMPP transport
             (c) 2005 Jakub Piotr Cłapa <jpc@pld-linux.org>

dxmpp is  a desktop  daemon which exposes  your Jabber/XMPP  accounts to
your desktop programs. It also contains a proxy program which allows you
to continue using your favorite  Jabber client. Currently it only allows
sending arbitrary messages  and setting presence but in  feature it will
allow any program, would it be a game, blackboard, data sharing software
(like Google Hello), voice chat  or HTTP authorization, to fully utilize
your Jabber connection for communication.

Acknowledgements:
-----------------

First of all I would like to thank God (surprised?) for looking after me
while I was coding  and while I was doing all other things  I had to. If
not Him my life (and this work as well) would not be as it should. (some
may argue  that world would  be better if either  me or this  project or
even both project never existed but  I hope you understand that I really
cannot discuss with this opinions ;)

The second person I would like to thank is my one and only -- Julita. If
not her I would probably fail  to find enought motivation to finish this
project. The fun for actually working on it wouldn't be so big as well.

I hope averybody will forgive me that  the first two places on this list
were already taken even before this project started. ;)

Apart from  them this project  would also not  been realized if  not the
help from Jacek Konieczny [1] and the Google Summer Of Code program [2].
I want to thank both Jacek for the enormous amount of help and advice he
provided and Google for providing me with a good reason to spend most of
my holidays  coding this.  I am  also grateful for  the help  from Havoc
Pennington [3] I got while writing my own DBus protocol implementation.

[1] Jacek Konieczny - the author of PyXMPP and my XMPP guru of choice ;)
    xmpp: jajcus <at> jabber bnet pl
[2] http://code.google.com/summerofcode.html
[3] Havoc Pennington - a great GNOME and fd.o hacker
    http://ometer.com/

Goals:
------

There are  currently two main goals  for this project and  only time can
tell which one was The One.

Create an easy  to use API for interacting with  the XMPP connections by
create a stand-alone proxy exposing  the connections. After this is done
the desktop clients can:

1. adopt the API and use it as their only way to connect to XMPP servers
   (dropping the need of XML/XMPP library)
2. expose their  connections using this  API to allow other  programs to
   use  them but  remain the  central program  managing the  connections
   (effectively incorporating the proxy into the client)

Of course there is  also the possibility that none of  this occurs and I
won't conquer the world but let's not be that pessimistic. ;]

Requirements:
-------------

1. Python 2.4 or newer
2. PyXMPP - http://jabberstudio.org/projects/pyxmpp
3. libxml2 python bindings - http://xmlsoft.org/
4. DBus 0.35  or never and  a properly set up  session bus (refer  to or
   your distributions' documentation if you have problems with this)

Installation:
-------------

There is no such step currently, just use it from the source.

Usage:
------

There are two main programs which you will probably want to use:

- jabber-dbus.py

  A desktop daemon  which exports your Jabber  connections through DBus.
  It needs a configuration file  in ~/.dxmpp/config which currently must
  be written  by hand (a browser  based interface is planned  in future;
  see config.example for now).

  WARNING: The account names  ('somedomain_com' and 'otherdomain_net' in
  the example) may only contain 'A-Za-z0-9_' characters.

- dbus-jabber.py
  
  A Jabber server which listens on  localhost and allows you to use your
  DBus exported  accounts with any Jabber  client. To use it  simply set
  the Jabber server  manually to localhost:5222 (w/o  SSL encryption and
  SASL auth).

There are also two example programs that show how to use the daemon DBus
exported  features  (currently  they  only allow  sending  messages  and
setting presence):

- send-message.py
- send-presence.py

The  last thing  in the  archive  is the  dbus folder  which contains  a
pure-Python DBus implementation. It could  be of some use for developers
but if  you don't know what  I'm talking about you  should probably just
believe that it must be there and works well. ;]

Bug reports and feature requests:
---------------------------------

The preferred  method to discuss any  dxmpp related issues is  to send a
message (probably after subscribing) to dxmpp@googlegroups.com.