desktop results from the CPAN

desktop

Net-DBus

view release on metacpan or search on metacpan

# -*- perl -*-
#
# Copyright (C) 2004-2011 Daniel P. Berrange
#
# This program is free software; You can redistribute it and/or modify
# it under the same terms as Perl itself. Either:
#
# a) the GNU General Public License as published by the Free
#   Software Foundation; either version 2, or (at your option) any
#   later version,
#
# or
#
# b) the "Artistic License"
#
# The file "COPYING" distributed along with this file provides full
# details of the terms and conditions of the two licenses.

=pod

=head1 NAME

Net::DBus - Perl extension for the DBus message system

=head1 SYNOPSIS


  ####### Attaching to the bus ###########

  use Net::DBus;

  # Find the most appropriate bus
  my $bus = Net::DBus->find;

  # ... or explicitly go for the session bus
  my $bus = Net::DBus->session;

  # .... or explicitly go for the system bus
  my $bus = Net::DBus->system


  ######## Accessing remote services #########

  # Get a handle to the HAL service
  my $hal = $bus->get_service("org.freedesktop.Hal");

  # Get the device manager
  my $manager = $hal->get_object("/org/freedesktop/Hal/Manager",
				 "org.freedesktop.Hal.Manager");

  # List devices
  foreach my $dev (@{$manager->GetAllDevices}) {
      print $dev, "\n";
  }


  ######### Providing services ##############

  # Register a service known as 'org.example.Jukebox'
  my $service = $bus->export_service("org.example.Jukebox");


=head1 DESCRIPTION

Net::DBus provides a Perl API for the DBus message system.
The DBus Perl interface is currently operating against
the 0.32 development version of DBus, but should work with
later versions too, providing the API changes have not been
too drastic.

Users of this package are either typically, service providers
in which case the L<Net::DBus::Service> and L<Net::DBus::Object>
modules are of most relevance, or are client consumers, in which
case L<Net::DBus::RemoteService> and L<Net::DBus::RemoteObject>
are of most relevance.

=head1 METHODS

=over 4

=cut

package Net::DBus;

use 5.006;
use strict;
use warnings;

BEGIN {
    our $VERSION = '1.2.0';
    require XSLoader;
    XSLoader::load('Net::DBus', $VERSION);
}

use Net::DBus::Binding::Bus;
use Net::DBus::Service;
use Net::DBus::RemoteService;
use Net::DBus::Test::MockConnection;
use Net::DBus::Binding::Value;

use vars qw($bus_system $bus_session);

use Exporter qw(import);

use vars qw(@EXPORT_OK %EXPORT_TAGS);

