pangdudu-ruby-dbus 0.1.0

data/README.rdoc

@@ -0,0 +1,111 @@
+= Ruby D-Bus -> ffwd
+
+Ruby D-Bus provides an implementation of the D-Bus protocol such that the
+D-Bus system can be used in the Ruby programming language.
+
+
+This is my personal dev-fork of mvidners upstream.
+
+If you'd like to contrib to this fork, let me know.
+
+
+
+Most of my work here is actually for another project: http://github.com/pangdudu/robots/tree/master
+
+I might also start writing a less ugly version of: http://github.com/pangdudu/ruby-dbus-daemon/tree/master 
+
+If you know of a nice custom-dbus-daemon let me know. Still thinking about writing
+a dbus spec compliant server/daemon implementation in (pure) Ruby, so that I can
+play around with the network and authentification more easily.
+
+Oki, will clean up a little now. :)
+
+Peace.
+
+== Requirements
+
+ * Ruby 1.8 (>= 1.8.6?)
+
+== Installation
+
+  sudo gem install pangdudu-ruby-dbus --source=http://gems.github.com
+
+== Features
+
+Ruby D-Bus currently supports the following features:
+
+ * Connecting to local buses.
+ * Accessing remote services, objects and interfaces.
+ * Invoking methods on remote objects synchronously and asynchronously.
+ * Catch signals on remote objects and handle them via callbacks.
+ * Remote object introspection.
+ * Walking object trees.
+ * Creating services and registering them on the bus.
+ * Exporting objects with interfaces on a bus for remote use.
+ * Rubyish D-Bus object and interface syntax support that automatically
+   allows for introspection.
+ * Emitting signals on exported objects.
+ 
+ * Connection to a local or remote bus over TCP/IP
+ * Authentification mechanisms working now: External,CookieSHA1
+
+== Usage
+
+=== Basics:
+
+View a tutorial online on http://trac.luon.net/data/ruby-dbus/tutorial/.
+
+
+=== TCP/Remote stuff:
+
+Take a look at 'config/remote.session.dbus.conf' and start 'config/start_dbus_session.sh'.
+
+You can now try and run one of the tests e.g. 'test/simple_socket_test.rb'.
+
+
+=== Problems you'll have with 'CookieSHA1' when using it remotely: 
+
+Unless we [including you :)] write a funkier SASL authentification mechanism that
+makes sense when using it over-wire, we're stuck with the cookie auth.
+
+Works like this: 
+
+There is a file in '~/.dbus-keyrings' named 'org_freedesktop_general'. 
+It is '-rw-------' so that only you can read it (if you change the permissions, 
+dbus-daemon will most likely ignore the file leaving you with 'External', which is
+even worse remotely). It's kind of a secret key you use to auth against yourself 
+later on.
+
+If you take a look at 'dbus/auth.rb line 40+' you'll see the problem:
+
+  # Search cookie file for id
+  path = File.join(ENV['HOME'], '.dbus-keyrings', context)
+  
+So if you're starting 'config/start_dbus_session.sh' on one host and 'config/start_dbus_session.sh'
+on another one, you'll need to make sure that the content in '~/.dbus-keyrings/org_freedesktop_general'
+is the same on both machines, in order for the 'CookieSHA1' auth to work.
+
+Not cool. I can think of hacks with nfs,smb or fuse:sshfs making it less
+painful to use. 
+
+The file content also get's updated every 5 minutes (when a client fails to auth etc.). 
+Making copy and paste from one shell to another very frolic.
+
+To sum it up: 
+
+Today it's acceptable to use it like this, but until next week we'll need an easy 
+auth mechanism that works on the wire. 
+
+
+more infos:
+  http://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms
+  http://lists.freedesktop.org/archives/dbus/2007-June/008067.html
+
+Booyaa.
+
+== License
+
+Ruby D-Bus is free software; you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by the
+Free Software Foundation; either version 2.1 of the License, or (at
+your option) any later version.

data/config/remote.session.dbus.conf

