ruby-dbus 0.8.0 → 0.9.0

data/NEWS

@@ -5,6 +5,19 @@ Note about bug numbers:
  Issue#1  - http://github.com/mvidner/ruby-dbus/issues#issue/1
  bnc#1    - https://bugzilla.novell.com/show_bug.cgi?id=1
 
+== Ruby D-Bus 0.9.0 - 2012-11-06
+
+Features:
+ * When calling methods, the interface can be left unspecified if unambiguous
+  (Damiano Stoffie)
+ * YARD documentation, Reference.md
+
+Bug fixes:
+ * Introspection attribute "direction" can be omitted
+   as allowed by the specification (Noah Meyerhans).
+ * ProxyObjectInterface#on_signal no longer needs the "bus" parameter
+   (Issue#31, by Damiano Stoffie)
+
 == Ruby D-Bus 0.8.0 - 2012-09-20
 
 Features:

data/{README → README.md}

@@ -1,17 +1,17 @@
-= Ruby D-Bus README
+# Ruby D-Bus README
 
 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.
 
-== Requirements
+## Requirements
 
- * Ruby 1.8.7 or 1.9
+- Ruby 1.8.7 or 1.9
 
-== Installation
+## Installation
 
- * gem install ruby-dbus
+- `gem install ruby-dbus`
 
-== Feature
+## Features
 
 Ruby D-Bus currently supports the following features:
 
@@ -27,14 +27,14 @@ Ruby D-Bus currently supports the following features:
    allows for introspection.
  * Emitting signals on exported objects.
 
-== Usage
+## Usage
 
  See some of the examples in the examples/ subdirectory of the tarball.
- Also, check out the included tutorial (in Markdown format) in doc/tutorial/
+ Also, check out the included tutorial (in Markdown format) in doc/Tutorial.md
  or view it online on
- https://github.com/mvidner/ruby-dbus/blob/master/doc/tutorial/index.markdown .
+ <https://github.com/mvidner/ruby-dbus/blob/master/doc/Tutorial.md> .
 
-== License
+## 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

data/Rakefile

@@ -1,6 +1,5 @@
 #! /usr/bin/env ruby
 require 'rake'
-require 'rake/gempackagetask'
 require 'fileutils'
 include FileUtils
 require 'tmpdir'
@@ -33,10 +32,9 @@ end
   end
 end
 
-load "ruby-dbus.gemspec"
-
-Rake::GemPackageTask.new(GEMSPEC) do |pkg|
-  # no other formats needed
+desc "Build the gem file"
+task :package do
+  sh "gem build ruby-dbus.gemspec"
 end
 
 desc "Build a package from a clone of the local Git repo"
@@ -46,7 +44,7 @@ task :package_git do |t|
     cd temp do
       sh "rake package"
     end
-    cp_r "#{temp}/pkg", "."
+    cp Dir.glob("#{temp}/*.gem"), "."
   end
 end
 
@@ -56,9 +54,3 @@ Rake::RDocTask.new do |rd|
 #  rd.options << "--diagram"
 #  rd.options << "--all"
 end
-
-desc "Render the tutorial in HTML"
-task :tutorial => "doc/tutorial/index.html"
-file "doc/tutorial/index.html" => "doc/tutorial/index.markdown" do |t|
-  sh "markdown #{t.prerequisites[0]} > #{t.name}"
-end

data/VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

data/doc/Reference.md

@@ -0,0 +1,196 @@
+Ruby D-Bus Reference
+====================
+
+This is a reference-style documentation. It's not [a tutorial for
+beginners](http://dbus.freedesktop.org/doc/dbus-tutorial.html), the
+reader should have knowledge of basic DBus concepts.
+
+Client Side
+-----------
+
+This section should be enough if you only want to consume DBus APIs.
+
+### Basic Concepts
+
+#### Setting Up
+
+The following code is assumed as a prolog to all following ones
+
+{include:file:doc/ex-setup.rb}    
+
+#### Calling Methods
+
+1. {DBus.session_bus Connect to the session bus};
+   {DBus::Connection#[] get the screensaver service}
+   {DBus::Service#object and its screensaver object}.
+2. Perform {DBus::ProxyObject#introspect explicit introspection}
+   to define the interfaces and methods
+   on the {DBus::ProxyObject object proxy}
+([I#28](https://github.com/mvidner/ruby-dbus/issues/28)).
+3. Call one of its methods in a loop, solving [xkcd#196](http://xkcd.com/196).
+
+{include:file:doc/ex-calling-methods.body.rb}
+
+##### Retrieving Return Values
+
+A method proxy always returns an array of values. This is to
+accomodate the rare cases of a DBus method specifying more than one
+*out* parameter. For nearly all methods you should use `Method[0]` or
+`Method.first`
+([I#30](https://github.com/mvidner/ruby-dbus/issues/30)).
+
+    
+    # wrong
+    if upower_i.SuspendAllowed    # [false] is true!
+      upower_i.Suspend
+    end
+
+    # right
+    if upower_i.SuspendAllowed[0]
+      upower_i.Suspend
+    end
+
+#### Accessing Properties
+
+To access properties, think of the {DBus::ProxyObjectInterface interface} as a
+{DBus::ProxyObjectInterface#[] hash} keyed by strings,
+or use {DBus::ProxyObjectInterface#all_properties} to get
+an actual Hash of them.
+
+{include:file:doc/ex-properties.body.rb}
+
+(TODO a writable property example)
+
+Note that unlike for methods where the interface is inferred if unambiguous,
+for properties the interface must be explicitly chosen.
+That is because {DBus::ProxyObject} uses the {DBus::ProxyObject Hash#[]} API
+to provide the {DBus::ProxyObjectInterface interfaces}, not the properties.
+
+#### Asynchronous Operation
+
+If a method call has a block attached, it is asynchronous and the block
+is invoked on receiving a method_return message or an error message
+
+##### Main Loop
+
+For asynchronous operation an event loop is necessary. Use {DBus::Main}:
+
+    # [set up signal handlers...]
+    main = DBus::Main.new
+    main << mybus
+    main.run
+
+Alternately, run the GLib main loop and add your DBus connections to it via
+{DBus::Connection#glibize}.
+
+#### Receiving Signals
+
+To receive signals for a specific object and interface, use
+{DBus::ProxyObjectInterface#on\_signal}(name, &block) or
+{DBus::ProxyObject#on_signal}(name, &block), for the default interface.
+
+{include:file:doc/ex-signal.body.rb}
+
+### Intermediate Concepts
+#### Names
+#### Types and Values, D-Bus -> Ruby
+
+D-Bus booleans, numbers, strings, arrays and dictionaries become their straightforward Ruby counterparts.
+
+Structs become arrays.
+
+Object paths become strings.
+
+Variants are simply unpacked to become their contained type.
+(ISSUE: prevents proper round-tripping!)
+
+#### Types and Values, Ruby -> D-Bus
+
+D-Bus has stricter typing than Ruby, so the library must decide
+which D-Bus type to choose. Most of the time the choice is dictated
+by the D-Bus signature. However if the signature expects a Variant
+(which is the case for all Properties!) then an explicit mechanism is needed.
+
+1. A pair [{DBus::Type::Type}, value] specifies to marshall *value* as
+   that specified type.
+   The pair can be produced by {DBus.variant}(signature, value) which
+   gives the  same result as [{DBus.type}(signature), value].
+
+   ISSUE: using something else than cryptic signatures is even more painful
+   than remembering the signatures!
+
+2. Other values are tried to fit one of these:
+   Boolean, Double, Array of Variants, Hash of String keyed Variants,
+   String, Int32, Int64.
+
+3. **Deprecated:** A pair [String, value], where String is a valid
+   signature of a single complete type, marshalls value as that
+   type. This will hit you when you rely on method (2) but happen to have
+   a particular string value in an array.
+
+
+`nil` is not allowed by D-Bus and attempting to send it raises an exception
+(but see [I#16](https://github.com/mvidner/ruby-dbus/issues/16)).
+
+    foo_i['Bar'] = DBus.variant("au", [0, 1, 1, 2, 3, 5, 8])
+
+
+#### Errors
+
+D-Bus calls can reply with an error instead of a return value. An error is
+translated to a Ruby exception, an instance of {DBus::Error}.
+
+    begin
+        network_manager.sleep
+    rescue DBus::Error => e
+        puts e unless e.name == "org.freedesktop.NetworkManager.AlreadyAsleepOrAwake"
+    end
+
+#### Interfaces
+
+Methods, properties and signals of a D-Bus object always belong to one of its interfaces.
+
+Methods can be called without specifying their interface, as long as there is no ambiguity.
+There are two ways to resolve ambiguities:
+
+1. assign an interface name to {DBus::ProxyObject#default_iface}.
+
+2. get a specific {DBus::ProxyObjectInterface interface} of the object,
+with {DBus::ProxyObject#[]} and call methods from there.
+
+Signals and properties only work with a specific interface.
+
+#### Thread Safety
+Not there. An [incomplete attempt] was made.
+### Advanced Concepts
+#### Bus Addresses
+#### Without Introspection
+#### Name Overloading
+
+Service Side
+------------
+
+When you want to provide a DBus API.
+
+(check that client and service side have their counterparts)
+
+### Basic
+#### Exporting a Method
+##### Interfaces
+##### Methods
+##### Bus Names
+##### Errors
+#### Exporting Properties
+### Advanced
+#### Inheritance
+#### Names
+
+Specification Conformance
+-------------------------
+
+This section lists the known deviations from version 0.19 of
+[the specification][spec].
+
+[spec]: http://dbus.freedesktop.org/doc/dbus-specification.html
+
+1. Properties support is basic.

data/doc/ex-calling-methods.body.rb

@@ -0,0 +1,8 @@
+mybus = DBus.session_bus
+service = mybus['org.freedesktop.ScreenSaver']
+object = service.object '/ScreenSaver'
+object.introspect
+loop do
+    object.SimulateUserActivity
+    sleep 5 * 60
+end

data/doc/ex-calling-methods.rb

@@ -0,0 +1,3 @@
+#! /usr/bin/env ruby
+require 'example-helper.rb'
+example 'ex-calling-methods.body.rb'

data/doc/ex-properties.body.rb

@@ -0,0 +1,9 @@
+sysbus = DBus.system_bus
+upower_s = sysbus['org.freedesktop.UPower']
+upower_o = upower_s.object '/org/freedesktop/UPower'
+upower_o.introspect
+upower_i = upower_o['org.freedesktop.UPower']
+
+on_battery = upower_i['OnBattery']
+
+puts "Is the computer on battery now? #{on_battery}"

data/doc/ex-properties.rb

@@ -0,0 +1,3 @@
+#! /usr/bin/env ruby
+require 'example-helper.rb'
+example 'ex-properties.body.rb'

data/doc/ex-setup.rb

@@ -0,0 +1,7 @@
+#! /usr/bin/env ruby
+require 'rubygems'  # Not needed since Ruby 1.9
+require 'dbus'      # The gem is 'ruby-dbus' but the require is 'dbus'
+
+# Connect to a well-known address. Most apps need only one of them.
+mybus  = DBus.session_bus
+sysbus = DBus.system_bus

data/doc/ex-signal.body.rb

@@ -0,0 +1,20 @@
+sysbus = DBus.system_bus
+login_s = sysbus['org.freedesktop.login1'] # part of systemd
+login_o = login_s.object '/org/freedesktop/login1'
+login_o.introspect
+login_o.default_iface = 'org.freedesktop.login1.Manager'
+
+# to trigger this signal, login on the Linux console
+login_o.on_signal("SessionNew") do |name, opath|
+  puts "New session: #{name}"
+
+  session_o = login_s.object(opath)
+  session_o.introspect
+  session_i = session_o['org.freedesktop.login1.Session']
+  uid, user_opath = session_i['User']
+  puts "Its UID: #{uid}"
+end
+
+main = DBus::Main.new
+main << sysbus
+main.run

data/doc/ex-signal.rb

@@ -0,0 +1,3 @@
+#! /usr/bin/env ruby
+require 'example-helper.rb'
+example 'ex-signal.body.rb'

data/doc/example-helper.rb

@@ -0,0 +1,6 @@
+# Fin
+$:.unshift File.expand_path("../../lib", __FILE__)
+load 'ex-setup.rb'
+def example(filename)
+  eval(File.read(filename), binding, filename, 1)
+end

data/lib/dbus.rb

@@ -12,7 +12,8 @@ require 'dbus/type'
 require 'dbus/introspect'
 require 'dbus/error'
 require 'dbus/export'
-require 'dbus/bus.rb'
+require 'dbus/bus'
+require 'dbus/logger'
 require 'dbus/marshall'
 require 'dbus/message'
 require 'dbus/matchrule'

data/lib/dbus/auth.rb

@@ -6,8 +6,6 @@
 # License, version 2.1 as published by the Free Software Foundation.
 # See the file "COPYING" for the exact licensing terms.
 
-$debug = $DEBUG #it's all over the state machine
-
 require 'rbconfig'
 
 module DBus
@@ -74,12 +72,12 @@ module DBus
       c_challenge = Array.new(s_challenge.bytesize/2).map{|obj|obj=rand(255).to_s}.join
       # Search cookie file for id
       path = File.join(ENV['HOME'], '.dbus-keyrings', context)
-      puts "DEBUG: path: #{path.inspect}" if $debug
+      DBus.logger.debug "path: #{path.inspect}"
       File.foreach(path) do |line|
         if line.index(id) == 0
           # Right line of file, read cookie
           cookie = line.split(' ')[2].chomp
-          puts "DEBUG: cookie: #{cookie.inspect}" if $debug
+          DBus.logger.debug "cookie: #{cookie.inspect}"
           # Concatenate and encrypt
           to_encrypt = [s_challenge, c_challenge, cookie].join(':')
           sha = Digest::SHA1.hexdigest(to_encrypt)
@@ -158,7 +156,7 @@ module DBus
         raise AuthenticationFailed if @auth_list.size == 0
         @authenticator = @auth_list.shift.new
         auth_msg = ["AUTH", @authenticator.name, @authenticator.authenticate]
-        puts "DEBUG: auth_msg: #{auth_msg.inspect}" if $debug
+        DBus.logger.debug "auth_msg: #{auth_msg.inspect}"
         send(auth_msg)
       rescue AuthenticationFailed
         @socket.close
@@ -179,7 +177,7 @@ module DBus
         break if data.include? crlf #crlf means line finished, the TCP socket keeps on listening, so we break 
       end
       readline = data.chomp.split(" ")
-      puts "DEBUG: readline: #{readline.inspect}" if $debug
+      DBus.logger.debug "readline: #{readline.inspect}"
       return readline
     end
 
@@ -195,7 +193,7 @@ module DBus
     def next_state
       msg = next_msg
       if @state == :Starting
-        puts "DEBUG: :Starting msg: #{msg[0].inspect}" if $debug
+        DBus.logger.debug ":Starting msg: #{msg[0].inspect}"
         case msg[0]
         when "OK"
           @state = :WaitingForOk    
@@ -205,15 +203,15 @@ module DBus
           @state = :WaitingForData
         end
       end
-      puts "DEBUG: state: #{@state}" if $debug
+      DBus.logger.debug "state: #{@state}"
       case @state
       when :WaitingForData
-        puts "DEBUG: :WaitingForData msg: #{msg[0].inspect}" if $debug
+        DBus.logger.debug ":WaitingForData msg: #{msg[0].inspect}"
         case msg[0]
         when "DATA"
           chall = msg[1]
           resp, chall = @authenticator.data(chall)
-          puts "DEBUG: :WaitingForData/DATA resp: #{resp.inspect}" if $debug
+          DBus.logger.debug ":WaitingForData/DATA resp: #{resp.inspect}"
           case resp
           when :AuthContinue
             send("DATA", chall)
@@ -239,7 +237,7 @@ module DBus
           @state = :WaitingForData
         end
       when :WaitingForOk
-        puts "DEBUG: :WaitingForOk msg: #{msg[0].inspect}" if $debug
+        DBus.logger.debug ":WaitingForOk msg: #{msg[0].inspect}"
         case msg[0]
         when "OK"
           send("BEGIN")
@@ -255,7 +253,7 @@ module DBus
           @state = :WaitingForOk
         end
       when :WaitingForReject
-        puts "DEBUG: :WaitingForReject msg: #{msg[0].inspect}" if $debug
+        DBus.logger.debug ":WaitingForReject msg: #{msg[0].inspect}"
         case msg[0]
         when "REJECT"
           next_authenticator