@EXPORT_OK = qw(dbus_int16 dbus_uint16 dbus_int32 dbus_uint32 dbus_int64 dbus_uint64
		dbus_byte dbus_boolean dbus_string dbus_double
		dbus_object_path dbus_signature dbus_unix_fd

lib/Net/DBus.pm view on Meta::CPAN


=item my $bus = Net::DBus->test(%params);

Returns a handle for a virtual bus for use in unit tests. This bus does
not make any network connections, but rather has an in-memory message
pipeline. Consult L<Net::DBus::Test::MockConnection> for further details
of how to use this special bus.

=cut

# NB. explicitly do *NOT* cache, since unit tests
# should always have pristine state
sub test {
    my $class = shift;
    return $class->_new(Net::DBus::Test::MockConnection->new());
}

=item my $bus = Net::DBus->new($address, %params);

Return a connection to a specific message bus.  The C<$address>
parameter must contain the address of the message bus to connect
to. An example address for a session bus might look like
C<unix:abstract=/tmp/dbus-PBFyyuUiVb,guid=191e0a43c3efc222e0818be556d67500>,
while one for a system bus would look like C<unix:/var/run/dbus/system_bus_socket>.
The optional C<params> hash can contain be used to specify
connection options. The only support option at this time
is C<nomainloop> which prevents the bus from being automatically
attached to the main L<Net::DBus::Reactor> event loop.

=cut

sub new {
    my $class = shift;
    return $class->_new(Net::DBus::Binding::Bus->new(address => shift), @_);
}

sub _new {
    my $class = shift;
    my $self = {};

    $self->{connection} = shift;
    $self->{signals} = [];
    # Map well known names to RemoteService objects
    $self->{services} = {};
    $self->{timeout} = 60 * 1000;

    my %params = @_;

    bless $self, $class;

    unless ($params{nomainloop}) {
	if (exists $INC{'Net/DBus/Reactor.pm'}) {
	    my $reactor = $params{reactor} ? $params{reactor} : Net::DBus::Reactor->main;
	    $reactor->manage($self->get_connection);
	}
	# ... Add support for GLib and POE
    }

    $self->get_connection->add_filter(sub { return $self->_signal_func(@_); });

    $self->{bus} = $self->{services}->{"org.freedesktop.DBus"} =
	Net::DBus::RemoteService->new($self, "org.freedesktop.DBus", "org.freedesktop.DBus");
    $self->get_bus_object()->connect_to_signal('NameOwnerChanged', sub {
	my ($svc, $old, $new) = @_;
	# Slightly evil poking into the private 'owner_name' field here
	if (exists $self->{services}->{$svc}) {
	    $self->{services}->{$svc}->{owner_name} = $new;
	}
    });

    return $self;
}

=item my $connection = $bus->get_connection;

Return a handle to the underlying, low level connection object
associated with this bus. The returned object will be an instance
of the L<Net::DBus::Binding::Bus> class. This method is not intended
for use by (most!) application developers, so if you don't understand
what this is for, then you don't need to be calling it!

=cut

sub get_connection {
    my $self = shift;
    return $self->{connection};
}

=item my $service = $bus->get_service($name);

Retrieves a handle for the remote service identified by the
service name C<$name>. The returned object will be an instance
of the L<Net::DBus::RemoteService> class.

=cut

sub get_service {
    my $self = shift;
    my $name = shift;

    if ($name eq "org.freedesktop.DBus") {
	return $self->{bus};
    }

    if (!exists $self->{services}->{$name}) {
	my $owner = $name;
	if ($owner !~ /^:/) {
	    $owner = $self->get_service_owner($name);
	    if (!defined $owner) {
		$self->get_bus_object->StartServiceByName($name, 0);
		$owner = $self->get_service_owner($name);
	    }
	}
	$self->{services}->{$name} = Net::DBus::RemoteService->new($self, $owner, $name);
    }
    return $self->{services}->{$name};
}

=item my $service = $bus->export_service($name);

Registers a service with the bus, returning a handle to
the service. The returned object is an instance of the
L<Net::DBus::Service> class.

When C<$name> is not specified or is C<undef> then returned
handle to the service is identified only by the unique name
of client's connection to the bus.

=cut

sub export_service {
    my $self = shift;
    my $name = shift;
    return Net::DBus::Service->new($self, $name);
}

=item my $object = $bus->get_bus_object;

Retrieves a handle to the bus object, C</org/freedesktop/DBus>,
provided by the service C<org.freedesktop.DBus>. The returned
object is an instance of L<Net::DBus::RemoteObject>

=cut

sub get_bus_object {
    my $self = shift;

    my $service = $self->get_service("org.freedesktop.DBus");
    return $service->get_object('/org/freedesktop/DBus',
				'org.freedesktop.DBus');
}


=item my $name = $bus->get_unique_name;

Retrieves the unique name of this client's connection to
the bus.

=cut

sub get_unique_name {
    my $self = shift;

    return $self->get_connection->get_unique_name
}

=item my $name = $bus->get_service_owner($service);

Retrieves the unique name of the client on the bus owning
the service named by the C<$service> parameter.

=cut

sub get_service_owner {
    my $self = shift;
    my $service = shift;

    my $bus = $self->get_bus_object;
    my $owner = eval {
	$bus->GetNameOwner($service);
    };
    if ($@) {
	if (UNIVERSAL::isa($@, "Net::DBus::Error") &&
	    $@->{name} eq "org.freedesktop.DBus.Error.NameHasNoOwner") {
	    $owner = undef;
	} else {
	    die $@;
	}
    }
    return $owner;
}

=item my $timeout = $bus->timeout(60 * 1000);

Sets or retrieves the timeout value which will be used for DBus
requests belongs to this bus connection. The timeout should be
specified in milliseconds, with the default value being 60 seconds.

=cut

sub timeout {
    my $self = shift;
    if (@_) {
        $self->{timeout} = shift;
    }
    return $self->{timeout};
}

sub _add_signal_receiver {
    my $self = shift;
    my $receiver = shift;
    my $signal_name = shift;
    my $interface = shift;
    my $service = shift;
    my $path = shift;

    my $rule = $self->_match_rule($signal_name, $interface, $service, $path);
    push @{$self->{signals}}, { cb => $receiver,
				rule => $rule,
				signal_name => $signal_name,
				interface => $interface,
				service => $service,
				path => $path };
    $self->{connection}->add_match($rule);
}

sub _remove_signal_receiver {
    my $self = shift;
    my $receiver = shift;
    my $signal_name = shift;
    my $interface = shift;
    my $service = shift;
    my $path = shift;

    my $rule = $self->_match_rule($signal_name, $interface, $service, $path);
    my @signals;
    foreach (@{$self->{signals}}) {
	if ($_->{cb} eq $receiver &&
	    $_->{rule} eq $rule) {
	    $self->{connection}->remove_match($rule);
	} else {
	    push @signals, $_;
	}
    }

lib/Net/DBus.pm view on Meta::CPAN


sub dbus_array {
    return Net::DBus::Binding::Value->new([&Net::DBus::Binding::Message::TYPE_ARRAY],
					  $_[0]);
}

=item $typed_value = dbus_struct($value);

Mark a value as being a structure

=cut


sub dbus_struct {
    return Net::DBus::Binding::Value->new([&Net::DBus::Binding::Message::TYPE_STRUCT],
					  $_[0]);
}

=item $typed_value = dbus_dict($value);

Mark a value as being a dictionary

=cut

sub dbus_dict {
    return Net::DBus::Binding::Value->new([&Net::DBus::Binding::Message::TYPE_DICT_ENTRY],
					  $_[0]);
}

=item $typed_value = dbus_variant($value);

Mark a value as being a variant

=cut

sub dbus_variant {
    return Net::DBus::Binding::Value->new([&Net::DBus::Binding::Message::TYPE_VARIANT],
					  $_[0]);
}

=item $typed_value = dbus_unix_fd($value);

Mark a value as being a unix file descriptor

=cut

sub dbus_unix_fd {
    return Net::DBus::Binding::Value->new(&Net::DBus::Binding::Message::TYPE_UNIX_FD,
                                          $_[0]);
}

=pod

=back

=head1 SEE ALSO

L<Net::DBus>, L<Net::DBus::RemoteService>, L<Net::DBus::Service>,
L<Net::DBus::RemoteObject>, L<Net::DBus::Object>,
L<Net::DBus::Exporter>, L<Net::DBus::Dumper>, L<Net::DBus::Reactor>,
C<dbus-monitor(1)>, C<dbus-daemon-1(1)>, C<dbus-send(1)>, L<http://dbus.freedesktop.org>,

=head1 AUTHOR

Daniel Berrange <dan@berrange.com>

=head1 COPYRIGHT

Copyright 2004-2011 by Daniel Berrange

=cut

1;

( run in 0.514 second using v1.01-cache-2.11-cpan-39bf76dae61 )