@@ -0,0 +1,39 @@
+<!-- This configuration file controls the per-user-login-session message bus.
+     Add a session-local.conf and edit that rather than changing this 
+     file directly. -->
+
+<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+<busconfig>
+  <!-- Our well-known bus type, don't change this -->
+  <type>session</type>
+
+  <!-- If we fork, keep the user's original umask to avoid affecting
+       the behavior of child processes. -->
+  <keep_umask/>
+
+<!--  <allow_anonymous/> -->
+  
+  <!-- Listen to everything on tcp! -->
+  <listen>tcp:host=0.0.0.0,port=2687,family=ipv4</listen>
+  <!-- Listen on socket at this file location -->
+  <listen>unix:path=/tmp/socket_test_session_bus_socket</listen>
+  
+  <standard_session_servicedirs /> 
+
+  <policy context="default">
+    <!-- Allow everything to be sent -->
+    <allow send_destination="*" eavesdrop="true"/>
+    <!-- Allow everything to be received -->
+    <allow eavesdrop="true"/>
+    <!-- Allow anyone to own anything -->
+    <allow own="*"/>
+  </policy>
+
+  <!-- raise the service start timeout to 40 seconds as it can timeout
+       on the live cd on slow machines -->
+  <limit name="service_start_timeout">60000</limit>
+
+  <include if_selinux_enabled="yes" selinux_root_relative="yes">contexts/dbus_contexts</include>
+
+</busconfig>

data/config/start_dbus_session.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+dbus-daemon --print-address --config-file=remote.session.dbus.conf

data/lib/dbus/auth.rb

