rbus 0.1.0

data/Manifest.txt

@@ -0,0 +1,58 @@
+CHANGELOG.txt
+COPYING.txt
+HACKING.txt
+Manifest.txt
+README.txt
+Rakefile
+TUTORIAL.txt
+bin/rbus-send
+examples/async_rb_and_notify.rb
+examples/async_rb_loop.rb
+examples/glib_async_rb_loop.rb
+examples/glib_rhythmbox.rb
+examples/hal_device_info.rb
+examples/listnames.rb
+examples/network_manager_get_properties.rb
+examples/notification_bubble.rb
+examples/rhythmbox_print_playing_uri.rb
+examples/rhythmbox_signal_print_playing.rb
+examples/rhythmbox_start_service.rb
+examples/rhythmbox_toggle_playing.rb
+lib/rbus.rb
+lib/rbus/auth/auth.rb
+lib/rbus/auth/dbus_cookie_sha1.rb
+lib/rbus/auth/dummy.rb
+lib/rbus/auth/external.rb
+lib/rbus/auth/state_machine.rb
+lib/rbus/bus/bus.rb
+lib/rbus/bus/proxy.rb
+lib/rbus/bus/transport.rb
+lib/rbus/default.rb
+lib/rbus/etc/exception.rb
+lib/rbus/etc/log.rb
+lib/rbus/etc/types.rb
+lib/rbus/etc/version.rb
+lib/rbus/glib.rb
+lib/rbus/mainloop/glib.rb
+lib/rbus/mainloop/mainloop.rb
+lib/rbus/mainloop/observers.rb
+lib/rbus/mainloop/thread.rb
+lib/rbus/message/constants.rb
+lib/rbus/message/marshal.rb
+lib/rbus/message/message.rb
+lib/rbus/message/reader.rb
+lib/rbus/message/serial_generator.rb
+lib/rbus/message/unmarshal.rb
+lib/rbus/message/writer.rb
+setup.rb
+spec/auth_spec.rb
+spec/bus_spec.rb
+spec/helpers/bus_mocks.rb
+spec/helpers/spec_helper.rb
+spec/mainloop_spec.rb
+spec/marshal_spec.rb
+spec/message_spec.rb
+spec/observers_spec.rb
+spec/proxy_spec.rb
+spec/transport_spec.rb
+spec/unmarshal_spec.rb

data/README.txt

@@ -0,0 +1,17 @@
+= README for R-Bus
+
+R-Bus is a native implementation of the D-Bus protocol, with these goals in mind:
+
+* Ruby + standard library is the only dependencies
+* A Rubyish API, approach and way of doing things
+* Complete client functionality
+* A comprehensive test suite.
+  
+It's possible that server functionality will be added later, but for now the
+goal is to talk to existing D-Bus servers.
+
+== See also
+
+* {TUTORIAL}[link:files/TUTORIAL_txt.html].
+* {HACKING}[link:files/HACKING_txt.html] for some info on how to help the 
+  development.

data/Rakefile

