ruby-dbus 0.6.0 → 0.7.0

data/doc/tutorial/index.html

@@ -1,365 +0,0 @@
-<style>
-code { background-color: #F0E7E7; }
-pre code { background-color: #F0DDDD; }
-pre {
-     font-size: 90%;
-     overflow: hidden;
-     padding-left: 10pt;
-     border: thin solid #F0B4B4;
-     background-color: #F0DDDD;
-}
-</style>
-
-<h1>Welcome</h1>
-<p>This is the Ruby D-Bus tutorial.  It aims to show you the features of Ruby
-D-Bus and as you read through the tutorial also how to use them.</p>
-<p>&copy; Arnaud Cornet and Paul van Tilburg; this tutorial is part of
-free software; you can redistribute it and/or modify it under the
-terms of the <a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License,
-version 2.1</a> as published by the 
-<a href="http://www.fsf.org/">Free Software Foundation</a>.</p>
-<h1>Introduction</h1>
-<p>This is a tutorial for Ruby D-Bus, a library to access D-Bus facilities of your
-system.</p>
-<h2>What is D-Bus?</h2>
-<p>D-Bus is an RPC(Remote Procedure Call) protocol.  A common setup can have
-multiple D-Bus daemons running that route procedure calls and signals in
-the form of messages.  Each of these daemons supports a bus.  A bus that
-is often used by modern desktop environments, and is available per session, is
-called the <em>session bus</em>.  Another bus that can be available, but in a
-system-wide manner, is called the <em>system bus</em>.  It is used for example by
-the <a href="http://hal.freedesktop.org/">Hardware Abstraction Layer</a> daemon.  Note
-that theoretically the D-Bus RPC protocol can be used without a system or
-session bus.  I never came across any actual use of this though.</p>
-<p>At the desktop level, D-Bus allows some components to interact.  Typically
-if you are writing an application or a personal script that wants to
-interact with your web browser, your music player, or that simply wants to
-pop-up a desktop notification, D-Bus comes into play.</p>
-<p>At the system level, the Hardware Abstraction Layer is a privileged daemon
-that notifies other software of hardware activities.  Typically, if you
-want to be notified if a CD-ROM has been loaded in, of if you want to
-explore hardware, the system daemon comes into play.</p>
-<p>The D-Bus RPC system is as we will see <em>object oriented</em>.</p>
-<p>Buses provide access to <em>services</em> provided in turn by running or ready to
-run processes.  Let me introduce some D-Bus terminology before we discuss
-the API of Ruby D-Bus.</p>
-<h2>Client</h2>
-<p>A D-Bus client is a process that connects to a D-Bus. They issue method
-calls and register to the bus for signals and events.</p>
-<h2>Service</h2>
-<p>A connected client can export some of its objects and let other clients
-call some of its methods.  Such clients typically register a special name
-like <code>org.freedesktop.Notifications</code>, the service name.</p>
-<p>There is slightly different type of service.  They are provided by
-processes that can be launched by a D-Bus daemon on demand.  Once they are
-started by D-Bus they register a service name and behave like another
-client.</p>
-<p>Note that the buses themselves provide the <code>org.freedesktop.DBus</code> service,
-and provide some features through it.</p>
-<h2>Object path</h2>
-<p>An object path is the D-Bus way to specify an object <em>instance</em> address.  A
-service can provide different object instances to the outside world, so
-that external processes can call methods on each of them.  An object path
-is an address of an instance in a very similar way that the path is an
-address of a file on a file system.  For example: 
-<code>/org/freedesktop/Notification</code> is an object path of an object provided by
-the <code>org.freedesktop.Notification</code> service</p>
-<p><strong>Beware</strong>:  service names and object paths can, but do <em>not</em> have to be
-related!  You'll probably encounter a lot of cases though, where the
-object path is a slashed version of the dotted service name.</p>
-<h2>Interface</h2>
-<p>Classically in an object model, classes can implement interfaces. That is,
-some method definitions grouped in an interface. This is exactly what a
-D-Bus interface is as well. In D-Bus interfaces have names. These names must be
-specified on method calls.</p>
-<p>The <code>org.freedesktop.Notification</code> service provides an object instance
-called <code>/org/freedesktop/Notification</code>.  This instance object implements an
-interface called <code>org.freedesktop.Notifications</code>.  It also provides two
-special D-Bus specific interfaces:  <code>org.freedesktop.DBus.Introspect</code> and
-<code>org.freedesktop.DBus.Properties</code>. Again, object paths, service names,
-and interface names can be related but do not have to be.</p>
-<p>Basically the <code>org.freedesktop.DBus.Introspect</code> has an <code>Introspect</code> method,
-that returns XML data describing the <code>/org/freedesktop/Notification</code> object
-interfaces. This is used heavily internally by Ruby D-Bus.</p>
-<h2>Method</h2>
-<p>A method is, well, a method in the classical meaning. It's a function that
-is called in the context of an object instance. Methods have typed
-parameters and return typed return values.</p>
-<h2>Signal</h2>
-<p>Signals are simplified method calls that do not have a return value. They
-do have typed parameters though.</p>
-<h2>Message</h2>
-<p>Method calls, method returns, signals, errors: all are encoded as D-Bus
-messages sent over a bus. They are made of a packet header with source and
-destination address, a type (method call, method reply, signal) and the
-body containing the parameters (for signals and method calls) or the return
-values (for a method return message).</p>
-<h2>Signature</h2>
-<p>Because D-Bus is typed and dynamic, each message comes with a signature that
-describes the types of the data that is contained within the message.  The
-signature is a string with an extremely basic language that only describes
-a data type.  You will need to have some knowledge of what a signature
-looks like if you are setting up a service.  If you are just programming a
-D-Bus client, you can live without knowing about them.</p>
-<h1>Client Usage</h1>
-<p>This chapter discusses basic client usage
-and has the following topics:</p>
-<h2>Using the library</h2>
-<p>If you want to use the library, you have to make Ruby load it by issuing:</p>
-<pre><code>require 'dbus'
-</code></pre>
-<p>That's all!  Now we can move on to really using it...</p>
-<h2>Connecting to a bus</h2>
-<p>On a typical system, two buses are running, the system bus and the session
-bus.  The system bus can be accessed by:</p>
-<pre><code>bus = DBus::SystemBus.instance
-</code></pre>
-<p>Probably you already have guessed how to access the session bus. This
-can be done by:</p>
-<pre><code>bus = DBus::SessionBus.instance
-</code></pre>
-<h2>Performing method calls</h2>
-<p>Let me continue this example using the session bus.  Let's say that I want
-to access an object of some client on the session bus.  This particular
-D-Bus client provides a service called <code>org.gnome.Rhythmbox</code>.  Let me
-access this service:</p>
-<pre><code>rb_service = bus.service("org.gnome.Rhythmbox")
-</code></pre>
-<p>In this example I access the <code>org.gnome.Rhythmbox</code> service, which is
-provided by the application
-<a href="http://www.gnome.org/projects/rhythmbox/">Rhythmbox</a>.
-OK, I have a service handle now, and I know that it exports the object
-"/org/gnome/Rhythmbox/Player".  I will trivially access this remote object
-using:</p>
-<pre><code>rb_player = rb_service.object("/org/gnome/Rhythmbox/Player")
-</code></pre>
-<h2>Introspection</h2>
-<p>Well, that was easy.  Let's say that I know that this particular object is
-introspectable.  In real life most of them are.  The <code>rb_object</code> object we
-have here is just a handle of a remote object, in general they are called
-<em>proxy objects</em>, because they are the local handle of a remote object.  It
-would be nice to be able to make it have methods, and that its methods send
-a D-Bus call to remotely execute the actual method in another process. 
-Well, instating these methods for a <em>introspectable</em> object is trivial:</p>
-<pre><code>rb_player.introspect
-</code></pre>
-<p>And there you go.  Note that not all services or objects can be
-introspected, therefore you have to do this manually!  Let me remind you
-that objects in D-Bus have interfaces and interfaces have methods.  Let's
-now access these methods:</p>
-<pre><code>rb_player_iface = rb_player["org.gnome.Rhythmbox.Player"]
-puts rb_player_iface.getPlayingUri
-</code></pre>
-<p>As you can see, when you want to call a method on an instance object, you have
-to get the correct interface. It is a bit tedious, so we have the following
-shortcut that does the same thing as before:</p>
-<pre><code>rb_player.default_iface = "org.gnome.Rhythmbox.Player"
-puts rb_player.getPlayingUri
-</code></pre>
-<p>The <code>default_iface=</code> call specifies the default interface that should be
-used when non existing methods are called directly on a proxy object, and
-not on one of its interfaces.</p>
-<p>Note that the bus itself has a corresponding introspectable object. You can
-access it with <code>bus.proxy</code> method. For example, you can retrieve an array of
-exported service names of a bus like this:</p>
-<pre><code>bus.proxy.ListNames[0]
-</code></pre>
-<h2>Properties</h2>
-<p>Some D-Bus objects provide access to properties. They are accessed by
-treating a proxy interface as a hash:</p>
-<pre><code>nm_iface = network_manager_object["org.freedesktop.NetworkManager"]
-enabled = nm_iface["WirelessEnabled"]
-puts "Wireless is " + (enabled ? "enabled":"disabled")
-puts "Toggling wireless"
-nm_iface["WirelessEnabled"] = ! enabled
-</code></pre>
-<h2>Calling a method asynchronously</h2>
-<p>D-Bus is <em>asynchronous</em>.  This means that you do not have to wait for a
-reply when you send a message.  When you call a remote method that takes a
-lot of time to process remotely, you don't want your application to hang,
-right?  Well the asychronousness exists for this reason.  What if you dont'
-want to wait for the return value of a method, but still you want to take
-some action when you receive it?</p>
-<p>There is a classical method to program this event-driven mechanism.  You do
-some computation, perform some method call, and at the same time you setup
-a callback that will be triggered once you receive a reply.  Then you run a
-main loop that is responsible to call the callbacks properly.  Here is how
-you do it:</p>
-<pre><code>rb_player.getPlayingUri do |resp|
-    puts "The playing URI is #{resp}"
-end
-puts "See, I'm not waiting!"
-loop = DBus::Main.new
-loop &lt;&lt; bus
-loop.run
-</code></pre>
-<p>This code will print the following:</p>
-<pre><code>See, I'm not waiting!
-The playing URI is file:///music/papapingoin.mp3
-</code></pre>
-<h2>Waiting for a signal</h2>
-<p>Signals are calls from the remote object to your program.  As a client, you
-set yourself up to receive a signal and handle it with a callback.  Then running
-the main loop triggers the callback.  You can register a callback handler
-as allows:</p>
-<pre><code>rb_player.on_signal("elapsedChanged") do |u|
-    puts u
-end
-</code></pre>
-<h2>More about introspection</h2>
-<p>There are various ways to inspect a remote service.  You can simply call
-<code>Introspect()</code> and read the XML output.  However, in this tutorial I assume
-that you want to do it using the Ruby D-Bus API.</p>
-<p>Notice that you can introspect a service, and not only objects:</p>
-<pre><code>rb_service = bus.service("org.gnome.Rhythmbox")
-rb_service.introspect
-p rb_service.root
-</code></pre>
-<p>This dumps a tree-like structure that represents multiple object paths.  In
-this particular case the output is:</p>
-<pre><code>&lt;/: {org =&gt; {gnome =&gt; {Rhythmbox =&gt; {Player =&gt; ..fdbe625de {},Shell =&gt; ..fdbe6852e {},PlaylistManager =&gt; ..fdbe4e340 {}}&gt;
-</code></pre>
-<p>Read this left to right:  the root node is "/", it has one child node "org",
-"org" has one child node "gnome", and "gnome" has one child node "Rhythmbox". 
-Rhythmbox has Tree child nodes "Player", "Shell" and "PlaylistManager". 
-These three last child nodes have a weird digit that means it has an object
-instance.  Such object instances are already introspected.</p>
-<p>If the prose wasn't clear, maybe the following ASCII art will help you:</p>
-<pre><code>/
-    org
-        gnome
-            Rhythmbox
-                Shell (with object)
-                Player (with object)
-                PlaylistManager (with object)
-</code></pre>
-<h3>Walking the object tree</h3>
-<p>You can have an object on any node, i.e. it is not limited to leaves.
-You can access a specific node like this:</p>
-<pre><code>rb_player = rb_service.root["org"]["gnome"]["Rhythmbox"]["Player"]
-rb_player = rb_service.object("/org/gnome/Rhythmbox/Player")
-</code></pre>
-<p>The difference between the two is that for the first one, <code>rb_service</code>
-needs to have been introspected.  Also the obtained <code>rb_player</code> is already
-introspected whereas the second <code>rb_player</code> isn't yet.</p>
-<h2>Errors</h2>
-<p>D-Bus calls can reply with an error instead of a return value. An error is
-translated to a Ruby exception.</p>
-<pre><code>begin
-    network_manager.sleep
-rescue DBus::Error =&gt; e
-    puts e unless e.name == "org.freedesktop.NetworkManager.AlreadyAsleepOrAwake"
-end
-</code></pre>
-<h1>Creating a Service</h1>
-<p>This chapter deals with the opposite side of the basic client usage, namely
-the creation of a D-Bus service.</p>
-<h2>Registering a service</h2>
-<p>Now that you know how to perform D-Bus calls, and how to wait for and
-handle signals, you might want to learn how to publish some object and
-interface to provide them to the D-Bus world.  Here is how you do that.</p>
-<p>As you should already know, D-Bus clients that provide some object to be
-called remotely are services.  Here is how to allocate a name on a bus:</p>
-<pre><code>bus = DBus.session_bus
-service = bus.request_service("org.ruby.service")
-</code></pre>
-<p>Now this client is know to the outside world as <code>org.ruby.service</code>.
-Note that this is a request and it <em>can</em> be denied! When it
-is denied, an exception (<code>DBus::NameRequestError</code>) is thrown.</p>
-<h2>Exporting an object</h2>
-<p>Now, let's define a class that we want to export:</p>
-<pre><code>class Test &lt; DBus::Object
-  # Create an interface.
-  dbus_interface "org.ruby.SampleInterface" do
-    # Create a hello method in that interface.
-    dbus_method :hello, "in name:s, in name2:s" do |name, name2|
-      puts "hello(#{name}, #{name2})"
-    end
-  end
-end
-</code></pre>
-<p>As you can see, we define a <code>Test</code> class in which we define a
-<code>org.ruby.SampleInterface</code> interface.  In this interface, we define a
-method.  The given code block is the method's implementation.  This will be
-executed when remote programs performs a D-Bus call.  Now the annoying part:
-the actual method definition.  As you can guess the call</p>
-<pre><code>dbus_method :hello, "in name:s, in name2:s" do ...
-</code></pre>
-<p>creates a <code>hello</code> method that takes two parameters both of type string. 
-The <em>:s</em> means "of type string".  Let's have a look at some other common
-parameter types:</p>
-<ul>
-<li><em>u</em> means unsigned integer</li>
-<li><em>i</em> means integer</li>
-<li><em>y</em> means byte</li>
-<li><em>(ui)</em> means a structure having a unsigned integer and a signed one.</li>
-<li><em>a</em> means array, so that "ai" means array of integers<ul>
-<li><em>as</em> means array of string</li>
-<li><em>a(is)</em> means array of structures, each having an integer and a string.</li>
-</ul>
-</li>
-</ul>
-<p>For a full description of the available D-Bus types, please refer to the 
-<a href="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures">D-Bus specification</a>.</p>
-<p>Now that the class has been defined, we can instantiate an object
-and export it as follows:</p>
-<pre><code>exported_obj = Test.new("/org/ruby/MyInstance")
-service.export(exported_obj)
-</code></pre>
-<p>This piece of code above instantiates a <code>Test</code> object with a D-Bus object
-path.  This object is reachable from the outside world after
-<code>service.export(exported_obj)</code> is called.</p>
-<p>We also need a loop which will read and process the calls coming over the bus:</p>
-<pre><code>loop = DBus::Main.new
-loop &lt;&lt; bus
-loop.run
-</code></pre>
-<h3>Using the exported object</h3>
-<p>Now, let's consider another program that will access our newly created service:</p>
-<pre><code>ruby_service = bus.service("org.ruby.service")
-obj = ruby_service.object("/org/ruby/MyInstance")
-obj.introspect
-obj.default_iface = "org.ruby.SampleInterface"
-obj.hello("giligiligiligili", "haaaaaaa")
-</code></pre>
-<p>As you can see, the object we defined earlier is automatically introspectable.
-See also "Basic Client Usage".</p>
-<h2>Emitting a signal</h2>
-<p>Let's add some example method so you can see how to return a value to the
-caller and let's also define another example interface that has a signal.</p>
-<pre><code>class Test2 &lt; DBus::Object
-  # Create an interface
-  dbus_interface "org.ruby.SampleInterface" do
-    # Create a hello method in the interface:
-    dbus_method :hello, "in name:s, in name2:s" do |name, name2|
-      puts "hello(#{name}, #{name2})"
-    end
-    # Define a signal in the interface:
-    dbus_signal :SomethingJustHappened, "toto:s, tutu:u"
-  end
-
-  dbus_interface "org.ruby.AnotherInterface" do
-    dbus_method :ThatsALongMethodNameIThink, "in name:s, out ret:s" do |name|
-      ["So your name is #{name}"] 
-    end
-  end
-end
-</code></pre>
-<p>Triggering the signal is a easy as calling a method, but then this time on
-a local (exported) object and not on a remote/proxy object:</p>
-<pre><code>exported_obj.SomethingJustHappened("blah", 1)
-</code></pre>
-<p>Note that the <code>ThatsALongMethodNameIThink</code> method is returning a single
-value to the caller.  Notice that you always have to return an array.  If
-you want to return multiple values, just have an array with multiple
-values.</p>
-<h2>Replying with an error</h2>
-<p>To reply to a dbus_method with a D-Bus error, raise a <code>DBus::Error</code>,
-as constructed by the <code>error</code> convenience function:</p>
-<pre><code>raise DBus.error("org.example.Error.SeatOccupied"), "Seat #{seat} is occupied"
-</code></pre>
-<p>If the error name is not specified, the generic
-<code>org.freedesktop.DBus.Error.Failed</code> is used.</p>
-<pre><code>raise DBus.error, "Seat #{seat} is occupied"
-raise DBus.error
-</code></pre>

data/examples/no-introspect/call-overloaded.rb

@@ -1,22 +0,0 @@
-#!/usr/bin/env ruby
-#
-# How to call overloaded methods.
-
-require 'dbus'
-
-bus = DBus::SessionmBus.instance
-
-konsole_svc = bus["org.freedesktop.konsole"]
-konsole_obj = konsole_svc["/Konsole"]
-poi = DBus::ProxyObjectInterface.new(konsole_obj, "org.kde.konsole.Konsole")
-
-
-begin
-  poi.define_method("getDevices", "") # NM 0.6
-  p poi.getDevices
-rescue Exception
-  poi.define_method("GetDevices", "") # NM 0.7
-  p poi.GetDevices
-end
-
-