Digimer: Created page with '{{dbtut_header}} This will be a complete list of modules used in the general 'Net::DBus' bindings. Much of the documentation below comes from the [[PO…'

2009-10-12T01:38:42Z

Created page with '{{dbtut_header}} This will be a complete list of modules used in the general 'Net::DBus' bindings. Much of the documentation below comes from the [[PO…'

Páàjì titun

{{dbtut_header}}

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:
<source lang="perl">use Net::DBus;</source>

In the following methods;
<source lang="perl">%params</source>
: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 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;
<source lang="perl">
use Net::DBus::Annotation qw(:call);

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

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

=== Methods ===

* [[Net::DBus::Annotation 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;
<source lang="perl">
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;
</source>

Where '$service' is a handle to a service gathered from the 'Net::DBus->get_service' method.
:Madi: Is this right?

=== Methods ===

* [[Net::DBus::ASyncReply 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;
<source lang="perl">
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();
</source>

: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::Connection 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'?
<source lang="perl">
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.
}
</source>

=== Methods ===

* [[Net::DBus::Binding::Iterator 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;
* [[Net::DBus_Modules_and_Methods#Net::DBus::Binding::Message::Error|Net::DBus::Binding::Message::Error]]
* [[Net::DBus_Modules_and_Methods#Net::DBus::Binding::Message::MethodCall|Net::DBus::Binding::Message::MethodCall]]
* [[Net::DBus_Modules_and_Methods#Net::DBus::Binding::Message::MethodReturn|Net::DBus::Binding::Message::MethodReturn]]
* [[Net::DBus_Modules_and_Methods#Net::DBus::Binding::Message::Signal|Net::DBus::Binding::Message::Signal]]

Usage:
MADI: Is 'use Net::DBus' enough to import this module or do I need 'use Net::DBus::Binding::Iterator'?
<source lang="perl">
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
#...
</source>

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:
<source lang="perl">
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);
</source>

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

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

Usage:
<source lang="perl">
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);
</source>

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

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

Usage:
<source lang="perl">
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);
</source>

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

This module is used to create a dbus signal messages.

Usage:
<source lang="perl">
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);
</source>

== 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?
<source lang="perl">
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;
</source>

=== Methods ===

* [[Net::DBus::Binding::PendingCall Methods]]

== Net::DBus::Binding::Server ==

Usage:
<source lang="perl">
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);
}
</source>

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

=== Methods ===

* [[Net::DBus::Binding::Server Methods]]

== Net::DBus::Binding::Value ==

Usage:
<source lang="perl">
# 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);
</source>

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:
<source lang="perl">
# No direct usage, simply AUTOLOADs contansts.
</source>

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

== Net::DBus::Callback ==

Usage:
<source lang="perl">
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)
</source>

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::Callback Methods]]

== Net::DBus::Dumper ==

Usage:
<source lang="perl">
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);
</source>

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

=== Methods ===

* [[Net::DBus::Dumper Methods]]

== Net::DBus::Error ==

Usage:
<source lang="perl">
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");
}
</source>
--- Next package ---
<source lang="perl">
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();
}
}
</source>

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 [[Net::DBus_Binding_Tutorial#Interface|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:
<source lang="perl">
# 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");
</source>

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 [[Net::Binding_Tutorial#Interface|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::Exporter Methods]]

== Net::DBus::Object ==

Usage:
<source lang="perl">
# 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);
</source>

Rest of program...

<source lang="perl">
# 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";
}
</source>

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_Modules_and_Methods#Net::DBus::Exporter|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::Object Methods]]

== Net::DBus::Reactor ==

Usage:
<source lang="perl">
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);
</source>

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::Reactor Methods]]

== Net::DBus::RemoteObject ==

Usage:
<source lang="perl">
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";
</source>

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

=== Methods ===

* [[Net::DBus::RemoteObject Methods]]

== Net::DBus::RemoteService ==

Usage:
<source lang="perl">
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";
}
</source>

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::RemoteService Methods]]

== Net::DBus::Service ==

Usage:
<source lang="perl">
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...
</source>

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

=== Methods ===

* [[Net::DBus::Service Methods]]

{{footer}}

Net::DBus Modules and Methods - Revision history

Digimer: /* List of modules in the Net::DBus Perl bindings */

Digimer: Created page with '{{dbtut_header}} This will be a complete list of modules used in the general 'Net::DBus' bindings. Much of the documentation below comes from the [[PO…'

← Older revision		Revision as of 01:42, 12 October 2009
Line 9:		Line 9:
	= List of modules in the Net::DBus Perl bindings =		= List of modules in the Net::DBus Perl bindings =

	The following list and methods was written agains Net::DBus version 0.33.5.		The following list and methods was written agains <span class="code">Net::DBus</span> version <span class="code">0.33.5</span>.

	== Net::DBus ==		== Net::DBus ==