Net::DBus::Tutorial::ExportingObjects 0.33.4

Net::DBus::Tutorial::ExportingObjects is a Perl module that contains tutorials on providing a DBus service.

This document provides a tutorial on providing a DBus service using the Perl Net::DBus application bindings. This examples in this document will be based on the code from the Music::Player distribution, which is a simple DBus service providing a music track player.

CREATING AN OBJECT

The first step in creating an object is to create a new package which inherits from Net::DBus::Object. The Music::Player::Manager object provides an API for managing the collection of music player backends for different track types. To start with, lets create the skeleton of the package & its constructor. The constructor of the super type, Net::DBus::Object expects to be given to parameters, a handle to the Net::DBus::Service owning the object, and a path under which the object shall be exported. Since the manager class is intended to be a singleton object, we can hard code the path to it within the constructor:

package Music::Player::Manager;

use base qw(Net::DBus);

sub new {
my $class = shift;
my $service = shift;
my $self = $class->SUPER::new($service, "/music/player/manager");

bless $self, $class;

return $self;
}

1;

Now, as mentioned, the manager with handle a number of different player backends. So we need to provide methods for registering new backends, and querying for backends capable of playing a particular file type. So modifying the above code we add a hash table in the constructor, to store the backends:

sub new {
my $class = shift;
my $service = shift;
my $self = $class->SUPER::new($service, "/music/player/manager");

$self->{backends} = {};

bless $self, $class;

return $self;
}

And now a method to register a new backend. This takes a Perl module name and uses it to instantiate a backend. Since the backends are also going to be DBus objects, we need to pass in a reference to the service we are attached to, along with a path under which to register the backend.

We use the get_service method to retreieve a reference to the service the manager is attached to, and attach the player backend to this same service: When a method on DBus object is invoked, the first parameter is the object reference ($self), and the remainder are the parameters provided to the method call. Thus writing a method implementation on a DBUs is really no different to normal object oriented Perl (cf perltoot):

sub register_backend {
my $self = shift;
my $name = shift;
my $module = shift;

eval "use $module";
if ($@) {
die "cannot load backend $module: $@" ;
}

$self->{backends} = $module->new($self->get_service,
"/music/player/backend/$name");
}

Looking at this one might wonder what happens if the die method is triggered. In such a scenario, rather than terminating the service process, the error will be caught and propagated back to the remote caller to deal with.

The player backends provide a method get_track_types which returns an array reference of the music track types they support. We can use this method to provide an API to allow easy retrieval of a backend for a particular track type. This method will return a path with which the backend object can be accessed

sub find_backend {
my $self = shift;
my $extension = shift;

foreach my $name (keys %{$self->{backends}}) {
my $backend = $self->{backends}->{$name};
foreach my $type (@{$backend->get_track_types}) {
if ($type eq $extension) {
return $backend->get_object_path;
}
}
}

die "no backend for type $extension";
}

Lets take a quick moment to consider how this method would be used to play a music track. If youve not already done so, refresh your memory from Net::DBus::Tutorial::UsingObjects. Now, we have an MP3 file which we wish to play, so we search for the path to a backend, then retrieve the object for it, and play the track:

...get the music player service...
# Ask for a path to a player for mp3 files
my $path = $service->find_backend("mp3");
# $path now contains /music/player/backend/mpg123
# and we can get the backend object
my $backend = $service->get_object($path);
# and finally play the track
$backend->play("/vol/music/beck/guero/09-scarecrow.mp3");