@@ -0,0 +1,97 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'rbus', 'etc', 'version')
+
+AUTHOR = "Kristoffer Lundén"  # can also be an array of Authors
+EMAIL = "kristoffer.lunden@gmail.com"
+DESCRIPTION = "A native implementation of the D-Bus protocol."
+GEM_NAME = "rbus" # what ppl will type to install your gem
+RUBYFORGE_PROJECT = "rbus" # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+
+
+NAME = "rbus"
+REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = ENV['VERSION'] || (RBus::VERSION::STRING + (REV ? ".#{REV}" : ""))
+                          CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "R-Bus documentation",
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README.txt",
+    "--charset", "utf-8",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/*_test.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  p.spec_extras = {
+    :rdoc_options => RDOC_OPTS,
+    :extra_rdoc_files => ['README.txt','TUTORIAL.txt','HACKING.txt','COPYING.txt','CHANGELOG.txt','bin/rbus-send']
+  }
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+end
+
+desc "Find all TODO's"
+task :todo do
+  FileList['**/*.rb'].egrep(/TODO/)
+end
+
+desc "Insert GPL into all source files"
+task :GPL do
+  gpl = File.readlines('GPL_header.txt')
+  FileList['**/*.rb'].each do |filename|
+    File.open(filename, 'r+') do |file|
+      lines = file.readlines      
+      # Skip shebang line
+      i = (lines[0].index('#!') == 0) ? 1 : 0
+      # Already have header?
+      next if lines[i].index('#--') == 0
+      
+      puts "Liberating #{filename}"
+      
+      file.pos = 0
+      file.print lines.insert(i, gpl).flatten
+      file.truncate(file.pos)
+    end
+  end
+end
+
+require 'spec/rake/spectask'
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+end
+
+desc "Run all specs with RCov"
+Spec::Rake::SpecTask.new('rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.rcov_dir = 'spec/coverage'
+  t.rcov = true
+end

data/TUTORIAL.txt

@@ -0,0 +1,303 @@
+= TUTORIAL
+
+Kristoffer Lundén <kristoffer.lunden@gmail.com>
+
+<em>This is a work in progress. Please also see the examples for more info
+on how to use this library.</em>
+
+== Definitions
+
+[D-Bus] is the protocol, see http://dbus.freedesktop.org
+[R-Bus] is a native implementation of the D-Bus protocol, written in Ruby.
+
+== Connecting to a Bus
+
+To communicate via D-Bus, you need to connect to a bus daemon, that will forward
+the messages between connected application. You do this in R-Bus by creating an
+instance of RBus::Bus, which represents this connection.
+
+On most systems, you will have a Session Bus, that is per login, and a System 
+Bus, that is global for the machine. For special needs and testing, you may also
+want to connect to a non-standard bus. 
+
+The Session and System Bus objects are Singleton objects, meaning that you 
+always get the same object and connection even if you get it several times.
+Apart from this, you can communicate with as many buses as you wish in the same
+application.
+
+There are three convenience methods 
+available for making these connections:
+
+=== Connecting to the Session Bus
+
+  require 'rbus'
+  bus = RBus.session_bus
+  
+This connects to the Session Bus, or returns the already active connection.
+
+=== Connecting to the System Bus
+
+  require 'rbus'
+  bus = RBus.system_bus
+
+This connects to the System Bus, or returns the already active connection.
+
+=== Connecting to a specified address
+
+  require 'rbus'
+  tcp_bus = RBus.get_bus('tcp:host=192.168.0.1,port=6666')
+  unix_bus = RBus.get_bus('unix:path=/tmp/dbus-test')
+  abstract_bus = RBus.get_bus('unix:abstract=/tmp/dbus-lafi7lJhll,guid=a190e4459a37da0c62586ac4de5fa400')
+
+This connects to the given address, which is given in the same form as
+reported by the Bus Daemon.
+
+== Remote objects
+
+D-Bus applications can export objects that other applications can call methods
+on, and receive signals from. A remote object has a <em>well-known name</em>, which
+represents the exporting application, and a <em>object path</em>, which represents the
+object itself. 
+
+Examples of well-known names are <tt>org.freedesktop.NetworkManager</tt> and 
+<tt>org.gnome.Rhythmbox</tt>. Examples of object paths are 
+<tt>/org/freedesktop/NetworkManager/Devices/eth0</tt> and
+<tt>/org/gnome/Rhythmbox/Player</tt>.
+
+Later in this document we will see how to export
+our own objects, but first we will look at interacting with other objects.
+
+== Proxy objects
+
+To communicate with the remote object, we need a local representation of it, a
+Proxy object, that we can call methods on and receive signals from. We can
+obtain a Proxy from the Bus via the method +get_object+, which takes a
+well-known name and an object path as describe above.
+
+  # get the Player object from Rhythmbox:
+  rb_player = session_bus.get_object('org.gnome.Rhythmbox', '/org/gnome/Rhythmbox/Player')
+
+== Method calls
+
+To make method calls on the remote object, we simply call the exact same
+method on the Proxy object. Any method not defined in the Proxy class will be
+forwarded to the other side of the wire. To avoid any collisions with built-in
+methods, the Proxy class is almost completely emptied. Also, to avoid almost any
+possible clash, the few methods that operate on Proxy objects end in '!', such
+as <tt>method!</tt> and <tt>interface!</tt>. It may not be not 100% idiomatic Ruby, so better
+suggestions are welcome. :)
+
+Some examples of method calls:
+
+  # get the uri of the playing song
+  uri = rb_player.getPlayingUri()
+
+  # get information on a HAL device
+  info = device.GetProperty('info.product')
+
+  # pop up a notification bubble
+  notify.Notify('R-Bus',0,'info','R-Bus Notification',
+                'A test example to see that everything works.',[],{},-1)
+
+== Signatures, introspection and data types
+
+D-Bus
+{defines a number of standard data types}[http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures]
+that can be used to send and receive data between applications.
+R-Bus is able to use Rubys standard types for the most part, as long as there is
+a signature available for the conversion. When a new Proxy object is created,
+R-Bus will ask the remote application for a list of methods and signatures via
+the standard methos +Introspect+. If the application provides such a list,
+everything should just work. :)
+
+If the introspection fails, the Proxy object may not know how to call the
+method. In this case you can add the method manually with +method!+:
+
+  obj.method!(:MethodName, 'as')
+
+This would define a method +MethodName+ that takes an Array of Strings.
+
+== Interfaces
+
+D-Bus uses interfaces to provide namespaces for methods. An interface groups 
+methods and signals under a common name, which is a dot-separated name starting
+with a reversed domain name. They are in many cases
+optional, only if an object have multiple methods with the same name, an
+interface is actually needed.
+
+You can use the <tt>interface!</tt> method to set an interface on an object.
+
+Some examples:
+
+  rb_player.interface!('org.gnome.Rhythmbox.Player')
+  puts rb_player.getPlayingUri()
+
+  eth0.interface!('org.freedesktop.NetworkManager.Devices')
+  eth0.getProperties()
+
+<tt>interface!</tt> also returns the object itself, so commands can be chained:
+
+  rb_player.interface!('org.gnome.Rhythmbox.Player').getPlayingUri()
+
+If you want to set an interface temporarily, you can use a block, which will
+get a copy of the object with a temporary interface:
+
+  rb_player.interface!('org.gnome.Rhythmbox.SomethingElse')
+  rb_player.interface!('org.gnome.Rhythmbox.Player') do |p|
+    p.getPlayingUri()
+  end
+  # ...here the interface is +SomethingElse+ again.
+
+== Asynchronous method calls
+
+To make an asynchronous call, simply attach a block to the method call instead 
+of waiting for a reply.
+
+  # from async_rb_loop.rb / glib_async_rb_loop.rb
+  10.times do |i|
+    rb.getPlayingUri() do |uri|
+      sleep(rand(2))
+      puts "#{i}: #{uri}"
+    end
+  end
+
+With the default version of R-Bus, that uses threads, the above code will return
+a list of uris in random order.
+
+With the GLib version, the mainloop needs to be started (see 
+Event loop) and the calls will be returned in the order they were queued.
+You can use the threaded version with GLib/Gtk+ applications if you
+need the extra flexibility though, however, mostly you don't. :)
+
+== Receiving signals
+
+Remote objects can notify listeners of events via signals. To listen to a
+signal on the remote object, call the <tt>connect!</tt> method with a block to 
+process the signal:
+
+  # from rhythmbox_signal_print_playing.rb:
+  # get notifications from Rhythmbox when the song changes
+  rb_player.connect!(:playingUriChanged) { |uri|
+    properties = rb_shell.getSongProperties(uri)
+    duration = Time.at(properties['duration'].to_i).strftime("%M:%S")
+    artist = properties['artist']
+    title = properties['title']
+    puts "Now playing: #{artist} - #{title} (#{duration})"
+    printf "File-size: %.2f MB\n", properties['file-size'].to_f/1024/1024
+  }
+
+  RBus.mainloop
+
+The block will receive whatever data the signal sends.
+
+<tt>connect!</tt> takes the name of the signal, and an optional Hash of
+extra match rules. See
+{Match rules}[http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules]
+in the D-Bus specification for a list of rules.
+
+  obj.connect!(:SignalName, {:arg0 => 'Foo', :arg1 => 'Bar'}) do |*args|
+    # ...
+  end
+
+To receive signals, you need  a mainloop. See the next section for a few more
+details.
+
+== Event loop
+
+To be able to receive signals and answers to asynchronous calls, an event loop
+needs to be running and listening for them. In the dfault version, using
+<tt>require 'rbus'</tt>, such a loop is always started automatically and in
+most cases nothing more neds to be done. However, a word of caution: as it uses
+threads you need to be wary of the same kind of concurrency issues as with
+any Ruby threads.
+
+With the GLib loop, used with <tt>require 'rbus/glib'</tt>, you need to start
+the loop. You can either use <tt>RBus.mainloop</tt> or <tt>Gtk.main</tt>. The
+former simply calls the latter, but you can use it for compatibility with
+other R-Bus mainloops.
+
+You can use <tt>RBus.mainloop</tt> in the threaded version as well to just sit
+idle and wait for signals and method replies.
+
+== Exporting objects
+
+<em>This section has yet to be written, and the functionality is 
+currently missing.</em>
+
+== Starting Services
+
+  require 'rbus'
+  session_bus = RBus.session_bus()
+  
+  # Start Rhythmbox
+  session_bus.StartServiceByName('org.gnome.Rhythmbox', 0)
+  
+== Extra utilities
+
+=== rbus-send
+
+R-Bus comes with its own variant of <em>dbus-send</em>, called 
+<em>{rbus-send}[link:files/bin/rbus-send.html]</em>, which should be pretty much compatible, except for these 
+known issues:
+
+* There is no <tt>--reply-timeout</tt>. Trivial to fix in seconds, though
+  milli-seconds may not be.
+* Currently dumps the any server answer in YAML[http://www.yaml.org/] instead of
+  the dbus-send format.
+
+The invokation looks like this:
+
+  rbus-send <destination object path> <message name> [options] [arguments ...]
+  --dest=NAME                  Specify the name of the connection to receive the message.
+  --print-reply                Block for a reply to the message sent, and print any reply received.
+  --system                     Send to the system message bus.
+  --session                    Send to the session message bus. (This is the default.)
+  --type=TYPE                  Specify "method_call" or "signal" (defaults to "signal").
+
+The object path and the name of the message to send must always be specified.
+Any following non-options are message arguments. These are given as 
+type-specified values and may include containers (arrays, dicts, and variants)
+as follows:
+
+  <arguments>  ::= <item> | <container> [ <item> | <container>...]
+  <item>       ::= <type>:<value>
+  <container>  ::= <array> | <dict> | <variant>
+  <array>      ::= array:<type>:<value>[,<value>...] 
+  <dict>       ::= dict:<type>:<type>:<key>,<value>[,<key>,<value>...]
+  <variant>    ::= variant:<type>:<value>
+  <type>       ::= string | int16 | uint16 | int32 | uint32 | int64 | uint64 | double | byte | boolean | objpath
+
+Some sample queries:
+
+  # List all HAL properties:
+  $ rbus-send --system --print-reply --dest=org.freedesktop.Hal \
+      /org/freedesktop/Hal/devices/computer \
+      org.freedesktop.Hal.Device.GetAllProperties
+
+  # Print URI of current song in Rhythmbox:
+  $ rbus-send --dest='org.gnome.Rhythmbox' --print-reply \
+      /org/gnome/Rhythmbox/Player org.gnome.Rhythmbox.Player.getPlayingUri
+
+  # Toggle play/pause in Rhytmbox:
+  $ rbus-send --dest='org.gnome.Rhythmbox' /org/gnome/Rhythmbox/Player \
+      org.gnome.Rhythmbox.Player.playPause boolean:true
+      
+  # Find services possible to start on the Bus:
+  $ rbus-send --print-reply --dest=org.freedesktop.DBus \
+      /org/freedesktop/DBus org.freedesktop.DBus.ListActivatableNames
+
+  # Start such a service (Rhythmbox in this case):
+  $ rbus-send --type=method_call --dest=org.freedesktop.DBus \
+      /org/freedesktop/DBus org.freedesktop.DBus.StartServiceByName \
+      string:'org.gnome.Rhythmbox' uint32:0
+
+  # Pop up a notification bubble:
+  $ rbus-send --dest=org.freedesktop.Notifications \
+      /org/freedesktop/Notifications org.freedesktop.Notifications.Notify \
+      string:'R-Bus' uint32:0 string:'info' string:'R-Bus Notification' \
+      string:'A test example to see that everything works.' \
+      array:string: dict:string:variant: int32:-1
+
+If you have not installed the library, you can use
+<tt>ruby -Ilib bin/rbus-send [invocation]</tt> from the root of the project
+to try it out.