Net::DBus Modules and Methods

From Alteeve Wiki
Revision as of 01:42, 12 October 2009 by Digimer (talk | contribs) (→‎List of modules in the Net::DBus Perl bindings)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

 AN!Tools :: Net::DBus Binding Tutorial :: Net::DBus Modules and Methods

This will be a complete list of modules used in the general 'Net::DBus' bindings.

Much of the documentation below comes from the POD documentation contained in the various modules themselves. As such, the majority of the credit for the following sections belongs to the 'Net::DBus' author, Daniel P. Berrange.

Errors, however, I claim total ownership of.

List of modules in the Net::DBus Perl bindings

The following list and methods was written agains Net::DBus version 0.33.5.

Net::DBus

This is the core library in the Net::DBus bindings. This module provides the following methods:

Usage: 

use Net::DBus;

In the following methods; 

%params
This is used to prevent the associated bus from being added to the 'Net::DBus::Reactor' event loop. Programs use the 'Net::DBus::Reactor' module to react to messages on the bus. By setting 'nomainloop', the general 'reactor' will not trigger, and thus programs using it will not react to messages on this bus. ... (show how 'nomainloop' would be set. 'my %params=(nomainloop=>1);'?).

Methods

Net::DBus::Annotation

This module provides annotations for switching how the DBus API handles remote calls. Currently it allows switching between 'sync', 'async' and 'no-reply' modes.

Usage; 

use Net::DBus::Annotation qw(:call);

my $object = $service->get_object("/org/example/systemMonitor");
# ...

Where '$service' is a handle to a service gathered from the 'Net::DBus->get_service' method.

Methods

Net::DBus::ASyncReply

This module provides the methodality of handling an asynchronous reply from a remote method. This module is used when the 'Net::DBus::Annotation->dbus_call_async' method is used.

Usage; 

use Net::DBus::Annotation qw(:call);

my $object = $service->get_object("/org/example/systemMonitor");
 
# List processes & get on with other work until
# the list is returned.
my $asyncreply = $object->list_processes(dbus_call_async, "someuser");

while (!$asyncreply->is_ready)
{
	# Do some background work...
}

my $processes = $asyncreply->get_result;

Where '$service' is a handle to a service gathered from the 'Net::DBus->get_service' method.

Madi: Is this right?

Methods

Note on Net::DBus::Binding::* Modules

All of the modules under this namespace are designed for internal use by the various 'Net::DBus*' modules and should not be directly accessed by applications. The author of this DBus binding makes no guarantee that methods herein will be compatible across versions. What documentation exists may quickly become inaccurate and should be used as a guide or learning aide only.

Net::DBus::Binding::Bus

This module provides handles to well know message bus instances.

This module is designed to be used internally by other Net::DBus modules. Please do not directly use this module unless you know what you are doing. Instead, use the 'Net::DBus->system' or 'Net::DBus->session' methods. Given this design, no methods will be documented at this time.

MADI: Ask Daniel if he thinks there is value in documenting the public methods in this module at this time.

Net::DBus::Binding::Connection

This module is used for connecting to a server. Once connected, this module provides methods for sending messages to the server and for listening to the bus for connections and messages from clients.

Usage; 

use Net::DBus::Binding::Connection;

# Connect to a server.
### (connect to a 'session' bus.)
#my $address="unix:abstract=/tmp/dbus-PBFyyuUiVb,guid=191e0a43c3efc222e0818be556d67500";
### (connect to a 'system' bus.)
my $address="unix:path=/path/to/socket";
my $connection=Net::DBus::Binding::Connection->new(address => "$address");

# Send a message on the bus.
my $message="what would a valid message be?";
$connection->send($message);

# Create a subroutine to handle messages.
sub &process_messages
{
        my $connection=shift;
        my $message=shift;
   
        # Do work here.
}
$connection->register_message_handler("/some/object/path", \&process_messages);

# Add this connection to an event loop.
my $reactor = Net::DBus::Binding::Reactor->new();
$reactor->manage($connection);
$reactor->run();
Can this in fact be used to connect to a session bus? The POD only references the UNIX socket... Assumptions are dangerous!
MADI: Look into the 'dbus_connection_XXX' methods in the C API for more details on the following matching methods.

Methods

Net::DBus::Binding::Introspector

This module is responsible for managing introspection data and for answering questions about that data.

