NAME¶
Net::DBus::Object - Provide objects to the bus for clients to use
SYNOPSIS¶
# Connecting an object to the bus, under a service
package main;
use Net::DBus;
# Attach to the bus
my $bus = Net::DBus->find;
# Acquire a service 'org.demo.Hello'
my $service = $bus->export_service("org.demo.Hello");
# Export our object within the service
my $object = Demo::HelloWorld->new($service);
....rest of program...
# Define a new package for the object we're going
# to export
package Demo::HelloWorld;
# Specify the main interface provided by our object
use Net::DBus::Exporter qw(org.example.demo.Greeter);
# We're going to be a DBus object
use base qw(Net::DBus::Object);
# Export a 'Greeting' signal taking a stringl string parameter
dbus_signal("Greeting", ["string"]);
# Export 'Hello' as a method accepting a single string
# parameter, and returning a single string value
dbus_method("Hello", ["string"], ["string"]);
sub new {
my $class = shift;
my $service = shift;
my $self = $class->SUPER::new($service, "/org/demo/HelloWorld");
bless $self, $class;
return $self;
}
sub Hello {
my $self = shift;
my $name = shift;
$self->emit_signal("Greeting", "Hello $name");
return "Said hello to $name";
}
# Export 'Goodbye' as a method accepting a single string
# parameter, and returning a single string, but put it
# in the 'org.exaple.demo.Farewell' interface
dbus_method("Goodbye", ["string"], ["string"], "org.example.demo.Farewell");
sub Goodbye {
my $self = shift;
my $name = shift;
$self->emit_signal("Greeting", "Goodbye $name");
return "Said goodbye to $name";
}
DESCRIPTION¶
This the base of all objects which are exported to the message bus. It provides
the core support for type introspection required for objects exported to the
message. When sub-classing this object, methods can be created & tested as
per normal Perl modules. Then just as the Exporter module is used to export
methods within a script, the Net::DBus::Exporter module is used to export
methods (and signals) to the message bus.
All packages inheriting from this, will automatically have the interface
"org.freedesktop.DBus.Introspectable" registered with
Net::DBus::Exporter, and the "Introspect" method within this
exported.
METHODS¶
- my $object = Net::DBus::Object->new($service, $path)
- This creates a new DBus object with an path of $path registered within the
service $service. The $path parameter should be a string complying with
the usual DBus requirements for object paths, while the $service parameter
should be an instance of Net::DBus::Service. The latter is typically
obtained by calling the "export_service" method on the Net::DBus
object.
- my $object = Net::DBus::Object->new($parentobj, $subpath)
- This creates a new DBus child object with an path of $subpath relative to
its parent $parentobj. The $subpath parameter should be a string complying
with the usual DBus requirements for object paths, while the $parentobj
parameter should be an instance of Net::DBus::Object.
- $object->disconnect();
- This method disconnects the object from the bus, such that it will no
longer receive messages sent by other clients. Any child objects will be
recursively disconnected too. After an object has been disconnected, it is
possible for Perl to garbage collect the object instance. It will also
make it possible to connect a newly created object to the same path.
- my $bool = $object->is_connected
- Returns a true value if the object is connected to the bus, and thus
capable of being accessed by remote clients. Returns false if the object
is disconnected & thus ready for garbage collection. All objects start
off in the connected state, and will only transition if the
"disconnect" method is called.
- my $service = $object->get_service
- Retrieves the Net::DBus::Service object within which this object is
exported.
- my $path = $object->get_object_path
- Retrieves the path under which this object is exported
- $object->emit_signal_in($name, $interface, $client, @args);
- Emits a signal from the object, with a name of $name. If the $interface
parameter is defined, the signal will be scoped within that interface. If
the $client parameter is defined, the signal will be unicast to that
client on the bus. The signal and the data types of the arguments @args
must have been registered with Net::DBus::Exporter by calling the
"dbus_signal" method.
- $self->emit_signal_to($name, $client, @args);
- Emits a signal from the object, with a name of $name. The signal and the
data types of the arguments @args must have been registered with
Net::DBus::Exporter by calling the "dbus_signal" method. The
signal will be sent only to the client named by the $client
parameter.
- $self->emit_signal($name, @args);
- Emits a signal from the object, with a name of $name. The signal and the
data types of the arguments @args must have been registered with
Net::DBus::Exporter by calling the "dbus_signal" method. The
signal will be broadcast to all clients on the bus.
- $object->connect_to_signal_in($name, $interface, $coderef);
- Connects a callback to a signal emitted by the object. The $name parameter
is the name of the signal within the object, and $coderef is a reference
to an anonymous subroutine. When the signal $name is emitted by the remote
object, the subroutine $coderef will be invoked, and passed the parameters
from the signal. The $interface parameter is used to specify the explicit
interface defining the signal to connect to.
- $object->connect_to_signal($name, $coderef);
- Connects a callback to a signal emitted by the object. The $name parameter
is the name of the signal within the object, and $coderef is a reference
to an anonymous subroutine. When the signal $name is emitted by the remote
object, the subroutine $coderef will be invoked, and passed the parameters
from the signal.
AUTHOR¶
Daniel P. Berrange
COPYRIGHT¶
Copyright (C) 2005-2011 Daniel P. Berrange
SEE ALSO¶
Net::DBus, Net::DBus::Service, Net::DBus::RemoteObject,
Net::DBus::Exporter.