net::dbus::glib(3pm) [debian man page]

Net::DBus::GLib(3pm)					User Contributed Perl Documentation				      Net::DBus::GLib(3pm)

NAME

       Net::DBus::GLib - Perl extension for the DBus GLib bindings

SYNOPSIS

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

	 use Net::DBus::GLib;

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

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

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

DESCRIPTION

       Net::DBus::GLib provides an extension to the Net::DBus module allowing integration with the GLib mainloop. To integrate with the main loop,
       simply get a connection to the bus via the methods in Net::DBus::GLib rather than the usual Net::DBus module.  That's it - every other API
       remains the same.

EXAMPLE

       As an example service using the GLib main loop, assuming that SomeObject inherits from Net::DBus::Service

	 my $bus = Net::DBus::GLib->session();
	 my $service = $bus->export_service("org.designfu.SampleService");
	 my $object = SomeObject->new($service);

	 Glib::MainLoop->new()->run();

       And as an example client

	 my $bus = Net::DBus::GLib->session();

	 my $service = $bus->get_service("org.designfu.SampleService");
	 my $object = $service->get_object("/SomeObject");

	 my $list = $object->HelloWorld("Hello from example-client.pl!");

METHODS

       my $bus = Net::DBus::GLib->find(%params);
	   Search for the most appropriate bus to connect to and return a connection to it. For details of the heuristics used, consult the method
	   of the same name in "Net::DBus".  The %params hash may contain an additional entry with a name of "context". This can be a reference to
	   an instance of the "Glib::MainContext" object; if omitted, the default GLib context will be used.

       my $bus = Net::DBus::GLib->system(%params);
	   Return a handle for the system message bus. For further details on this method, consult to the method of the same name in Net::DBus.
	   The %params hash may contain an additional entry with a name of "context". This can be a reference to an instance of the
	   "Glib::MainContext" object; if omitted, the default GLib context will be used.

       my $bus = Net::DBus::GLib->session(%params);
	   Return a handle for the session message bus. For further details on this method, consult to the method of the same name in Net::DBus.
	   The %params hash may contain an additional entry with a name of "context". This can be a reference to an instance of the
	   "Glib::MainContext" object; if omitted, the default GLib context will be used.

SEE ALSO

       Net::DBus, Glib, Glib::MainLoop "http://dbus.freedesktop.org", "http://gtk.org"

AUTHOR

       Daniel Berrange <dan@berrange.com>

COPYRIGHT

       Copyright 2006-2008 by Daniel Berrange

perl v5.14.2							    2008-01-08						      Net::DBus::GLib(3pm)

Net::DBus::Object(3pm)					User Contributed Perl Documentation				    Net::DBus::Object(3pm)

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.

perl v5.14.2							    2011-06-30						    Net::DBus::Object(3pm)