This module is designed to be used internally by other Net::DBus modules. Please do not directly use this module unless you know what you are doing. Instead, use the higher-level API methods provided by the 'Net::DBus::Exporter' module. Given this design, no methods will be documented at this time.

MADI: Ask Daniel if he thinks there is value in documenting the public methods in this module at this time.

Net::DBus::Binding::Iterator

This module reads and writes message parameters.

It handles the dirty work of putting messages together for sending and parsing incoming messages from the message bus. Specifically, it provides a perl API to the 'dbus_message_iter_*' methods in DBus' C API.

NOTE!

The 'array' and 'dictionary' (hash) types are not yet supported. Also, there are bugs in the 'quad' method (specifically, it always returns '-1'). MADI: Ask Daniel about this.

Usage: MADI: Is 'use Net::DBus' enough to import this module or do I need 'use Net::DBus::Binding::Iterator'? 

use Net::DBus;
use Net::DBus::Binding::Iterator;

# Creating a new message
my $message=new Net::DBus::Binding::Message::Signal;
my $iterator=$message->iterator;

$iterator->append_boolean(1);
$iterator->append_byte(123);

# Reading from a mesage
my $msg=""; # Get it from somewhere...
my $iterator=$msg->iterator();

my $i=0;
while ($iterator->has_next())
{
        $iterator->next();
        $i++;
        if ($i == 1)
        {
                my $value=$iterator->get_boolean();
        }
        elsif ($i == 2)
        {
                my $value=$iterator->get_byte();
        }
        # MADI: What does '$i' map to? Find it and include it in this section.
}

Methods

Net::DBus::Binding::Message

This module provides the base classes for sending and receiving message. This module should not be used directly. You should always use one of the four sub-types provided by the modules;

Usage: MADI: Is 'use Net::DBus' enough to import this module or do I need 'use Net::DBus::Binding::Iterator'? 

use Net::DBus;
use Net::DBus::Binding::Message;

my $bus=Net::DBus->find();
my $connection=$bus->get_connection;

# Sending a message
my $message=new Net::DBus::Binding::Message::Signal;
my $iterator=$message->iterator;

$iterator->append_byte(132);
$iterator->append_int32(14241);

$connection->send($msg);

# Receiving a message
#...

# Receiving an error
#...

The methods in this class are not currently documented as they are designed for internal use only.

Net::DBus::Binding::Message::Error

This module is used to create bus error messages.

Usage: 

use Net::DBus::Binding::Message::Error;

my $bus=Net::DBus->find();
my $connection=$bus->get_connection;

# Create an error message.
my $error=Net::DBus::Binding::Message::Error->new(
        replyto     => $method_call,
        name        => "org.example.myobject.FooException",
        description => "Unable to do Foo when updating bar");

# And send it out.
$connection->send($error);

Net::DBus::Binding::Message::MethodCall

This module is used to create a dbus messages containing a (remote) method call.

Usage: 

use Net::DBus::Binding::Message::MethodCall;

my $bus=Net::DBus->find();
my $connection=$bus->get_connection;

# Create the method call message.
my $service="";
my $object="";
my $interface="";
my $name="";
my $call=Net::DBus::Binding::Message::MethodCall->new(
        service_name => $service,
        object_path  => $object,
        interface    => $interface,
        method_name  => $name);

# And send it out.
$connection->send($call);

Net::DBus::Binding::Message::MethodReturn

This module is used to create a dbus method return messages.

Usage: 

use Net::DBus::Binding::Message::MethodReturn;

my $bus=Net::DBus->find();
my $connection=$bus->get_connection;

# Create the method return message.
my $method_call="";
my $return=Net::DBus::Binding::Message::MethodReturn->new(call => $method_call);

# And send it out.
$connection->send($return);

Net::DBus::Binding::Message::Signal

This module is used to create a dbus signal messages.

Usage: 

use Net::DBus::Binding::Message::Signal;

my $bus=Net::DBus->find();
my $connection=$bus->get_connection;

# Create the signal message.
my $signal=Net::DBus::Binding::Message::Signal->new(
        object_path => "/org/example/myobject",
        interface   => "org.example.myobject",
        signal_name => "foo_changed");

# And send it out.
$connection->send($signal);

Net::DBus::Binding::PendingCall

This modules handles asynchronous method calls. It provides a means to be notified when a pending call is returned.

