ruby-dbus 0.5.0

data/doc/tutorial/index.markdown

@@ -0,0 +1,467 @@
+<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>
+
+Welcome
+=======
+
+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.
+
+&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 [GNU Lesser General Public License,
+version 2.1](http://www.gnu.org/licenses/lgpl.html) as published by the 
+[Free Software Foundation](http://www.fsf.org/).
+
+Introduction
+============
+
+This is a tutorial for Ruby D-Bus, a library to access D-Bus facilities of your
+system.
+
+What is D-Bus?
+--------------
+
+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 _session bus_.  Another bus that can be available, but in a
+system-wide manner, is called the _system bus_.  It is used for example by
+the [Hardware Abstraction Layer](http://hal.freedesktop.org/) 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.
+
+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.
+
+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.
+
+The D-Bus RPC system is as we will see _object oriented_.
+
+Buses provide access to _services_ 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.
+
+Client
+------
+
+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.
+
+Service
+-------
+
+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 `org.freedesktop.Notifications`, the service name.
+
+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.
+
+Note that the buses themselves provide the `org.freedesktop.DBus` service,
+and provide some features through it.
+
+Object path
+-----------
+
+An object path is the D-Bus way to specify an object _instance_ 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: 
+`/org/freedesktop/Notification` is an object path of an object provided by
+the `org.freedesktop.Notification` service
+
+**Beware**:  service names and object paths can, but do _not_ 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.
+
+Interface
+---------
+
+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.
+
+The `org.freedesktop.Notification` service provides an object instance
+called `/org/freedesktop/Notification`.  This instance object implements an
+interface called `org.freedesktop.Notifications`.  It also provides two
+special D-Bus specific interfaces:  `org.freedesktop.DBus.Introspect` and
+`org.freedesktop.DBus.Properties`. Again, object paths, service names,
+and interface names can be related but do not have to be.
+
+Basically the `org.freedesktop.DBus.Introspect` has an `Introspect` method,
+that returns XML data describing the `/org/freedesktop/Notification` object
+interfaces. This is used heavily internally by Ruby D-Bus.
+
+Method
+------
+
+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.
+
+Signal
+------
+
+Signals are simplified method calls that do not have a return value. They
+do have typed parameters though.
+
+Message
+-------
+
+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).
+
+Signature
+---------
+
+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.
+
+Client Usage
+============
+
+This chapter discusses basic client usage
+and has the following topics:
+
+Using the library
+-----------------
+
+If you want to use the library, you have to make Ruby load it by issuing:
+
+    require 'dbus'
+
+That's all!  Now we can move on to really using it...
+
+Connecting to a bus
+-------------------
+
+On a typical system, two buses are running, the system bus and the session
+bus.  The system bus can be accessed by:
+
+    bus = DBus::SystemBus.instance
+
+Probably you already have guessed how to access the session bus. This
+can be done by:
+
+    bus = DBus::SessionBus.instance
+
+Performing method calls
+-----------------------
+
+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 `org.gnome.Rhythmbox`.  Let me
+access this service:
+
+    rb_service = bus.service("org.gnome.Rhythmbox")
+
+In this example I access the `org.gnome.Rhythmbox` service, which is
+provided by the application
+[Rhythmbox](http://www.gnome.org/projects/rhythmbox/).
+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:
+
+    rb_player = rb_service.object("/org/gnome/Rhythmbox/Player")
+
+Introspection
+-------------
+
+Well, that was easy.  Let's say that I know that this particular object is
+introspectable.  In real life most of them are.  The `rb_object` object we
+have here is just a handle of a remote object, in general they are called
+_proxy objects_, 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 _introspectable_ object is trivial:
+
+    rb_player.introspect
+
+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:
+
+    rb_player_iface = rb_player["org.gnome.Rhythmbox.Player"]
+    puts rb_player_iface.getPlayingUri
+
+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:
+
+    rb_player.default_iface = "org.gnome.Rhythmbox.Player"
+    puts rb_player.getPlayingUri
+
+The `default_iface=` 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.
+
+Note that the bus itself has a corresponding introspectable object. You can
+access it with `bus.proxy` method. For example, you can retrieve an array of
+exported service names of a bus like this:
+
+    bus.proxy.ListNames[0]
+
+Calling a method asynchronously
+-------------------------------
+
+D-Bus is _asynchronous_.  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?
+
+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:
+
+    rb_player.getPlayingUri do |resp|
+    	puts "The playing URI is #{resp}"
+    end
+    puts "See, I'm not waiting!"
+    loop = DBus::Main.new
+    loop << bus
+    loop.run
+
+This code will print the following:
+
+    See, I'm not waiting!
+    The playing URI is file:///music/papapingoin.mp3
+
+Waiting for a signal
+--------------------
+
+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:
+
+    rb_player.on_signal("elapsedChanged") do |u|
+    	puts u
+    end
+
+More about introspection
+------------------------
+
+There are various ways to inspect a remote service.  You can simply call
+`Introspect()` and read the XML output.  However, in this tutorial I assume
+that you want to do it using the Ruby D-Bus API.
+
+Notice that you can introspect a service, and not only objects:
+
+    rb_service = bus.service("org.gnome.Rhythmbox")
+    rb_service.introspect
+    p rb_service.root
+
+This dumps a tree-like structure that represents multiple object paths.  In
+this particular case the output is:
+
+    </: {org => {gnome => {Rhythmbox => {Player => ..fdbe625de {},Shell => ..fdbe6852e {},PlaylistManager => ..fdbe4e340 {}}>
+
+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.
+
+If the prose wasn't clear, maybe the following ASCII art will help you:
+
+    /
+    	org
+    		gnome
+    			Rhythmbox
+    				Shell (with object)
+    				Player (with object)
+    				PlaylistManager (with object)
+
+### Walking the object tree
+
+You can have an object on any node, i.e. it is not limited to leaves.
+You can access a specific node like this:
+
+    rb_player = rb_service.root["org"]["gnome"]["Rhythmbox"]["Player"]
+    rb_player = rb_service.object("/org/gnome/Rhythmbox/Player")
+
+The difference between the two is that for the first one, `rb_service`
+needs to have been introspected.  Also the obtained `rb_player` is already
+introspected whereas the second `rb_player` isn't yet.
+
+Errors
+------
+
+D-Bus calls can reply with an error instead of a return value. An error is
+translated to a Ruby exception.
+
+    begin
+        network_manager.sleep
+    rescue DBus::Error => e
+        puts e unless e.name == "org.freedesktop.NetworkManager.AlreadyAsleepOrAwake"
+    end
+
+Creating a Service
+==================
+
+This chapter deals with the opposite side of the basic client usage, namely
+the creation of a D-Bus service.
+
+Registering a service
+---------------------
+
+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.
+
+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:
+
+    bus = DBus.session_bus
+    service = bus.request_service("org.ruby.service")
+
+Now this client is know to the outside world as `org.ruby.service`.
+Note that this is a request and it _can_ be denied! When it
+is denied, an exception (`DBus::NameRequestError`) is thrown.
+
+Exporting an object
+-------------------
+
+Now, let's define a class that we want to export:
+
+    class Test < 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
+
+As you can see, we define a `Test` class in which we define a
+`org.ruby.SampleInterface` 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
+
+    dbus_method :hello, "in name:s, in name2:s" do ...
+
+creates a `hello` method that takes two parameters both of type string. 
+The _:s_ means "of type string".  Let's have a look at some other common
+parameter types:
+
+- *u* means unsigned integer
+- *i* means integer
+- *y* means byte
+- *(ui)* means a structure having a unsigned integer and a signed one.
+- *a* means array, so that "ai" means array of integers
+    - *as* means array of string
+    - *a(is)* means array of structures, each having an integer and a string.
+
+For a full description of the available D-Bus types, please refer to the 
+[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures).
+
+Now that the class has been defined, we can instantiate an object
+and export it as follows:
+
+    exported_obj = Test.new("/org/ruby/MyInstance")
+    service.export(exported_obj)
+
+This piece of code above instantiates a `Test` object with a D-Bus object
+path.  This object is reachable from the outside world after
+`service.export(exported_obj)` is called.
+
+We also need a loop which will read and process the calls coming over the bus:
+
+    loop = DBus::Main.new
+    loop << bus
+    loop.run
+
+### Using the exported object
+
+Now, let's consider another program that will access our newly created service:
+
+    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")
+
+As you can see, the object we defined earlier is automatically introspectable.
+See also "Basic Client Usage".
+
+Emitting a signal
+-----------------
+
+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.
+
+    class Test2 < 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
+
+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:
+
+    exported_obj.SomethingJustHappened("blah", 1)
+
+Note that the `ThatsALongMethodNameIThink` 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.
+
+Replying with an error
+----------------------
+
+To reply to a dbus_method with a D-Bus error, raise a `DBus::Error`,
+as constructed by the `error` convenience function:
+
+    raise DBus.error("org.example.Error.SeatOccupied"), "Seat #{seat} is occupied"
+
+If the error name is not specified, the generic
+`org.freedesktop.DBus.Error.Failed` is used.
+
+    raise DBus.error, "Seat #{seat} is occupied"
+    raise DBus.error