@@ -0,0 +1,238 @@
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+module DBus
+  # Exception raised when authentication fails somehow.
+  class AuthenticationFailed < Exception
+  end
+
+  # = General class for authentication.
+  class Authenticator
+    # Returns the name of the authenticator.
+    def name
+      self.class.to_s.upcase.sub(/.*::/, "")
+    end
+  end
+
+  # = External authentication class 
+  #
+  # Class for 'external' type authentication.
+  class External < Authenticator
+    # Performs the authentication.
+    def authenticate
+      # Take the user id (eg integer 1000) make a string out of it "1000", take
+      # each character and determin hex value "1" => 0x31, "0" => 0x30. You
+      # obtain for "1000" => 31303030 This is what the server is expecting.
+      # Why? I dunno. How did I come to that conclusion? by looking at rbus
+      # code. I have no idea how he found that out. 
+      return Process.uid.to_s.split(//).collect { |a| "%x" % a[0] }.join
+    end
+  end
+  
+  # = Authentication class using SHA1 crypto algorithm 
+  #
+  # Class for 'CookieSHA1' type authentication.
+  # Implements the AUTH DBUS_COOKIE_SHA1 mechanism.
+  class DBusCookieSHA1 < Authenticator
+    
+    #the autenticate method (called in stage one of authentification)    
+    def authenticate
+      require 'etc'
+      return "#{hex_encode(Etc.getlogin)}" #server expects it to be binary
+    end
+
+    #returns the modules name
+    def name
+      return 'DBUS_COOKIE_SHA1'
+    end
+    
+    #handles the interesting crypto stuff, check the rbus-project for more info: http://rbus.rubyforge.org/
+    def data(hexdata)
+      require 'digest/sha1'
+      data = hex_decode(hexdata)
+      # name of cookie file, id of cookie in file, servers random challenge  
+      context, id, s_challenge = data.split(' ')
+      # Random client challenge        
+      c_challenge = Array.new(s_challenge.length/2).map{|obj|obj=rand(255).to_s}.join
+      # Search cookie file for id
+      path = File.join(ENV['HOME'], '.dbus-keyrings', context)
+      dlog "path: #{path.inspect}"
+      File.foreach(path) do |line|
+        if line.index(id) == 0
+          # Right line of file, read cookie
+          cookie = line.split(' ')[2].chomp
+          dlog "cookie: #{cookie.inspect}"
+          # Concatenate and encrypt
+          to_encrypt = [s_challenge, c_challenge, cookie].join(':')
+          sha = Digest::SHA1.hexdigest(to_encrypt)
+          #the almighty tcp server wants everything hex encoded
+          hex_response = hex_encode("#{c_challenge} #{sha}")
+          # Return response
+          response = [:AuthOk, hex_response]
+          return response
+        end
+      end
+      elog "Unable to locate cookie"
+    end  
+    
+    # encode plain to hex
+    def hex_encode(plain)
+      return nil if plain.nil?
+      plain.to_s.unpack('H*')[0]
+    end
+    
+    # decode hex to plain
+    def hex_decode(encoded)
+      encoded.scan(/[[:xdigit:]]{2}/).map{|h|h.hex.chr}.join
+    end  
+  end #DBusCookieSHA1 class ends here
+
+  # = Authentication client class.
+  #
+  # Class tha performs the actional authentication.
+  class Client
+    # Create a new authentication client.
+    def initialize(socket)
+      @socket = socket
+      @state = nil
+      @auth_list = [External,DBusCookieSHA1]
+    end
+
+    # Start the authentication process.
+    def authenticate
+      @socket.write(0.chr)
+      next_authenticator
+      @state = :Starting
+      while @state != :Authenticated
+        r = next_state
+        return r if not r
+      end
+      true
+    end
+
+    ##########
+    private
+    ##########
+
+    # Send an authentication method _meth_ with arguments _args_ to the
+    # server.
+    def send(meth, *args)
+      o = ([meth] + args).join(" ")
+      @socket.write(o + "\r\n")
+    end
+
+    # Try authentication using the next authenticator.
+    def next_authenticator
+      begin
+        raise AuthException if @auth_list.size == 0
+        @authenticator = @auth_list.shift.new
+        auth_msg = ["AUTH", @authenticator.name, @authenticator.authenticate]
+        dlog "auth_msg: #{auth_msg.inspect}"
+        send(auth_msg)
+      rescue AuthException
+        @socket.close
+        raise
+      end
+    end
+
+
+    # Read data (a buffer) from the bus until CR LF is encountered.
+    # Return the buffer without the CR LF characters.
+    def next_msg
+      data,crlf = "","\r\n"
+      left = 1024 #1024 byte, no idea if it's ever getting bigger
+      while left > 0
+        buf = @socket.read( left > 1 ? 1 : left )
+        break if buf.nil?
+        left -= buf.size
+        data += buf
+        break if data.include? crlf #crlf means line finished, the TCP socket keeps on listening, so we break 
+      end
+      readline = data.chomp.split(" ")
+      dlog "readline: #{readline.inspect}"
+      return readline
+    end
+
+    # Try to reach the next state based on the current state.
+    def next_state
+      msg = next_msg
+      if @state == :Starting
+        dlog ":Starting msg: #{msg[0].inspect}"
+        case msg[0]
+        when "OK"
+          @state = :WaitingForOk    
+        when "CONTINUE"
+          @state = :WaitingForData
+        when "REJECTED" #needed by tcp, unix-path/abstract doesn't get here
+          @state = :WaitingForData
+        end
+      end
+      dlog "state: #{@state}"
+      case @state
+      when :WaitingForData
+        dlog ":WaitingForData msg: #{msg[0].inspect}"
+        case msg[0]
+        when "DATA"
+          chall = msg[1]
+          resp, chall = @authenticator.data(chall)
+          dlog ":WaitingForData/DATA resp: #{resp.inspect}"
+          case resp
+          when :AuthContinue
+            send("DATA", chall)
+            @state = :WaitingForData
+          when :AuthOk
+            send("DATA", chall)
+            @state = :WaitingForOk
+          when :AuthError
+            send("ERROR")
+            @state = :WaitingForData
+          end
+        when "REJECTED"
+          next_authenticator
+          @state = :WaitingForData
+        when "ERROR"
+          send("CANCEL")
+          @state = :WaitingForReject
+        when "OK"
+          send("BEGIN")
+          @state = :Authenticated
+        else
+          send("ERROR")
+          @state = :WaitingForData
+        end
+      when :WaitingForOk
+        dlog ":WaitingForOk msg: #{msg[0].inspect}"
+        case msg[0]
+        when "OK"
+          send("BEGIN")
+          @state = :Authenticated
+        when "REJECT"
+          next_authenticator
+          @state = :WaitingForData
+        when "DATA", "ERROR"
+          send("CANCEL")
+          @state = :WaitingForReject
+        else
+          send("ERROR")
+          @state = :WaitingForOk
+        end
+      when :WaitingForReject
+        dlog ":WaitingForReject msg: #{msg[0].inspect}"
+        case msg[0]
+        when "REJECT"
+          next_authenticator
+          @state = :WaitingForOk
+        else
+          @socket.close
+          return false
+        end
+      end
+      return true
+    end # def next_state
+  end # class Client 
+end # module D-Bus

data/lib/dbus/bus.rb

@@ -0,0 +1,719 @@
+# dbus.rb - Module containing the low-level D-Bus implementation
+#
+# This file is part of the ruby-dbus project
+# Copyright (C) 2007 Arnaud Cornet and Paul van Tilburg
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+require 'socket'
+require 'thread'
+require 'singleton'
+
+# = D-Bus main module
+#
+# Module containing all the D-Bus modules and classes.
+module DBus
+  # This represents a remote service. It should not be instancied directly
+  # Use Bus::service()
+  class Service
+    # The service name.
+    attr_reader :name
+    # The bus the service is running on.
+    attr_reader :bus
+    # The service root (FIXME).
+    attr_reader :root
+
+    # Create a new service with a given _name_ on a given _bus_.
+    def initialize(name, bus)
+      @name, @bus = name, bus
+      @root = Node.new("/")
+    end
+
+    # Determine whether the serice name already exists.
+    def exists?
+      bus.proxy.ListName.member?(@name)
+    end
+
+    # Perform an introspection on all the objects on the service
+    # (starting recursively from the root).
+    def introspect
+      if block_given?
+        raise NotImplementedError
+      else
+        rec_introspect(@root, "/")
+      end
+      self
+    end
+
+    # Retrieves an object at the given _path_.
+    def object(path)
+      node = get_node(path, true)
+      if node.object.nil?
+        node.object = ProxyObject.new(@bus, @name, path)
+      end
+      node.object
+    end
+
+    # Export an object _obj_ (an DBus::Object subclass instance).
+    def export(obj)
+      obj.service = self
+      get_node(obj.path, true).object = obj
+    end
+
+    # Get the object node corresponding to the given _path_. if _create_ is
+    # true, the the nodes in the path are created if they do not already exist.
+    def get_node(path, create = false)
+      n = @root
+      path.sub(/^\//, "").split("/").each do |elem|
+        if not n[elem]
+          if not create
+            return nil
+          else
+            n[elem] = Node.new(elem)
+          end
+        end
+        n = n[elem]
+      end
+      if n.nil?
+        wlog "Unknown object #{path.inspect}"
+      end
+      n
+    end
+
+    #########
+    private
+    #########
+
+    # Perform a recursive retrospection on the given current _node_
+    # on the given _path_.
+    def rec_introspect(node, path)
+      xml = bus.introspect_data(@name, path)
+      intfs, subnodes = IntrospectXMLParser.new(xml).parse
+      subnodes.each do |nodename|
+        subnode = node[nodename] = Node.new(nodename)
+        if path == "/"
+          subpath = "/" + nodename
+        else
+          subpath = path + "/" + nodename
+        end
+        rec_introspect(subnode, subpath)
+      end
+      if intfs.size > 0
+        node.object = ProxyObjectFactory.new(xml, @bus, @name, path).build
+      end
+    end
+  end
+
+  # = Object path node class
+  #
+  # Class representing a node on an object path.
+  class Node < Hash
+    # The D-Bus object contained by the node.
+    attr_accessor :object
+    # The name of the node.
+    attr_reader :name
+
+    # Create a new node with a given _name_.
+    def initialize(name)
+      @name = name
+      @object = nil
+    end
+
+    # Return an XML string representation of the node.
+    def to_xml
+      xml = '<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+      <node>'
+
+      self.each_pair do |k, v|
+        xml += "<node name=\"#{k}\" />"
+      end
+      if @object
+        @object.intfs.each_pair do |k, v|
+          xml += %{<interface name="#{v.name}">\n}
+          v.methods.each_value { |m| xml += m.to_xml }
+          v.signals.each_value { |m| xml += m.to_xml }
+          xml +="</interface>\n"
+        end
+      end
+      xml += '</node>'
+      return xml
+    end
+
+    # Return inspect information of the node.
+    def inspect
+      # Need something here
+      "<DBus::Node #{sub_inspect}>"
+    end
+
+    # Return instance inspect information, used by Node#inspect.
+    def sub_inspect
+      s = ""
+      if not @object.nil?
+        s += "%x " % @object.object_id
+      end
+      s + "{" + keys.collect { |k| "#{k} => #{self[k].sub_inspect}" }.join(",") + "}"
+    end
+  end # class Inspect
+
+  # FIXME: rename Connection to Bus?
+
+  # D-Bus main connection class
+  #
+  # Main class that maintains a connection to a bus and can handle incoming
+  # and outgoing messages.
+  class Connection
+    # The unique name (by specification) of the message.
+    attr_reader :unique_name
+    # The socket that is used to connect with the bus.
+    attr_reader :socket
+
+    # Create a new connection to the bus for a given connect _path_. _path_
+    # format is described in the D-Bus specification:
+      # http://dbus.freedesktop.org/doc/dbus-specification.html#addresses
+    # and is something like:
+    # "transport1:key1=value1,key2=value2;transport2:key1=value1,key2=value2"
+    # e.g. "unix:path=/tmp/dbus-test" or "tcp:host=localhost,port=2687"
+    def initialize(path)
+      @path = path
+      @unique_name = nil
+      @buffer = ""
+      @method_call_replies = Hash.new
+      @method_call_msgs = Hash.new
+      @signal_matchrules = Array.new
+      @proxy = nil
+      @object_root = Node.new("/")
+    end
+
+    # Connect to the bus and initialize the connection.
+    def connect
+      connect_to_tcp if @path.include? "tcp:" #connect to tcp socket
+      connect_to_unix if @path.include? "unix:" #connect to unix socket
+    end
+
+    # Connect to a bus over tcp and initialize the connection.
+    def connect_to_tcp
+      #check if the path is sufficient
+      if @path.include? "host=" and @path.include? "port="
+        host,port,family = "","",""
+        #get the parameters
+        @path.split(",").each do |para|
+          host = para.sub("tcp:","").sub("host=","") if para.include? "host="
+          port = para.sub("port=","").to_i if para.include? "port="
+          family = para.sub("family=","") if para.include? "family="
+        end
+        dlog "host,port,family : #{host},#{port},#{family}"      
+        begin
+          #initialize the tcp socket
+          @socket = TCPSocket.new(host,port)
+          init_connection
+        rescue
+          elog "Could not establish connection to: #{@path}, will now exit."
+          exit(0) #a little harsh
+        end
+      else
+        #Danger, Will Robinson: the specified "path" is not usable
+        elog "supplied path: #{@path}, unusable! sorry."
+      end
+    end
+
+    # Connect to an abstract unix bus and initialize the connection.
+    def connect_to_unix
+      @socket = Socket.new(Socket::Constants::PF_UNIX,Socket::Constants::SOCK_STREAM, 0)
+      parse_session_string
+      if @transport == "unix" and @type == "abstract"
+        if HOST_END == LIL_END
+          sockaddr = "\1\0\0#{@unix_abstract}"
+        else
+          sockaddr = "\0\1\0#{@unix_abstract}"
+        end
+      elsif @transport == "unix" and @type == "path"
+        sockaddr = Socket.pack_sockaddr_un(@unix)
+      end
+      @socket.connect(sockaddr)
+      init_connection
+    end
+    
+    # Parse the session string (socket address).
+    def parse_session_string
+      path_parsed = /^([^:]*):([^;]*)$/.match(@path)
+      @transport = path_parsed[1]
+      adr = path_parsed[2]
+      if @transport == "unix"
+        adr.split(",").each do |eqstr|
+          idx, val = eqstr.split("=")
+          case idx
+          when "path"
+            @type = idx
+            @unix = val
+          when "abstract"
+            @type = idx
+            @unix_abstract = val
+          when "guid"
+            @guid = val
+          end
+        end
+      end
+    end
+
+    # Send the buffer _buf_ to the bus using Connection#writel.
+    def send(buf)
+      @socket.write(buf) unless @socket.nil?
+    end
+
+    # Tell a bus to register itself on the glib main loop
+    def glibize
+      require 'glib2'
+      # Circumvent a ruby-glib bug
+      @channels ||= Array.new
+
+      gio = GLib::IOChannel.new(@socket.fileno)
+      @channels << gio
+      gio.add_watch(GLib::IOChannel::IN) do |c, ch|
+        update_buffer
+        messages.each do |msg|
+          process(msg)
+        end
+        true
+      end
+    end
+
+    # FIXME: describe the following names, flags and constants.
+    # See DBus spec for definition
+    NAME_FLAG_ALLOW_REPLACEMENT = 0x1
+    NAME_FLAG_REPLACE_EXISTING = 0x2
+    NAME_FLAG_DO_NOT_QUEUE = 0x4
+
+    REQUEST_NAME_REPLY_PRIMARY_OWNER = 0x1
+    REQUEST_NAME_REPLY_IN_QUEUE = 0x2
+    REQUEST_NAME_REPLY_EXISTS = 0x3
+    REQUEST_NAME_REPLY_ALREADY_OWNER = 0x4
+
+    DBUSXMLINTRO = '<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+  <interface name="org.freedesktop.DBus.Introspectable">
+    <method name="Introspect">
+      <arg name="data" direction="out" type="s"/>
+    </method>
+  </interface>
+  <interface name="org.freedesktop.DBus">
+    <method name="RequestName">
+      <arg direction="in" type="s"/>
+      <arg direction="in" type="u"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="ReleaseName">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="StartServiceByName">
+      <arg direction="in" type="s"/>
+      <arg direction="in" type="u"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="Hello">
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="NameHasOwner">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="b"/>
+    </method>
+    <method name="ListNames">
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="ListActivatableNames">
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="AddMatch">
+      <arg direction="in" type="s"/>
+    </method>
+    <method name="RemoveMatch">
+      <arg direction="in" type="s"/>
+    </method>
+    <method name="GetNameOwner">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="s"/>
+    </method>
+    <method name="ListQueuedOwners">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="as"/>
+    </method>
+    <method name="GetConnectionUnixUser">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="GetConnectionUnixProcessID">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="u"/>
+    </method>
+    <method name="GetConnectionSELinuxSecurityContext">
+      <arg direction="in" type="s"/>
+      <arg direction="out" type="ay"/>
+    </method>
+    <method name="ReloadConfig">
+    </method>
+    <signal name="NameOwnerChanged">
+      <arg type="s"/>
+      <arg type="s"/>
+      <arg type="s"/>
+    </signal>
+    <signal name="NameLost">
+      <arg type="s"/>
+    </signal>
+    <signal name="NameAcquired">
+      <arg type="s"/>
+    </signal>
+  </interface>
+</node>
+'
+
+    def introspect_data(dest, path)
+      m = DBus::Message.new(DBus::Message::METHOD_CALL)
+      m.path = path
+      m.interface = "org.freedesktop.DBus.Introspectable"
+      m.destination = dest
+      m.member = "Introspect"
+      m.sender = unique_name
+      if not block_given?
+        # introspect in synchronous !
+        send_sync(m) do |rmsg|
+          if rmsg.is_a?(Error)
+            raise rmsg
+          else
+            return rmsg.params[0]
+          end
+        end
+      else
+        send(m.marshall)
+        on_return(m) do |rmsg|
+          if rmsg.is_a?(Error)
+            yield rmsg
+          else
+            yield rmsg.params[0]
+          end
+        end
+      end
+      nil
+    end
+
+    # Issues a call to the org.freedesktop.DBus.Introspectable.Introspect method
+    # _dest_ is the service and _path_ the object path you want to introspect
+    # If a code block is given, the introspect call in asynchronous. If not
+    # data is returned
+    #
+    # FIXME: link to ProxyObject data definition
+    # The returned object is a ProxyObject that has methods you can call to
+    # issue somme METHOD_CALL messages, and to setup to receive METHOD_RETURN
+    def introspect(dest, path)
+      if not block_given?
+        # introspect in synchronous !
+        data = introspect_data(dest, path)
+        pof = DBus::ProxyObjectFactory.new(data, self, dest, path)
+        return pof.build
+      else
+        introspect_data(dest, path) do |data|
+          yield(DBus::ProxyObjectFactory.new(data, self, dest, path).build)
+        end
+      end
+    end
+
+    # Exception raised when a service name is requested that is not available.
+    class NameRequestError < Exception
+    end
+
+    # Attempt to request a service _name_.
+    def request_service(name)
+      r = proxy.RequestName(name, NAME_FLAG_REPLACE_EXISTING)
+      raise NameRequestError if r[0] != REQUEST_NAME_REPLY_PRIMARY_OWNER
+      @service = Service.new(name, self)
+      @service
+    end
+
+    # Set up a ProxyObject for the bus itself, since the bus is introspectable.
+    # Returns the object.
+    def proxy
+      if @proxy == nil
+        path = "/org/freedesktop/DBus"
+        dest = "org.freedesktop.DBus"
+        pof = DBus::ProxyObjectFactory.new(DBUSXMLINTRO, self, dest, path)
+        @proxy = pof.build["org.freedesktop.DBus"]
+      end
+      @proxy
+    end
+
+    # Fill (append) the buffer from data that might be available on the
+    # socket.
+    def update_buffer
+      @buffer += @socket.read_nonblock(MSG_BUF_SIZE) unless @socket.nil?
+    end
+
+    # Get one message from the bus and remove it from the buffer.
+    # Return the message.
+    def pop_message
+      ret = nil
+      begin
+        ret, size = Message.new.unmarshall_buffer(@buffer)
+        @buffer.slice!(0, size)
+      rescue IncompleteBufferException => e
+        # fall through, let ret be null
+      end
+      ret
+    end
+
+    # Retrieve all the messages that are currently in the buffer.
+    def messages
+      ret = Array.new
+      while msg = pop_message
+        ret << msg
+      end
+      ret
+    end
+
+    # The buffer size for messages.
+    MSG_BUF_SIZE = 4096
+
+    # Update the buffer and retrieve all messages using Connection#messages.
+    # Return the messages.
+    def poll_messages
+      ret = nil
+      r, d, d = IO.select([@socket], nil, nil, 0)
+      if r and r.size > 0
+        update_buffer
+      end
+      messages
+    end
+
+    # Wait for a message to arrive. Return it once it is available.
+    def wait_for_message
+      if @socket.nil?
+        elog "Can't wait for messages, @socket is nil."
+        return
+      end
+      ret = pop_message
+      while ret == nil
+        r, d, d = IO.select([@socket])
+        if r and r[0] == @socket
+          update_buffer
+          ret = pop_message
+        end
+      end
+      ret
+    end
+
+    # Send a message _m_ on to the bus. This is done synchronously, thus
+    # the call will block until a reply message arrives.
+    def send_sync(m, &retc) # :yields: reply/return message
+      return if m.nil? #check if somethings wrong
+      send(m.marshall)
+      @method_call_msgs[m.serial] = m
+      @method_call_replies[m.serial] = retc
+
+      retm = wait_for_message
+      
+      return if retm.nil? #check if somethings wrong
+      
+      process(retm)
+      until [DBus::Message::ERROR,
+          DBus::Message::METHOD_RETURN].include?(retm.message_type) and
+          retm.reply_serial == m.serial
+        retm = wait_for_message
+        process(retm)
+      end
+    end
+
+    # Specify a code block that has to be executed when a reply for
+    # message _m_ is received.
+    def on_return(m, &retc)
+      # Have a better exception here
+      if m.message_type != Message::METHOD_CALL
+        elog "Funky exception, occured."
+        raise "on_return should only get method_calls"
+      end
+      @method_call_msgs[m.serial] = m
+      @method_call_replies[m.serial] = retc
+    end
+
+    # Asks bus to send us messages matching mr, and execute slot when
+    # received
+    def add_match(mr, &slot)
+      # check this is a signal.
+      @signal_matchrules << [mr, slot]
+      self.proxy.AddMatch(mr.to_s)
+    end
+
+    # Process a message _m_ based on its type.
+    def process(m)
+      return if m.nil? #check if somethings wrong
+      case m.message_type
+      when Message::ERROR, Message::METHOD_RETURN
+        raise InvalidPacketException if m.reply_serial == nil
+        mcs = @method_call_replies[m.reply_serial]
+        if not mcs
+          dlog "no return code for mcs: #{mcs.inspect} m: #{m.inspect}"
+        else
+          if m.message_type == Message::ERROR
+            mcs.call(Error.new(m))
+          else
+            mcs.call(m)
+          end
+          @method_call_replies.delete(m.reply_serial)
+          @method_call_msgs.delete(m.reply_serial)
+        end
+      when DBus::Message::METHOD_CALL
+        if m.path == "/org/freedesktop/DBus"
+          dlog "Got method call on /org/freedesktop/DBus"
+        end
+        # handle introspectable as an exception:
+        if m.interface == "org.freedesktop.DBus.Introspectable" and
+            m.member == "Introspect"
+          reply = Message.new(Message::METHOD_RETURN).reply_to(m)
+          reply.sender = @unique_name
+          node = @service.get_node(m.path)
+          raise NotImplementedError if not node
+          reply.sender = @unique_name
+          reply.add_param(Type::STRING, @service.get_node(m.path).to_xml)
+          send(reply.marshall)
+        else
+          node = @service.get_node(m.path)
+          return if node.nil?
+          obj = node.object
+          return if obj.nil?
+          obj.dispatch(m) if obj
+        end
+      when DBus::Message::SIGNAL
+        @signal_matchrules.each do |elem|
+          mr, slot = elem
+          if mr.match(m)
+            slot.call(m)
+            return
+          end
+        end
+      else
+        dlog "Unknown message type: #{m.message_type}"
+      end
+    end
+
+    # Retrieves the service with the given _name_.
+    def service(name)
+      # The service might not exist at this time so we cannot really check
+      # anything
+      Service.new(name, self)
+    end
+    alias :[] :service
+
+    # Emit a signal event for the given _service_, object _obj_, interface
+    # _intf_ and signal _sig_ with arguments _args_.
+    def emit(service, obj, intf, sig, *args)
+      m = Message.new(DBus::Message::SIGNAL)
+      m.path = obj.path
+      m.interface = intf.name
+      m.member = sig.name
+      m.sender = service.name
+      i = 0
+      sig.params.each do |par|
+        m.add_param(par[1], args[i])
+        i += 1
+      end
+      send(m.marshall)
+    end
+
+    ###########################################################################
+    private
+
+    # Send a hello messages to the bus to let it know we are here.
+    def send_hello
+      m = Message.new(DBus::Message::METHOD_CALL)
+      m.path = "/org/freedesktop/DBus"
+      m.destination = "org.freedesktop.DBus"
+      m.interface = "org.freedesktop.DBus"
+      m.member = "Hello"
+      send_sync(m) do |rmsg|
+        @unique_name = rmsg.destination
+        dlog "Got hello reply. Our unique_name is #{@unique_name}, i feel special."
+      end
+    end
+
+    # Initialize the connection to the bus.
+    def init_connection
+      @client = Client.new(@socket)
+      @client.authenticate
+    end
+  end # class Connection
+
+  # = D-Bus session bus class
+  #
+  # The session bus is a session specific bus (mostly for desktop use).
+  # This is a singleton class.
+  class SessionBus < Connection
+    include Singleton
+    
+    # Get the the default session bus.
+    def initialize socket_name=SessionSocketName
+      super(socket_name)
+      connect
+      send_hello
+    end
+  end
+
+  # = D-Bus system bus class
+  #
+  # The system bus is a system-wide bus mostly used for global or
+  # system usages.  This is a singleton class.
+  class SystemBus < Connection
+    include Singleton
+
+    # Get the default system bus.
+    def initialize socket_name=SystemSocketName
+      super(socket_name)
+      connect
+      send_hello
+    end
+  end
+
+  # FIXME: we should get rid of these singeltons
+
+  def DBus.system_bus
+    SystemBus.instance
+  end
+
+  def DBus.session_bus
+    SessionBus.instance
+  end
+
+  # = Main event loop class.
+  #
+  # Class that takes care of handling message and signal events
+  # asynchronously.  *Note:* This is a native implement and therefore does
+  # not integrate with a graphical widget set main loop.
+  class Main
+    # Create a new main event loop.
+    def initialize
+      @buses = Hash.new
+    end
+
+    # Add a _bus_ to the list of buses to watch for events.
+    def <<(bus)
+      @buses[bus.socket] = bus
+    end
+
+    # Run the main loop. This is a blocking call!
+    def run
+      loop do
+        ready, dum, dum = IO.select(@buses.keys)
+        ready.each do |socket|
+          b = @buses[socket]
+          begin
+            b.update_buffer
+          rescue EOFError
+            return              # the bus died
+          end
+          while m = b.pop_message
+            b.process(m)
+          end
+        end
+      end
+    end
+  end # class Main
+end # module DBus