Usage: MADI: Do I need to call this module directly? 

use Net::DBus;
use Net::DBus::Binding::PendingCall;

my $call="";
my $reply="";
my $call = Net::DBus::Binding::PendingCall->new(
        method_call  => $call,
        pending_call => $reply);

# Wait for the call to be returned.
$call->block;

# And get the reply message.
my $message=$call->get_reply;

Methods

Net::DBus::Binding::Server

Usage: 

use Net::DBus::Binding::Server;

my $server = Net::DBus::Binding::Server->new(address => "unix:path=/path/to/socket");

$server->connection_callback(\&new_connection);

sub new_connection
{
        my $connection = shift;

        # work with new connection...
}

# Managing the server and new connections in an event loop
my $reactor = Net::DBus::Binding::Reactor->new();

$reactor->manage($server);
$reactor->run();

sub new_connection
{
        my $connection = shift;

        $reactor->manage($connection);
}

This module provides methods for setting up a server that clients can connect to via a UNIX socket file.

Methods

Net::DBus::Binding::Value

Usage: 

# Import the convenience functions
use Net::DBus qw(:typing);

# Takes a 16-bit perl value and marks it as a DBus 'INT16' type. Don't actually
# do this though! Use '$value=Net::DBus->dbus_int16($raw_value);' in real life.
my $raw_value=12;
my $value=Net::DBus::Binding::Value->new(
        &Net::DBus::Binding::Message::TYPE_INT16,
        $raw_value);

This provides a method for marking a perl '$value' as being a certain DBus '$type'.

This is not meant to be directly used! Use the typing functions provided by 'Net::DBus' if needed. This is used internally by DBus for servers that do not offer Introspect data and require strong typing.

Net::DBus::Binding::Watch

Usage: 

# No direct usage, simply AUTOLOADs contansts.

This provides the binding to the DBus watch API. It provides no methods.

Net::DBus::Callback

Usage: 

use Net::DBus::Callback;

# Assume we have a 'terminal' object and its got a method
# to be invoked every time there is input on its terminal.
#
# To create a callback to invoke this method one might use
my $cb = Net::DBus::Callback->new(
        object => $terminal,
        method => "handle_stdio");

# Whatever is monitoring the stdio channel, would then
# invoke the callback, perhaps passing in a parameter with
# some 'interesting' data, such as number of bytes available
$cb->invoke($nbytes)

# ... which results in a call to $terminal->handle_stdio($nbytes)

This provides a container for storing details about a callback to be called at a later time. It is used when registering to receive events via the 'Net::DBus::Reactor' class.

Methods

Net::DBus::Dumper

Usage: 

use Net::DBus::Dumper;
use Net::DBus;

# Dump out info about the bus
my $bus = Net::DBus->find;
print dbus_dump($bus);

# Dump out info about a service
my $service = $bus->get_service("org.freedesktop.DBus");
print dbus_dump($service);

# Dump out info about an object
my $object = $service->get_object("/org/freedesktop/DBus");
print dbus_dump($object);

This module provides debugging methods aimed to help by "stringifing" the various 'Net::DBus:*' objects.

Methods

Net::DBus::Error

Usage: 

package Music::Player::UnknownFormat;

use base qw(Net::DBus::Error);

# Define an error type for unknown track encoding type
# for a music player service
sub new
{
        my $proto = shift;
        my $class = ref($proto) || $proto;
        my $self = $class->SUPER::new(
                name => "org.example.music.UnknownFormat",
                message => "Unknown track encoding format");
}

--- Next package --- 

package Music::Player::Engine;

# ...snip...

# Play either mp3 or ogg music tracks, otherwise
# thrown an error
sub play
{
        my $self = shift;
        my $url = shift;

        if ($url =~ /\.(mp3|ogg)$/)
        {
                # play the track...
        }
        else
        {
                die Music::Player::UnknownFormat->new();
        }
}

This module exports (publishes) methods and signals in an object for use on the message bus.

Note:

Perl is not a strongly typed language like C making it difficult or impossible to determine strict typing information for arguments accepted or returned by methods or signals. To deal with this, when sub-classing (??) 'Net::DBus::Object', this module will provide the specific type information.

An optional, default interface can be specified for newly exported methods to be used when a specific interface is not passed. This saves repeating the interface name when exporting many methods under the same interface.

