em-ruby-dbus 0.11.0

data/NEWS

@@ -0,0 +1,253 @@
+= Ruby D-Bus NEWS
+
+Note about bug numbers:
+ Ticket#1 - https://trac.luon.net/ruby-dbus/ticket/1
+ 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.11.0 - 2014-02-17
+
+API:
+ * Connection: split off MessageQueue, marked other methods as private.
+
+Requirements:
+ * converted tests to RSpec, rather mechanically for now
+
+== Ruby D-Bus 0.10.0 - 2014-01-10
+
+Bug fixes:
+ * fixed "Interfaces added with singleton_class.instance_eval aren't
+   exported" (Issue#22, by miaoufkirsh)
+
+Requirements:
+ * Require ruby 1.9.3, stopped supporting 1.8.7.
+
+== Ruby D-Bus 0.9.3 - 2014-01-02
+
+Bug fixes:
+ * re-added COPYING, NEWS, README.md to the gem (Issue#47,
+   by Cédric Boutillier)
+
+Packaging:
+ * use packaging_rake_tasks
+
+== Ruby D-Bus 0.9.2 - 2013-05-08
+
+Features:
+ * Ruby strings can be passed where byte arrays ("ay") are expected 
+   (Issue#40, by Jesper B. Rosenkilde)
+
+Bug fixes:
+ * Fixed accessing ModemManager properties (Issue#41, reported
+   by Ernest Bursa). MM introspection produces two elements
+   for a single interface; merge them.
+
+== Ruby D-Bus 0.9.1 - 2013-04-23
+
+Bug fixes:
+ * Prefer /etc/machine-id to /var/lib/dbus/machine-id
+   when DBUS_SESSION_BUS_ADDRESS is unset (Issue#39, by WU Jun).
+
+== 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:
+ * Add Anonymous authentication (Issue#27, by Walter Brebels).
+ * Use Nokogiri for XML parsing when available (Issue#24, by Geoff Youngs).
+
+Bug fixes:
+ * Use SCM_CREDS authentication only on FreeBSD, not on OpenBSD (Issue#21,
+   reported by Adde Nilsson).
+ * Recognize signature "h" (UNIX_FD) used eg. by Upstart (Issue#23,
+   by Bernd Ahlers).
+ * Find the session bus also via launchd, on OS X (Issue#20, reported
+   by Paul Sturgess).
+
+Other:
+ * Now doing continuous integration with Travis:
+     http://travis-ci.org/#!/mvidner/ruby-dbus
+
+
+== Ruby D-Bus 0.7.2 - 2012-04-05
+
+A brown-paper-bag release.
+
+Bug fixes:
+ * Fixed "undefined local variable or method `continue'" in
+   DBus::Main#run when a service becomes idle (by Ravil Bayramgalin)
+
+== Ruby D-Bus 0.7.1 - 2012-04-04
+
+Bug fixes:
+ * Fixed calling asynchronous methods on the default interface (Issue#13,
+   by Eugene Korbut). 
+ * Fixed Main#quit to really quit the loop (by Josef Reidinger)
+ * Unbundled files from Active Support (by Bohuslav Kabrda)
+
+== Ruby D-Bus 0.7.0 - 2011-07-26
+
+Features:
+ * Added ASystemBus and ASessionBus, non-singletons useful in tests
+   and threads.
+
+Bug fixes:
+ * Fixed handling of multibyte strings (Issue#8, by Takayuki YAMAGUCHI).
+ * Allow reopening of a dbus_interface declaration (Issue#9, by T. YAMAGUCHI).
+ * Fixed ruby-1.9.2 compatibility again (Issue#12).
+ * Fixed authentication on BSD (Issue#11, by Jonathan Walker)
+ * Fixed exiting a nested event loop for synchronous calls
+   (reported by Timo Warns).
+ * Fixed introspection calls leaking reply handlers.
+ * "rake test" now works, doing what was called "rake env:test"
+
+== Ruby D-Bus 0.6.0 - 2010-12-11
+
+Features:
+ * Clients can access properties conveniently (Ticket#28).
+
+Bug fixes:
+ * Service won't crash whan handling an unknown method or interface (Ticket#31).
+ * Don't send an invalid error name when it originates from a NameError.
+
+== Ruby D-Bus 0.5.0 - 2010-11-07
+
+Features:
+ * Better binding of Ruby Exceptions to D-Bus Errors.
+ * Converted the package to a Gem (Issue#6).
+ * Converted the tutorial from Webgen to Markdown.
+
+Bug fixes:
+ * Don't pass file descriptors to subprocesses.
+ * Fixed InterfaceElement::validate_name (Ticket#38, by Herwin Weststrate).
+ * Fixed a typo in InvalidDestinationName description (Ticket#40).
+
+== Ruby D-Bus 0.4.0 - 2010-08-20
+
+Features:
+ * TCP transport (by pangdudu)
+ * Enabled test code coverage report (rcov)
+
+Bug fixes:
+ * Classes should not share all interfaces (Ticket#36/Issue#5)
+ * Ruby 1.9 compatibility (Ticket#37, by Myra Nelson)
+
+== Ruby D-Bus 0.3.1 - 2010-07-22
+
+Bug fixes:
+ * Many on_signal could cause DBus.Error.LimitsExceeded bnc#617350).
+   Don't add a match rule that already exists, enable removing match
+   rules. Now only one handler for a rule is called (but it is possible
+   for one signal to match more rules). This reverts the half-fix done
+   to fix Issue#3
+ * Re-added InterfaceElement#add_param for compatibility.
+ * Handle more ways which tell us that a bus connection has died.
+
+== Ruby D-Bus 0.3.0 - 2010-03-28
+
+Bug fixes:
+ 
+ * Fixed "undefined method `get_node' for nil:NilClass"
+   on Ubuntu Karmic (Ticket#34).
+ * Get the session bus address even if unset in ENV (Issue#4).
+ * Improved exceptions a bit:
+   UndefinedInterface, InvalidMethodName, NoMethodError, no RuntimeException
+
+ These are by Klaus Kaempf:
+ * Make the signal dispatcher call all handlers (Issue#3).
+ * Run on Ruby < 1.8.7 (Issue#2).
+ * Avoid needless DBus::IncompleteBufferException (Ticket#33).
+ * Don't ignore DBus Errors in request_service, raise them (Ticket#32).
+
+Features:
+
+ * Automatic signature inference for variants.
+ * Introduced FormalParameter where a plain pair had been used.
+
+== Ruby D-Bus 0.2.12 - 2010-01-24
+
+Bug fixes:
+
+ * Fixed a long-standing bug where a service activated by the bus
+   would fail with "undefined method `get_node' for nil:NilClass"
+   (Tickets#25 and #29).
+
+== Ruby D-Bus 0.2.11 - 2009-11-12
+
+Features:
+
+ * Added DBus::Service#unexport (da1l6).
+
+Bug fixes:
+
+ * Return org.freedesktop.DBus.Error.UnknownObject instead of crashing
+   (Ticket#31).
+ * Rescue exceptions in dbus_methods and reply with DBus errors instead of
+   crashing (da1l6).
+ * Better exception messages when sending nil, or mismatched structs.
+ * Call mktemp without --tmpdir, to build on older distros.
+
+== Ruby D-Bus 0.2.10 - 2009-09-10
+
+Bug fixes:
+
+ * DBus::Service.exists? fixed (Murat Demirten).
+ * Ruby 1.9 fixes (Jedediah Smith).
+ * Fixed an endless sleep in DBus::Main.run (bnc#537401).
+ * Added details to PacketMarshaller exceptions (bnc#538050).
+
+(bnc#FOO refers to https://bugzilla.novell.com/show_bug.cgi?id=FOO )
+
+== Ruby D-Bus "I'm not dead" 0.2.9 - 2009-08-26
+
+Thank you to Paul and Arnaud for starting the project. I, Martin
+Vidner, am continuing with it on GitHub.
+
+ * Fixed passing an array through a variant (no ticket).
+ * Fixed marshalling "av" (Ticket #30).
+ * Fixed variant alignment (Ticket #27).
+ * Added DBus::Main.quit.
+ * Mention the DBus interface in a NameError for an unknown method.
+ * Fixed ruby-1.9 "warning: default `to_a' will be obsolete".
+ * Added Rakefile and gemspec.
+
+== Ruby D-Bus "Thanks for all the fish" 0.2.1 - 2007-12-29
+
+More bugfixes, mostly supplied by users supplying us with patches.  Thanks!
+
+ * Support for new types added: 
+   - dict (courtesy of Drake Wilson);
+   - double (courtesy of Patrick Sissons);
+   - variant.
+ * Improved exception raise support (courtesy of Sjoerd Simons,
+   Patrick Sissons).
+ * Some polish (removed debug output, solved unnecessary warnings).
+ * Documentation updates, example fixes and updates.
+
+== Ruby D-Bus "Almost live from DebConf 7" 0.2.0 - 2007-06-02
+
+Again a bugfix release, also meant to be the public release
+for exploratory purposes. New in 0.2.0:
+
+ * Complete tutorial revamp.
+ * Relicensed to the LGPL.
+
+== Ruby D-Bus "Release Often" 0.1.1 - 2007-04-23
+
+Bugfix release.  Fixes hardcoded string for requesting bus names,
+found by Rudi Cilibrasi.
+
+== Ruby D-Bus "Happy Birthday Paul" 0.1.0 - 2007-04-17
+
+First release. Supports most of D-Bus' features.

data/README.md

@@ -0,0 +1,93 @@
+# Ruby D-Bus (with EventMachine support)
+
+## Note
+
+This fork works in the same way as [original Ruby D-Bus bindings](https://github.com/mvidner/ruby-dbus)
+but it supports [EventMachine](http://rubyeventmachine.com).
+
+You can bind it to the EM by calling `#eventmachinize`:
+
+    @connection = DBus::SessionBus.instance
+    @connection.eventmachinize
+
+## (Original README)
+
+[D-Bus](http://dbus.freedesktop.org) is an interprocess communication
+mechanism for Linux.
+Ruby D-Bus is a pure Ruby library for writing clients and services for D-Bus.
+
+[![Gem Version][GV img]][Gem Version]
+[![Build Status][BS img]][Build Status]
+[![Dependency Status][DS img]][Dependency Status]
+[![Code Climate][CC img]][Code Climate]
+[![Coverage Status][CS img]][Coverage Status]
+
+[Gem Version]: https://rubygems.org/gems/ruby-dbus
+[Build Status]: https://travis-ci.org/mvidner/ruby-dbus
+[travis pull requests]: https://travis-ci.org/mvidner/ruby-dbus/pull_requests
+[Dependency Status]: https://gemnasium.com/mvidner/ruby-dbus
+[Code Climate]: https://codeclimate.com/github/mvidner/ruby-dbus
+[Coverage Status]: https://coveralls.io/r/mvidner/ruby-dbus
+
+[GV img]: https://badge.fury.io/rb/ruby-dbus.png
+[BS img]: https://travis-ci.org/mvidner/ruby-dbus.png
+[DS img]: https://gemnasium.com/mvidner/ruby-dbus.png
+[CC img]: https://codeclimate.com/github/mvidner/ruby-dbus.png
+[CS img]: https://coveralls.io/repos/mvidner/ruby-dbus/badge.png?branch=master
+
+## Example
+
+Check whether the system is on battery power
+via [UPower](http://upower.freedesktop.org/docs/UPower.html#UPower:OnBattery)
+
+    require "dbus"
+    sysbus = DBus.system_bus
+    upower_service   = sysbus["org.freedesktop.UPower"]
+    upower_object    = upower_service.object "/org/freedesktop/UPower"
+    upower_object.introspect
+    upower_interface = upower_object["org.freedesktop.UPower"]
+    on_battery       = upower_interface["OnBattery"]
+    if on_battery
+      puts "The computer IS on battery power."
+    else
+      puts "The computer IS NOT on battery power."
+    end
+
+## Requirements
+
+- Ruby 1.9.3 or 2.0
+
+
+## Installation
+
+- `gem install em-ruby-dbus`
+
+## 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.
+
+## 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.md
+ or view it online on
+ <https://github.com/mvidner/ruby-dbus/blob/master/doc/Tutorial.md> .
+
+## 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/Rakefile

@@ -0,0 +1,58 @@
+#! /usr/bin/env ruby
+require 'rake'
+require 'fileutils'
+include FileUtils
+require 'tmpdir'
+require 'rspec/core/rake_task'
+
+require "packaging"
+
+Packaging.configuration do |conf|
+  conf.obs_project = "devel:languages:ruby:extensions"
+  conf.package_name = "rubygem-ruby-dbus"
+  conf.obs_sr_project = "openSUSE:Factory"
+  conf.skip_license_check << /^[^\/]*$/
+  conf.skip_license_check << /^(doc|examples|test)\/.*/
+  # "Ruby on Rails is released under the MIT License."
+  # but the files are missing copyright headers
+  conf.skip_license_check << /^lib\/dbus\/core_ext\//
+end
+
+desc 'Default: run specs in the proper environment'
+task :default => :spec
+task :test => :spec
+
+RSpec::Core::RakeTask.new("bare:spec") do |t|
+  t.pattern = "**/test/**/*_spec.rb"
+  t.rspec_opts = "--color --format doc"
+end
+
+%w(spec).each do |tname|
+  desc "Run bare:#{tname} in the proper environment"
+  task tname do |t|
+    cd "test/tools" do
+      sh "./test_env rake bare:#{tname}"
+    end
+  end
+end
+
+if ENV["TRAVIS"]
+  require "coveralls/rake/task"
+  Coveralls::RakeTask.new
+  task :default => "coveralls:push"
+end
+
+#remove tarball implementation and create gem for this gemfile
+Rake::Task[:tarball].clear
+
+desc "Build a package from a clone of the local Git repo"
+task :tarball do |t|
+  Dir.mktmpdir do |temp|
+    sh "git clone . #{temp}"
+    cd temp do
+      sh "gem build ruby-dbus.gemspec"
+    end
+    sh "rm -f package/*.gem"
+    cp Dir.glob("#{temp}/*.gem"), "package"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.11.0

data/doc/Reference.md

@@ -0,0 +1,207 @@
+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.
+
+##### Variants
+
+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!
+
+        foo_i['Bar'] = DBus.variant("au", [0, 1, 1, 2, 3, 5, 8])
+
+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.
+
+##### Byte Arrays
+
+If a byte array (`ay`) is expected you can pass a String too.
+The bytes sent are according to the string's
+[encoding](http://ruby-doc.org/core-1.9.3/Encoding.html).
+
+##### nil
+
+`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)).
+
+
+#### 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](https://github.com/mvidner/ruby-dbus/tree/multithreading) 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.