Please see the 'list of DBus data types' for a complete list of valid DBus message types and their usage.

Net::DBus::Exporter

Usage: 

# Define a new package for the object we're going to export.
package Demo::HelloWorld;

# Specify the main/default 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.
signal("Greeting", ["string"]);

# Export 'Hello' as a method accepting a single string parameter, and returning
# a single string value.
method("Hello", ["string"], ["string"]);

# 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.
method("Goodbye", ["string"], ["string"], "org.example.demo.Farewell");

This module exports (publishes) methods and signals in an object for use on the message bus.

Note:

Perl is not a strongly typed language like C making it difficult to impossible to determine strict typing information for arguments accepted or returned by methods or signals. To deal with this, when sub-classing (??) 'Net::DBus::Object', this module will provide the specific type information.

An optional, default interface can be specified for newly exported methods to be used when a specific interface is not passed. This saves repeating the interface name when exporting many methods under the same interface.

Please see the 'list of DBus data types' for a complete list of valid DBus message types and their usage.

Methods

Net::DBus::Object

Usage: 

# 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";
}

This is the foundation of all exported objects on a message bus.

In a way similar to how the 'Exporter' module exports functions in perl, 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->Introspect' method.

Methods

Net::DBus::Reactor

Usage: 

use Net::DBus::Reactor;

# Create the main event loop.
my $reactor = Net::DBus::Reactor->main();

# Start the event loop now.
$reactor->run();

### MADI: Where would '$filehandle' come from? IO::Handle->new(); or new Filehandle?
# Now register some handlers to the event loop.
$reactor->add_read($filehandle,
        Net::DBus::Callback->new(method => sub {
                my $filehandle = shift;
                # Read some data...
        }, args => [$filehandle]);

$reactor->add_write($filehandle,
        Net::DBus::Callback->new(method => sub {
                my $filehandle = shift;
                # Write some data...
        }, args => [$filehandle]);

# Temporarily (dis|en)able a handle
$reactor->toggle_read($filehandle, 0);       # Disabled
$reactor->toggle_read($filehandle, 1);       # Enabled

# Permanently remove a handle
$reactor->remove_read($filehandle);

# Manage a regular timeout every 100 milliseconds
my $timer=$reactor->add_timeout(100,
        Net::DBus::Callback->new(
                method => sub {
                        # Process the alarm...
                }));

# Temporarily (dis|en)able a timer
$reactor->toggle_timeout($timer, 0); # Disabled
$reactor->toggle_timeout($timer, 1); # Enabled

# Permanently remove a timer
$reactor->remove_timeout($timer);

# Add a post-dispatch hook
my $hook=$reactor->add_hook(Net::DBus::Callback->new(
        method => sub {
                # Do some work...
        }));

# Remove a hook
$reactor->remove_hook($hook);

This uses perl's underlying 'select' system call to create an event loop. This event loop allows for reacting to various filehandle's I/O and timeout events in a single process.

Methods

Net::DBus::RemoteObject

Usage: 

use Net::DBus;

# Connect to the bus.
my $bus=Net::DBus->find;

# Connect to the service on the bus.
my $service=$bus->get_service("org.freedesktop.DBus");

# Connect to the object in the service.
my $object=$service->get_object("/org/freedesktop/DBus");

print "Names on the bus {\n";
foreach my $name (sort $object->ListNames)
{
	print "  ", $name, "\n";
}
print "}\n";

This module provides the API for connecting to remote objects published on the message bus by a given service.

Methods

Net::DBus::RemoteService

Usage: 

use Net::DBus;

my $bus = Net::DBus->find;
my $service = $bus->get_service("org.freedesktop.DBus");

my $object = $service->get_object("/org/freedesktop/DBus");
foreach (@{$object->ListNames})
{
        print "$_\n";
}

This module provides for connecting to an existing service on a message bus, thus allowing access to the objects published on that bus.

Methods

Net::DBus::Service

Usage: 

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);

# The rest of program...

This modules allows for creating a service on a message bus which, in turn, objects can be created and exported under.

Methods

 

Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche! Enterprise Support:
Alteeve Support 		Community Support
© Alteeve's Niche! Inc. 1997-2024   Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.
Retrieved from ‘https://alteeve.com/w/index.php?title=Net::DBus_Modules_and_Methods&oldid=431’