[libnet-dbus-perl] 181/335: Significantly increased POD api coverage & fix various pod errors
Intrigeri
intrigeri at moszumanska.debian.org
Sat Mar 21 01:07:51 UTC 2015
This is an automated email from the git hooks/post-receive script.
intrigeri pushed a commit to branch experimental
in repository libnet-dbus-perl.
commit d8a427c1b6765c4da56541b6921fbc86535ee509
Author: Daniel P. Berrange <dan at berrange.com>
Date: Fri Jan 27 15:34:25 2006 +0000
Significantly increased POD api coverage & fix various pod errors
---
CHANGES | 7 +-
Makefile.PL | 21 ++-
README | 2 +
lib/Net/DBus.pm | 58 +------
lib/Net/DBus/Binding/Bus.pm | 58 ++++++-
lib/Net/DBus/Binding/Connection.pm | 54 ++-----
lib/Net/DBus/Binding/Introspector.pm | 12 +-
lib/Net/DBus/Binding/Iterator.pm | 4 +-
lib/Net/DBus/Binding/Message.pm | 4 +-
lib/Net/DBus/Binding/Message/Error.pm | 26 ++-
lib/Net/DBus/Binding/Message/MethodCall.pm | 28 +++-
lib/Net/DBus/Binding/Message/MethodReturn.pm | 26 ++-
lib/Net/DBus/Binding/Message/Signal.pm | 26 ++-
lib/Net/DBus/Binding/Server.pm | 16 +-
lib/Net/DBus/Binding/Value.pm | 24 ++-
lib/Net/DBus/Binding/Watch.pm | 28 +++-
lib/Net/DBus/Callback.pm | 27 +++-
lib/Net/DBus/Dumper.pm | 8 +-
lib/Net/DBus/Exporter.pm | 233 ++++++++++++++-------------
lib/Net/DBus/Object.pm | 170 +++++++++++++------
lib/Net/DBus/Reactor.pm | 48 ++----
lib/Net/DBus/RemoteObject.pm | 23 ++-
lib/Net/DBus/RemoteService.pm | 12 +-
lib/Net/DBus/Service.pm | 12 +-
lib/Net/DBus/Test/MockConnection.pm | 11 +-
lib/Net/DBus/Test/MockObject.pm | 4 +-
t/05-pod.t | 4 +
t/45-exporter.t | 2 +-
28 files changed, 587 insertions(+), 361 deletions(-)
diff --git a/CHANGES b/CHANGES
index 86f9350..1a45525 100644
--- a/CHANGES
+++ b/CHANGES
@@ -12,7 +12,12 @@ Changes since 0.32.3
to unregister object from the bus & thus make it possible to destroy
objects which are no longer required / relevant.
- - More POD documentation fixes
+ - Unregister all child objects if we are unregistered ourselves
+
+ - Fix numerous POD errors identified by Test::Pod and podchecker
+
+ - Greatly expand coverage of API documentation to satisfy both
+ users and the Test::Pod::Coverage tool!
Changes since 0.32.2
diff --git a/Makefile.PL b/Makefile.PL
index 79f5420..c9137ed 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -44,19 +44,26 @@ sub libscan
($path =~ /\~$/ || $path =~ m,/CVS/,) ? undef : $path;
}
-sub postamble {
+sub test {
+ my $self = shift;
+ my $mm_test = $self->SUPER::test(@_);
+
return '
TO_TEST_PM = $(TO_INST_PM:lib/%.pm=blib/test/%.pm)
-XXXtest :: $(TO_TEST_PM)
+test :: test-syntax
-blib/test/%.pm: blib/lib/%.pm
- @echo -n "Checking $@: "
- @perl -I blib/lib -I blib/arch -c $<
+test-syntax: pure_all $(TO_TEST_PM)
+
+blib/test/%.pm: lib/%.pm
+ @echo -n "Checking $<: "
+ #@perl -I blib/lib -c $<
+ @podchecker $<
@mkdir -p `dirname $@`
@touch $@
-';
-}
+
+' . $mm_test;
+ }
__END__
diff --git a/README b/README
index 12b37f6..22da478 100644
--- a/README
+++ b/README
@@ -55,6 +55,8 @@ has minimal external dependancies:
And to run the test suite:
Test::More
+ Test::Pod (optional, but recommended)
+ Test::Pod::Coverage (optional, but recommended)
Although they are not part of the base Perl distribution, most
OS distributor will already provide addon packages containing
diff --git a/lib/Net/DBus.pm b/lib/Net/DBus.pm
index 5d5a2ac..6ed5ef7 100644
--- a/lib/Net/DBus.pm
+++ b/lib/Net/DBus.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: DBus.pm,v 1.23 2006/01/06 16:21:04 dan Exp $
+# $Id: DBus.pm,v 1.24 2006/01/27 15:34:22 dan Exp $
=pod
@@ -30,7 +30,7 @@ DBus - Perl extension for the DBus message system
####### Attaching to the bus ###########
use Net::DBus;
-
+
# Find the most appropriate bus
my $bus = Net::DBus->find;
@@ -45,7 +45,7 @@ DBus - Perl extension for the DBus message system
# 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");
@@ -55,7 +55,7 @@ DBus - Perl extension for the DBus message system
print $dev, "\n";
}
-
+
######### Providing services ##############
# Register a service known as 'org.example.Jukebox'
@@ -117,8 +117,6 @@ use vars qw(@EXPORT_OK %EXPORT_TAGS);
dbus_byte dbus_boolean dbus_string dbus_double
dbus_struct dbus_array dbus_dict)]);
-=pod
-
=item my $bus = Net::DBus->find(%params);
Search for the most appropriate bus to connect to and
@@ -159,8 +157,6 @@ sub find {
}
}
-=pod
-
=item my $bus = Net::DBus->system(%params);
Return a handle for the system message bus. Note that the
@@ -182,8 +178,6 @@ sub system {
return $bus_system
}
-=pod
-
=item my $bus = Net::DBus->session(%params);
Return a handle for the session message bus.
@@ -203,8 +197,6 @@ sub session {
}
-=pod
-
=item my $bus = Net::DBus->test(%params);
Returns a handle for a virtual bus for use in unit tests. This bus does
@@ -221,8 +213,6 @@ sub test {
return $class->_new(Net::DBus::Test::MockConnection->new());
}
-=pod
-
=item my $bus = Net::DBus->new($address, %params);
Return a connection to a specific message bus. The C<$address>
@@ -271,10 +261,7 @@ sub _new {
return $self;
}
-
-=pod
-
-=item my $connection = $bus->connection;
+=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
@@ -289,8 +276,6 @@ sub get_connection {
return $self->{connection};
}
-=pod
-
=item my $service = $bus->get_service($name);
Retrieves a handle for the remote service identified by the
@@ -322,9 +307,6 @@ sub get_service {
return $self->{services}->{$owner};
}
-
-=pod
-
=item my $service = $bus->export_service($name);
Registers a service with the bus, returning a handle to
@@ -339,8 +321,6 @@ sub export_service {
return Net::DBus::Service->new($self, $name);
}
-=pod
-
=item my $object = $bus->get_bus_object;
Retrieves a handle to the bus object, C</org/freedesktop/DBus>,
@@ -358,8 +338,6 @@ sub get_bus_object {
}
-=pod
-
=item my $name = $bus->get_unique_name;
Retrieves the unique name of this client's connection to
@@ -373,8 +351,6 @@ sub get_unique_name {
return $self->get_connection->get_unique_name
}
-=pod
-
=item my $name = $bus->get_service_owner($service);
Retrieves the unique name of the client on the bus owning
@@ -529,8 +505,6 @@ sub _signal_func {
return $handled;
}
-=pod
-
=back
=head1 DATA TYPING METHODS
@@ -556,8 +530,6 @@ sub dbus_int32 {
}
-=pod
-
=item $typed_value = dbus_uint32($value);
Mark a value as being an unsigned, 32-bit integer.
@@ -570,8 +542,6 @@ sub dbus_uint32 {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_int64($value);
Mark a value as being an unsigned, 64-bit integer.
@@ -586,8 +556,6 @@ sub dbus_int64 {
}
-=pod
-
=item $typed_value = dbus_uint64($value);
Mark a value as being an unsigned, 64-bit integer.
@@ -601,8 +569,6 @@ sub dbus_uint64 {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_double($value);
Mark a value as being a double precision IEEE floating point.
@@ -616,8 +582,6 @@ sub dbus_double {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_byte($value);
Mark a value as being an unsigned, byte.
@@ -631,8 +595,6 @@ sub dbus_byte {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_string($value);
Mark a value as being a UTF-8 string. This is not usually required
@@ -647,8 +609,6 @@ sub dbus_string {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_boolean($value);
Mark a value as being an boolean
@@ -662,8 +622,6 @@ sub dbus_boolean {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_array($value);
Mark a value as being an array
@@ -676,8 +634,6 @@ sub dbus_array {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_struct($value);
Mark a value as being a structure
@@ -690,8 +646,6 @@ sub dbus_struct {
$_[0]);
}
-=pod
-
=item $typed_value = dbus_dict($value);
Mark a value as being a dictionary
@@ -712,7 +666,7 @@ sub dbus_dict{
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>,
-L<dbus-monitor(1)>, L<dbus-daemon-1(1)>, L<dbus-send(1)>, L<http://dbus.freedesktop.org>,
+C<dbus-monitor(1)>, C<dbus-daemon-1(1)>, C<dbus-send(1)>, L<http://dbus.freedesktop.org>,
=head1 AUTHOR
diff --git a/lib/Net/DBus/Binding/Bus.pm b/lib/Net/DBus/Binding/Bus.pm
index 6a32d39..660314f 100644
--- a/lib/Net/DBus/Binding/Bus.pm
+++ b/lib/Net/DBus/Binding/Bus.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Bus.pm,v 1.10 2006/01/06 15:29:09 dan Exp $
+# $Id: Bus.pm,v 1.11 2006/01/27 15:34:24 dan Exp $
=pod
@@ -26,6 +26,21 @@ Net::DBus::Binding::Bus - Handle to a well-known message bus instance
=head1 SYNOPSIS
+ use Net::DBus::Binding::Bus;
+
+ # Get a handle to the system bus
+ my $bus = Net::DBus::Binding::Bus->new(type => &Net::DBus::Binding::Bus::SYSTEM);
+
+=head1 DESCRIPTION
+
+This is a specialization of the L<Net::DBus::Binding::Connection>
+module providing convenience constructor for connecting to one of
+the well-known bus types. There is no reason to use this module
+directly, instead get a handle to the bus with the C<session> or
+C<system> methods in L<Net::DBus>.
+
+=head1 METHODS
+
=over 4
=cut
@@ -41,6 +56,16 @@ use Net::DBus;
use base qw(Net::DBus::Binding::Connection);
+=item my $bus = Net::DBus::Binding::Bus->new(type => $type);
+
+=item my $bus = Net::DBus::Binding::Bus->new(address => $addr);
+
+Open a connection to a message bus, either a well known bus type
+specified using the C<type> parameter, or an arbitrary bus specified
+using the C<address> parameter.
+
+=cut
+
sub new {
my $proto = shift;
my $class = ref($proto) || $proto;
@@ -64,6 +89,15 @@ sub new {
}
+=item $bus->request_name($service_name)
+
+Send a request to the bus registering the well known name
+specified in the C<$service_name> parameter. If another client
+already owns the name, registration will be queued up, pending
+the exit of the other client.
+
+=cut
+
sub request_name {
my $self = shift;
my $service_name = shift;
@@ -71,6 +105,14 @@ sub request_name {
$self->{connection}->dbus_bus_request_name($service_name);
}
+=item my $name = $bus->get_unique_name
+
+Returns the unique name by which this processes' connection to
+the bus is known. Unique names are never re-used for the entire
+lifetime of the bus daemon.
+
+=cut
+
sub get_unique_name {
my $self = shift;
@@ -78,6 +120,13 @@ sub get_unique_name {
}
+=item $bus->add_match($rule)
+
+Register a signal match rule with the bus controller, allowing
+matching broadcast signals to routed to this client.
+
+=cut
+
sub add_match {
my $self = shift;
my $rule = shift;
@@ -85,6 +134,13 @@ sub add_match {
$self->{connection}->dbus_bus_add_match($rule);
}
+=item $bus->remove_match($rule)
+
+Unregister a signal match rule with the bus controller, preventing
+further broadcast signals being routed to this client
+
+=cut
+
sub remove_match {
my $self = shift;
my $rule = shift;
diff --git a/lib/Net/DBus/Binding/Connection.pm b/lib/Net/DBus/Binding/Connection.pm
index 46178a2..fc09f8c 100644
--- a/lib/Net/DBus/Binding/Connection.pm
+++ b/lib/Net/DBus/Binding/Connection.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Connection.pm,v 1.7 2006/01/26 19:20:15 dan Exp $
+# $Id: Connection.pm,v 1.8 2006/01/27 15:34:24 dan Exp $
=pod
@@ -79,8 +79,6 @@ use Carp;
use Net::DBus;
use Net::DBus::Binding::Message::MethodReturn;
-=pod
-
=item my $con = Net::DBus::Binding::Connection->new(address => "unix:path=/path/to/socket");
Creates a new connection to the remove server specified by
@@ -105,8 +103,6 @@ sub new {
}
-=pod
-
=item $status = $con->is_connected();
Returns zero if the connection has been disconnected,
@@ -120,8 +116,6 @@ sub is_connected {
return $self->{connection}->dbus_connection_get_is_connected();
}
-=pod
-
=item $status = $con->is_authenticated();
Returns zero if the connection has not yet successfully
@@ -137,8 +131,6 @@ sub is_authenticated {
}
-=pod
-
=item $con->disconnect()
Closes this connection to the remote host. This method
@@ -154,8 +146,6 @@ sub disconnect {
$self->{connection}->dbus_connection_disconnect();
}
-=pod
-
=item $con->flush()
Blocks execution until all data in the outgoing data
@@ -171,8 +161,6 @@ sub flush {
}
-=pod
-
=item $con->send($message)
Queues a message up for sending to the remote host.
@@ -193,8 +181,6 @@ sub send {
return $self->{connection}->_send($msg->{message});
}
-=pod
-
=item my $reply = $con->send_with_reply_and_block($msg, $timeout);
Queues a message up for sending to the remote host
@@ -225,8 +211,6 @@ sub send_with_reply_and_block {
}
-=pod
-
=item $con->dispatch;
Dispatches any pending messages in the incoming queue
@@ -243,8 +227,6 @@ sub dispatch {
}
-=pod
-
=item $message = $con->borrow_message
Temporarily removes the first message from the incoming
@@ -263,8 +245,6 @@ sub borrow_message {
return Net::DBus::Binding::Message->new(message => $msg);
}
-=pod
-
=item $con->return_message($msg)
Replaces a previously borrowed message in the incoming
@@ -281,8 +261,6 @@ sub return_message {
}
-=pod
-
=item $con->steal_message($msg)
Permanently remove a borrowed message from the incoming
@@ -298,8 +276,6 @@ sub steal_message {
$self->{connection}->dbus_connection_steal_borrowed_message($msg->{message});
}
-=pod
-
=item $msg = $con->pop_message();
Permanently removes the first message on the incoming
@@ -317,8 +293,6 @@ sub pop_message {
return Net::DBus::Binding::Message->new(message => $msg);
}
-=pod
-
=item $con->set_watch_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);
Register a set of callbacks for adding, removing & updating
@@ -344,8 +318,6 @@ sub set_watch_callbacks {
$self->{connection}->_set_watch_callbacks();
}
-=pod
-
=item $con->set_timeout_callbacks(\&add_timeout, \&remove_timeout, \&toggle_timeout);
Register a set of callbacks for adding, removing & updating
@@ -371,8 +343,6 @@ sub set_timeout_callbacks {
$self->{connection}->_set_timeout_callbacks();
}
-=pod
-
=item $con->register_object_path($path, \&handler)
Registers a handler for messages whose path matches
@@ -398,8 +368,6 @@ sub register_object_path {
$self->{connection}->_register_object_path($path, $callback);
}
-=pod
-
=item $con->unregister_object_path($path)
Unregisters the handler associated with the object path C<$path>. The
@@ -415,8 +383,6 @@ sub unregister_object_path {
}
-=pod
-
=item $con->register_fallback($path, \&handler)
Registers a handler for messages whose path starts with
@@ -444,8 +410,6 @@ sub register_fallback {
}
-=pod
-
=item $con->set_max_message_size($bytes)
Sets the maximum allowable size of a single incoming
@@ -462,8 +426,6 @@ sub set_max_message_size {
$self->{connection}->dbus_connection_set_max_message_size($size);
}
-=pod
-
=item $bytes = $con->get_max_message_size();
Retrieves the maximum allowable incoming
@@ -478,8 +440,6 @@ sub get_max_message_size {
return $self->{connection}->dbus_connection_get_max_message_size;
}
-=pod
-
=item $con->set_max_received_size($bytes)
Sets the maximum size of the incoming message queue.
@@ -498,8 +458,6 @@ sub set_max_received_size {
$self->{connection}->dbus_connection_set_max_received_size($size);
}
-=pod
-
=item $bytes $con->get_max_received_size()
Retrieves the maximum incoming message queue size.
@@ -514,6 +472,16 @@ sub get_max_received_size {
}
+=item $con->add_filter($coderef);
+
+Adds a filter to the connection which will be invoked whenever a
+message is received. The C<$coderef> should be a reference to a
+subroutine, which returns a true value if the message should be
+filtered out, or a false value if the normal message dispatch
+should be performed.
+
+=cut
+
sub add_filter {
my $self = shift;
my $callback = shift;
diff --git a/lib/Net/DBus/Binding/Introspector.pm b/lib/Net/DBus/Binding/Introspector.pm
index b91d5ea..20262b4 100644
--- a/lib/Net/DBus/Binding/Introspector.pm
+++ b/lib/Net/DBus/Binding/Introspector.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Introspector.pm,v 1.12 2005/12/21 12:01:42 dan Exp $
+# $Id: Introspector.pm,v 1.13 2006/01/27 15:34:24 dan Exp $
=pod
@@ -107,6 +107,16 @@ our %compound_type_map = (
"dict" => &Net::DBus::Binding::Message::TYPE_DICT_ENTRY,
);
+=item my $ins = Net::DBus::Binding::Introspector->new(object_path => $object_path,
+ xml => $xml);
+
+Creates a new introspection data manager for the object registered
+at the path specified for the C<object_path> parameter. The optional
+C<xml> parameter can be used to pre-load the manager with introspection
+metadata from an XML document.
+
+=cut
+
sub new {
my $proto = shift;
diff --git a/lib/Net/DBus/Binding/Iterator.pm b/lib/Net/DBus/Binding/Iterator.pm
index dedac2a..b050639 100644
--- a/lib/Net/DBus/Binding/Iterator.pm
+++ b/lib/Net/DBus/Binding/Iterator.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Iterator.pm,v 1.14 2005/11/21 11:39:51 dan Exp $
+# $Id: Iterator.pm,v 1.15 2006/01/27 15:34:24 dan Exp $
=pod
@@ -86,8 +86,6 @@ BEGIN {
}
}
-=pod
-
=item $res = $iter->has_next()
Determines if there are any more fields in the message
diff --git a/lib/Net/DBus/Binding/Message.pm b/lib/Net/DBus/Binding/Message.pm
index 8cadae1..7e7e7f5 100644
--- a/lib/Net/DBus/Binding/Message.pm
+++ b/lib/Net/DBus/Binding/Message.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Message.pm,v 1.11 2005/11/21 10:54:48 dan Exp $
+# $Id: Message.pm,v 1.12 2006/01/27 15:34:24 dan Exp $
=pod
@@ -158,8 +158,6 @@ sub set_destination {
$self->{message}->dbus_message_set_destination(@_);
}
-=pod
-
=item my $iterator = $msg->iterator;
Retrieves an iterator which can be used for reading or
diff --git a/lib/Net/DBus/Binding/Message/Error.pm b/lib/Net/DBus/Binding/Message/Error.pm
index 63d60ef..3d9ab4b 100644
--- a/lib/Net/DBus/Binding/Message/Error.pm
+++ b/lib/Net/DBus/Binding/Message/Error.pm
@@ -16,7 +16,15 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Error.pm,v 1.4 2005/11/21 10:54:48 dan Exp $
+# $Id: Error.pm,v 1.5 2006/01/27 15:34:24 dan Exp $
+
+=pod
+
+=head1 NAME
+
+Net::DBus::Binding::Message::Error - a message encoding a method call error
+
+=cut
package Net::DBus::Binding::Message::Error;
@@ -57,3 +65,19 @@ sub get_error_name {
}
1;
+
+=pod
+
+=head1 AUTHOR
+
+Daniel P. Berrange.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2005-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus::Binding::Message>
+
+=cut
diff --git a/lib/Net/DBus/Binding/Message/MethodCall.pm b/lib/Net/DBus/Binding/Message/MethodCall.pm
index 9a485c7..02b7975 100644
--- a/lib/Net/DBus/Binding/Message/MethodCall.pm
+++ b/lib/Net/DBus/Binding/Message/MethodCall.pm
@@ -16,7 +16,17 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: MethodCall.pm,v 1.3 2005/10/15 13:31:42 dan Exp $
+# $Id: MethodCall.pm,v 1.4 2006/01/27 15:34:24 dan Exp $
+
+
+=pod
+
+=head1 NAME
+
+Net::DBus::Binding::Message::MethodCall - a message encoding a method call
+
+=cut
+
package Net::DBus::Binding::Message::MethodCall;
@@ -49,3 +59,19 @@ sub new {
}
1;
+
+=pod
+
+=head1 AUTHOR
+
+Daniel P. Berrange.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2005-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus::Binding::Message>
+
+=cut
diff --git a/lib/Net/DBus/Binding/Message/MethodReturn.pm b/lib/Net/DBus/Binding/Message/MethodReturn.pm
index 1c20111..0075d75 100644
--- a/lib/Net/DBus/Binding/Message/MethodReturn.pm
+++ b/lib/Net/DBus/Binding/Message/MethodReturn.pm
@@ -16,7 +16,15 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: MethodReturn.pm,v 1.3 2005/10/15 13:31:42 dan Exp $
+# $Id: MethodReturn.pm,v 1.4 2006/01/27 15:34:24 dan Exp $
+
+=pod
+
+=head1 NAME
+
+Net::DBus::Binding::Message::MethodReturn - a message encoding a method return
+
+=cut
package Net::DBus::Binding::Message::MethodReturn;
@@ -46,3 +54,19 @@ sub new {
}
1;
+
+=pod
+
+=head1 AUTHOR
+
+Daniel P. Berrange.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2005-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus::Binding::Message>
+
+=cut
diff --git a/lib/Net/DBus/Binding/Message/Signal.pm b/lib/Net/DBus/Binding/Message/Signal.pm
index d90cde3..d93e223 100644
--- a/lib/Net/DBus/Binding/Message/Signal.pm
+++ b/lib/Net/DBus/Binding/Message/Signal.pm
@@ -16,7 +16,15 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Signal.pm,v 1.4 2005/10/15 13:31:42 dan Exp $
+# $Id: Signal.pm,v 1.5 2006/01/27 15:34:24 dan Exp $
+
+=pod
+
+=head1 NAME
+
+Net::DBus::Binding::Message::Signal - a message encoding a signal
+
+=cut
package Net::DBus::Binding::Message::Signal;
@@ -49,3 +57,19 @@ sub new {
1;
+
+=pod
+
+=head1 AUTHOR
+
+Daniel P. Berrange.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2005-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus::Binding::Message>
+
+=cut
diff --git a/lib/Net/DBus/Binding/Server.pm b/lib/Net/DBus/Binding/Server.pm
index 5aeb6ae..c0ecd84 100644
--- a/lib/Net/DBus/Binding/Server.pm
+++ b/lib/Net/DBus/Binding/Server.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Server.pm,v 1.4 2005/11/21 10:55:44 dan Exp $
+# $Id: Server.pm,v 1.5 2006/01/27 15:34:24 dan Exp $
=pod
@@ -49,7 +49,7 @@ Managing the server and new connections in an event loop
sub new_connection {
my $connection = shift;
-
+
$reactor->manage($connection);
}
@@ -78,8 +78,6 @@ use Carp;
use Net::DBus;
use Net::DBus::Binding::Connection;
-=pod
-
=item my $server = Net::DBus::Binding::Server->new(address => "unix:path=/path/to/socket");
Creates a new server binding it to the socket specified by the
@@ -113,8 +111,6 @@ sub new {
return $self;
}
-=pod
-
=item $status = $server->is_connected();
Returns zero if the server has been disconnected,
@@ -129,8 +125,6 @@ sub is_connected {
return $self->{server}->dbus_server_get_is_connected();
}
-=pod
-
=item $server->disconnect()
Closes this server to the remote host. This method
@@ -147,8 +141,6 @@ sub disconnect {
}
-=pod
-
=item $server->set_watch_callbacks(\&add_watch, \&remove_watch, \&toggle_watch);
Register a set of callbacks for adding, removing & updating
@@ -175,8 +167,6 @@ sub set_watch_callbacks {
$self->{server}->_set_watch_callbacks();
}
-=pod
-
=item $server->set_timeout_callbacks(\&add_timeout, \&remove_timeout, \&toggle_timeout);
Register a set of callbacks for adding, removing & updating
@@ -202,8 +192,6 @@ sub set_timeout_callbacks {
$self->{server}->_set_timeout_callbacks();
}
-=pod
-
=item $server->set_connection_callback(\&handler)
Registers the handler to use for dealing with
diff --git a/lib/Net/DBus/Binding/Value.pm b/lib/Net/DBus/Binding/Value.pm
index 29d9247..178fb96 100644
--- a/lib/Net/DBus/Binding/Value.pm
+++ b/lib/Net/DBus/Binding/Value.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Value.pm,v 1.6 2005/12/21 12:01:42 dan Exp $
+# $Id: Value.pm,v 1.7 2006/01/27 15:34:24 dan Exp $
=pod
@@ -32,7 +32,6 @@ Net::DBus::Binding::Value - Strongly typed data value
# Call a method with passing an int32
$object->doit(dint32("3"));
-
=head1 DESCRIPTION
This module provides a simple wrapper around a raw Perl value,
@@ -53,6 +52,15 @@ package Net::DBus::Binding::Value;
use strict;
use warnings;
+=item my $value = Net::DBus::Binding::Value->new($type, $value);
+
+Creates a wrapper for the perl value C<$value> marking it as having
+the dbus data type C<$type>. It is not neccessary to call this method
+directly, instead the data typing methods in the L<Net::DBus> object
+should be used.
+
+=cut
+
sub new {
my $class = shift;
my $self = [];
@@ -65,12 +73,24 @@ sub new {
return $self;
}
+=item my $raw = $value->value
+
+Returns the raw perl value wrapped by this object
+
+=cut
sub value {
my $self = shift;
return $self->[1];
}
+=item my $type = $value->type
+
+Returns the dbus data type this value is marked
+as having
+
+=cut
+
sub type {
my $self = shift;
return $self->[0];
diff --git a/lib/Net/DBus/Binding/Watch.pm b/lib/Net/DBus/Binding/Watch.pm
index 791c0cc..387e86e 100644
--- a/lib/Net/DBus/Binding/Watch.pm
+++ b/lib/Net/DBus/Binding/Watch.pm
@@ -16,7 +16,15 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Watch.pm,v 1.2 2005/10/15 13:31:42 dan Exp $
+# $Id: Watch.pm,v 1.3 2006/01/27 15:34:24 dan Exp $
+
+=pod
+
+=head1 NAME
+
+Net::DBus::Binding::Watch - binding to the dbus watch API
+
+=cut
package Net::DBus::Binding::Watch;
@@ -49,4 +57,20 @@ sub AUTOLOAD {
}
1;
-__END__
+
+=pod
+
+=head1 AUTHOR
+
+Daniel P. Berrange.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2004-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus::Binding::Connection>
+
+=cut
+
diff --git a/lib/Net/DBus/Callback.pm b/lib/Net/DBus/Callback.pm
index 946eddb..92801f3 100644
--- a/lib/Net/DBus/Callback.pm
+++ b/lib/Net/DBus/Callback.pm
@@ -16,7 +16,15 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Callback.pm,v 1.5 2005/10/15 13:31:42 dan Exp $
+# $Id: Callback.pm,v 1.6 2006/01/27 15:34:23 dan Exp $
+
+=pod
+
+=head1 NAME
+
+Net::DBus::Callback - a callback for receiving reactor events
+
+=cut
package Net::DBus::Callback;
@@ -57,3 +65,20 @@ sub invoke {
}
1;
+
+=pod
+
+=head1 AUTHOR
+
+Daniel P. Berrange.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2004-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus::Reactor>
+
+=cut
+
diff --git a/lib/Net/DBus/Dumper.pm b/lib/Net/DBus/Dumper.pm
index 6aaca0a..8833b83 100644
--- a/lib/Net/DBus/Dumper.pm
+++ b/lib/Net/DBus/Dumper.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Dumper.pm,v 1.8 2006/01/26 19:18:51 dan Exp $
+# $Id: Dumper.pm,v 1.9 2006/01/27 15:34:23 dan Exp $
=pod
@@ -85,7 +85,6 @@ use vars qw(@EXPORT);
@EXPORT = qw(dbus_dump);
-=pod
=item my @data = dbus_dump($object);
@@ -197,6 +196,8 @@ sub _dbus_dump_bus {
return @data;
}
+1;
+
=pod
=back
@@ -204,7 +205,8 @@ sub _dbus_dump_bus {
=head1 BUGS
It should print out a list of object paths registered against a
-service
+service, but this only currently works for service implemented
+in Perl
=head1 SEE ALSO
diff --git a/lib/Net/DBus/Exporter.pm b/lib/Net/DBus/Exporter.pm
index 43360b4..798f1e2 100644
--- a/lib/Net/DBus/Exporter.pm
+++ b/lib/Net/DBus/Exporter.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Exporter.pm,v 1.9 2005/12/21 12:04:41 dan Exp $
+# $Id: Exporter.pm,v 1.10 2006/01/27 15:34:23 dan Exp $
=pod
@@ -47,7 +47,7 @@ Net::DBus::Exporter - Export object methods and signals to the bus
# 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");
-
+
=head1 DESCRIPTION
The C<Net::DBus::Exporter> module is used to export methods
@@ -220,111 +220,6 @@ is used.
=over 4
-=item dbus_method($name, $params, $returns, [\%annotations]);
-
-=item dbus_method($name, $params, $returns, $interface, [\%annotations]);
-
-Exports a method called C<$name>, having parameters whose types
-are defined by C<$params>, and returning values whose types are
-defined by C<$returns>. If the C<$interface> parameter is
-provided, then the method is associated with that interface, otherwise
-the default interface for the calling package is used. The
-value for the C<$params> parameter should be an array reference
-with each element defining the data type of a parameter to the
-method. Likewise, the C<$returns> parameter should be an array
-reference with each element defining the data type of a return
-value. If it not possible to export a method which accepts a
-variable number of parameters, or returns a variable number of
-values.
-
-=item dbus_signal($name, $params);
-
-=item dbus_signal($name, $params, $interface);
-
-Exports a signal called C<$name>, having parameters whose types
-are defined by C<$params>, and returning values whose types are
-defined by C<$returns>. If the C<$interface> parameter is
-provided, then the signal is associated with that interface, otherwise
-the default interface for the calling package is used. The
-value for the C<$params> parameter should be an array reference
-with each element defining the data type of a parameter to the
-signal. Signals do not have return values. It not possible to
-export a signal which has a variable number of parameters.
-
-=back
-
-=head1 EXAMPLES
-
-=over 4
-
-=item No paramters, no return values
-
-A method which simply prints "Hello World" each time its called
-
- sub Hello {
- my $self = shift;
- print "Hello World\n";
- }
-
- dbus_method("Hello", [], []);
-
-=item One string parameter, returning an boolean value
-
-A method which accepts a process name, issues the killall
-command on it, and returns a boolean value to indicate whether
-it was successful.
-
- sub KillAll {
- my $self = shift;
- my $processname = shift;
- my $ret = system("killall $processname");
- return $ret == 0 ? 1 : 0;
- }
-
- dbus_method("KillAll", ["string"], ["bool"]);
-
-=item One list of strings parameter, returning a dictionary
-
-A method which accepts a list of files names, stats them, and
-returns a dictionary containing the last modification times.
-
- sub LastModified {
- my $self = shift;
- my $files = shift;
-
- my %mods;
- foreach my $file (@{$files}) {
- $mods{$file} = (stat $file)[9];
- }
- return \%mods;
- }
-
- dbus_method("LastModified", ["array", "string"], ["dict", "string", "int32"]);
-
-=item Annotating methods with metdata
-
-A method which is targetted for removal, and also does not
-return any value
-
- sub PlayMP3 {
- my $self = shift;
- my $track = shift;
-
- system "mpg123 $track &";
- }
-
- dbus_method("PlayMP3", ["string"], [], { deprecated => 1, no_return => 1 });
-
-=back
-
-=head1 SEE ALSO
-
-L<Net::DBus::Object>
-
-=head1 AUTHORS
-
-Daniel P, Berrange L<dan at berrange.com>
-
=cut
package Net::DBus::Exporter;
@@ -366,7 +261,7 @@ sub import {
$class->export_to_level(1, "", @EXPORT);
}
-sub dbus_introspector {
+sub _dbus_introspector {
my $object = shift;
my $class = shift;
@@ -436,6 +331,25 @@ sub _dbus_introspector_add {
}
}
+=item dbus_method($name, $params, $returns, [\%annotations]);
+
+=item dbus_method($name, $params, $returns, $interface, [\%annotations]);
+
+Exports a method called C<$name>, having parameters whose types
+are defined by C<$params>, and returning values whose types are
+defined by C<$returns>. If the C<$interface> parameter is
+provided, then the method is associated with that interface, otherwise
+the default interface for the calling package is used. The
+value for the C<$params> parameter should be an array reference
+with each element defining the data type of a parameter to the
+method. Likewise, the C<$returns> parameter should be an array
+reference with each element defining the data type of a return
+value. If it not possible to export a method which accepts a
+variable number of parameters, or returns a variable number of
+values.
+
+=cut
+
sub dbus_method {
my $name = shift;
my $params = [];
@@ -465,6 +379,17 @@ sub dbus_method {
}
+=item dbus_property($name, $type, $access, [\%attributes]);
+
+=item dbus_property($name, $type, $access, $interface, [\%attributes]);
+
+Exports a property called C<$name>, whose data type is C<$type>.
+If the C<$interface> parameter is provided, then the property is
+associated with that interface, otherwise the default interface
+for the calling package is used.
+
+=cut
+
sub dbus_property {
my $name = shift;
my $type = "string";
@@ -494,6 +419,22 @@ sub dbus_property {
}
+=item dbus_signal($name, $params);
+
+=item dbus_signal($name, $params, $interface);
+
+Exports a signal called C<$name>, having parameters whose types
+are defined by C<$params>, and returning values whose types are
+defined by C<$returns>. If the C<$interface> parameter is
+provided, then the signal is associated with that interface, otherwise
+the default interface for the calling package is used. The
+value for the C<$params> parameter should be an array reference
+with each element defining the data type of a parameter to the
+signal. Signals do not have return values. It not possible to
+export a signal which has a variable number of parameters.
+
+=cut
+
sub dbus_signal {
my $name = shift;
my $params = [];
@@ -519,3 +460,79 @@ sub dbus_signal {
}
1;
+
+=back
+
+=head1 EXAMPLES
+
+=over 4
+
+=item No paramters, no return values
+
+A method which simply prints "Hello World" each time its called
+
+ sub Hello {
+ my $self = shift;
+ print "Hello World\n";
+ }
+
+ dbus_method("Hello", [], []);
+
+=item One string parameter, returning an boolean value
+
+A method which accepts a process name, issues the killall
+command on it, and returns a boolean value to indicate whether
+it was successful.
+
+ sub KillAll {
+ my $self = shift;
+ my $processname = shift;
+ my $ret = system("killall $processname");
+ return $ret == 0 ? 1 : 0;
+ }
+
+ dbus_method("KillAll", ["string"], ["bool"]);
+
+=item One list of strings parameter, returning a dictionary
+
+A method which accepts a list of files names, stats them, and
+returns a dictionary containing the last modification times.
+
+ sub LastModified {
+ my $self = shift;
+ my $files = shift;
+
+ my %mods;
+ foreach my $file (@{$files}) {
+ $mods{$file} = (stat $file)[9];
+ }
+ return \%mods;
+ }
+
+ dbus_method("LastModified", ["array", "string"], ["dict", "string", "int32"]);
+
+=item Annotating methods with metdata
+
+A method which is targetted for removal, and also does not
+return any value
+
+ sub PlayMP3 {
+ my $self = shift;
+ my $track = shift;
+
+ system "mpg123 $track &";
+ }
+
+ dbus_method("PlayMP3", ["string"], [], { deprecated => 1, no_return => 1 });
+
+=back
+
+=head1 SEE ALSO
+
+L<Net::DBus::Object>, L<Net::DBus::Binding::Introspector>
+
+=head1 AUTHORS
+
+Daniel P. Berrange <dan at berrange.com>
+
+=cut
diff --git a/lib/Net/DBus/Object.pm b/lib/Net/DBus/Object.pm
index 01b5b23..f25e9f3 100644
--- a/lib/Net/DBus/Object.pm
+++ b/lib/Net/DBus/Object.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Object.pm,v 1.21 2006/01/26 19:20:31 dan Exp $
+# $Id: Object.pm,v 1.22 2006/01/27 15:34:24 dan Exp $
=pod
@@ -63,9 +63,9 @@ Net::DBus::Object - Provide objects to the bus for clients to use
my $class = shift;
my $service = shift;
my $self = $class->SUPER::new($service, "/org/demo/HelloWorld");
-
+
bless $self, $class;
-
+
return $self;
}
@@ -90,7 +90,7 @@ Net::DBus::Object - Provide objects to the bus for clients to use
$self->emit_signal("Greeting", "Goodbye $name");
return "Said goodbye to $name";
}
-
+
=head1 DESCRIPTION
This the base of all objects which are exported to the
@@ -110,49 +110,6 @@ this exported.
=over 4
-=item my $object = Net::DBus::Object->new($service, $path)
-
-This creates a new DBus object with an path of C<$path>
-registered within the service C<$service>. The C<$path>
-parameter should be a string complying with the usual
-DBus requirements for object paths, while the C<$service>
-parameter should be an instance of L<Net::DBus::Service>.
-The latter is typically obtained by calling the C<export_service>
-method on the L<Net::DBus> object.
-
-=item my $service = $self->get_service
-
-Retrieves the L<Net::DBus::Service> object within which this
-object is exported.
-
-=item my $path = $self->get_object_path
-
-Retrieves the path under which this object is exported
-
-=item $self->emit_signal($name, @args);
-
-Emits a signal from the object, with a name of C<$name>. The
-signal and the data types of the arguments C<@args> must have
-been registered with L<Net::DBus::Exporter> by calling the
-C<dbus_signal> method. The signal will be broadcast to all
-clients on the bus.
-
-=item $self->emit_signal_to($name, $client, @args);
-
-Emits a signal from the object, with a name of C<$name>. The
-signal and the data types of the arguments C<@args> must have
-been registered with L<Net::DBus::Exporter> by calling the
-C<dbus_signal> method. The signal will be sent only to the
-client named by the C<$client> parameter.
-
-
-=back
-
-=head1 SEE ALSO
-
-L<Net::DBus>, L<Net::DBus::Service>, L<Net::DBus::RemoteObject>,
-L<Net::DBus::Exporter>.
-
=cut
package Net::DBus::Object;
@@ -181,6 +138,18 @@ dbus_method("Introspect", [], ["string"]);
dbus_method("Get", ["string", "string"], ["variant"], "org.freedesktop.DBus.Properties");
dbus_method("Set", ["string", "string", "variant"], [], "org.freedesktop.DBus.Properties");
+=item my $object = Net::DBus::Object->new($service, $path)
+
+This creates a new DBus object with an path of C<$path>
+registered within the service C<$service>. The C<$path>
+parameter should be a string complying with the usual
+DBus requirements for object paths, while the C<$service>
+parameter should be an instance of L<Net::DBus::Service>.
+The latter is typically obtained by calling the C<export_service>
+method on the L<Net::DBus> object.
+
+=cut
+
sub new {
my $class = shift;
my $self = {};
@@ -215,6 +184,17 @@ sub new {
}
+=item $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.
+
+=cut
+
sub disconnect {
my $self = shift;
@@ -232,6 +212,15 @@ sub disconnect {
$self->{parent} = undef;
}
+=item 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 C<disconnect> method is called.
+
+=cut
sub is_connected {
my $self = shift;
@@ -269,17 +258,41 @@ sub _unregister_child {
delete $self->{children}->{$object->get_object_path};
}
+=item my $service = $self->get_service
+
+Retrieves the L<Net::DBus::Service> object within which this
+object is exported.
+
+=cut
sub get_service {
my $self = shift;
return $self->{service};
}
+
+=item my $path = $self->get_object_path
+
+Retrieves the path under which this object is exported
+
+=cut
+
sub get_object_path {
my $self = shift;
return $self->{object_path};
}
+=item $self->emit_signal_in($name, $interface, $client, @args);
+
+Emits a signal from the object, with a name of C<$name>. If the
+C<$interface> parameter is defined, the signal will be scoped
+within that interface. If the C<$client> parameter is defined,
+the signal will be unicast to that client on the bus. The
+signal and the data types of the arguments C<@args> must have
+been registered with L<Net::DBus::Exporter> by calling the
+C<dbus_signal> method.
+
+=cut
sub emit_signal_in {
my $self = shift;
@@ -313,6 +326,16 @@ sub emit_signal_in {
}
}
+=item $self->emit_signal_to($name, $client, @args);
+
+Emits a signal from the object, with a name of C<$name>. The
+signal and the data types of the arguments C<@args> must have
+been registered with L<Net::DBus::Exporter> by calling the
+C<dbus_signal> method. The signal will be sent only to the
+client named by the C<$client> parameter.
+
+=cut
+
sub emit_signal_to {
my $self = shift;
my $name = shift;
@@ -335,6 +358,16 @@ sub emit_signal_to {
$self->emit_signal_in($name, $interfaces[0], $destination, @args);
}
+=item $self->emit_signal($name, @args);
+
+Emits a signal from the object, with a name of C<$name>. The
+signal and the data types of the arguments C<@args> must have
+been registered with L<Net::DBus::Exporter> by calling the
+C<dbus_signal> method. The signal will be broadcast to all
+clients on the bus.
+
+=cut
+
sub emit_signal {
my $self = shift;
my $name = shift;
@@ -343,6 +376,17 @@ sub emit_signal {
$self->emit_signal_to($name, undef, @args);
}
+=item $object->connect_to_signal_in($name, $interface, $coderef);
+
+Connects a callback to a signal emitted by the object. The C<$name>
+parameter is the name of the signal within the object, and C<$coderef>
+is a reference to an anonymous subroutine. When the signal C<$name>
+is emitted by the remote object, the subroutine C<$coderef> will be
+invoked, and passed the parameters from the signal. The C<$interface>
+parameter is used to specify the explicit interface defining the
+signal to connect to.
+
+=cut
sub connect_to_signal_in {
my $self = shift;
@@ -357,6 +401,16 @@ sub connect_to_signal_in {
$self->{callbacks}->{$interface}->{$name} = $code;
}
+=item $object->connect_to_signal($name, $coderef);
+
+Connects a callback to a signal emitted by the object. The C<$name>
+parameter is the name of the signal within the object, and C<$coderef>
+is a reference to an anonymous subroutine. When the signal C<$name>
+is emitted by the remote object, the subroutine C<$coderef> will be
+invoked, and passed the parameters from the signal.
+
+=cut
+
sub connect_to_signal {
my $self = shift;
my $name = shift;
@@ -548,10 +602,30 @@ sub _introspector {
my $self = shift;
if (!$self->{introspected}) {
- $self->{introspector} = Net::DBus::Exporter::dbus_introspector($self);
+ $self->{introspector} = Net::DBus::Exporter::_dbus_introspector($self);
$self->{introspected} = 1;
}
return $self->{introspector};
}
1;
+
+
+=pod
+
+=back
+
+=head1 AUTHORS
+
+Daniel P. Berrange
+
+=head1 COPYRIGHT
+
+Copyright (C) 2005-2006 Daniel P. Berrange
+
+=head1 SEE ALSO
+
+L<Net::DBus>, L<Net::DBus::Service>, L<Net::DBus::RemoteObject>,
+L<Net::DBus::Exporter>.
+
+=cut
diff --git a/lib/Net/DBus/Reactor.pm b/lib/Net/DBus/Reactor.pm
index a0015e0..cf01156 100644
--- a/lib/Net/DBus/Reactor.pm
+++ b/lib/Net/DBus/Reactor.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Reactor.pm,v 1.8 2005/11/21 10:53:53 dan Exp $
+# $Id: Reactor.pm,v 1.9 2006/01/27 15:34:24 dan Exp $
=pod
@@ -123,12 +123,13 @@ use Net::DBus::Binding::Watch;
use Net::DBus::Callback;
use Time::HiRes qw(gettimeofday);
-=pod
-
=item my $reactor = Net::DBus::Reactor->new();
-Creates a new event loop ready for monitoring file
-handles, or generating timeouts.
+Creates a new event loop ready for monitoring file handles, or
+generating timeouts. Except in very unsual circumstances (examples
+of which I can't think up) it is not neccessary or desriable to
+explicitly create new reactor instances. Instead call the L<main>
+method to get a handle to the singleton instance.
=cut
@@ -153,6 +154,15 @@ sub new {
use vars qw($main_reactor);
+=item $reactor->main
+
+Return a handle to the singleton instance of the reactor. This
+is the recommended way of getting hold of a reactor, since it
+removes the need for modules to pass around handles to their
+privately created reactors.
+
+=cut
+
sub main {
my $class = shift;
$main_reactor = $class->new() unless defined $main_reactor;
@@ -160,8 +170,6 @@ sub main {
}
-=pod
-
=item $reactor->manage($connection);
=item $reactor->manage($server);
@@ -299,8 +307,6 @@ sub _manage_watch_toggle {
}
-=pod
-
=item $reactor->run();
Starts the event loop monitoring any registered
@@ -313,7 +319,7 @@ disabled. The reactor can be explicitly stopped by
calling the C<shutdown> method.
=cut
-
+
sub run {
my $self = shift;
@@ -321,8 +327,6 @@ sub run {
while ($self->{running}) { $self->step };
}
-=pod
-
=item $reactor->shutdown();
Explicitly shutdown the reactor after pending
@@ -335,8 +339,6 @@ sub shutdown {
$self->{running} = 0;
}
-=pod
-
=item $reactor->step();
Perform one iteration of the event loop, going to
@@ -477,8 +479,6 @@ sub _dispatch_hook {
}
-=pod
-
=item $reactor->add_read($fd, $callback[, $status]);
Registers a file handle for monitoring of read
@@ -495,8 +495,6 @@ sub add_read {
$self->_add("read", @_);
}
-=pod
-
=item $reactor->add_write($fd, $callback[, $status]);
Registers a file handle for monitoring of write
@@ -513,7 +511,6 @@ sub add_write {
$self->_add("write", @_);
}
-=pod
=item $reactor->add_exception($fd, $callback[, $status]);
@@ -531,7 +528,6 @@ sub add_exception {
$self->_add("exception", @_);
}
-=pod
=item my $id = $reactor->add_timeout($interval, $callback, $status);
@@ -569,7 +565,6 @@ sub add_timeout {
return $key;
}
-=pod
=item $reactor->remove_timeout($id);
@@ -588,7 +583,6 @@ sub remove_timeout {
$self->{timeouts}->[$key] = undef;
}
-=pod
=item $reactor->toggle_timeout($id, $status[, $interval]);
@@ -610,8 +604,6 @@ sub toggle_timeout {
}
-=pod
-
=item my $id = $reactor->add_hook($callback[, $status]);
Registers a new hook to be fired on each iteration
@@ -645,8 +637,6 @@ sub add_hook {
}
-=pod
-
=item $reactor->remove_hook($id)
Removes the previously registered hook identified
@@ -665,8 +655,6 @@ sub remove_hook {
$self->{hooks}->[$key] = undef;
}
-=pod
-
=item $reactor->toggle_hook($id[, $status])
Updates the status of the previously registered
@@ -698,8 +686,6 @@ sub _add {
};
}
-=pod
-
=item $reactor->remove_read($fd);
=item $reactor->remove_write($fd);
@@ -736,8 +722,6 @@ sub _remove {
delete $self->{fds}->{$type}->{$fd};
}
-=pod
-
=item $reactor->toggle_read($fd, $status);
=item $reactor->toggle_write($fd, $status);
diff --git a/lib/Net/DBus/RemoteObject.pm b/lib/Net/DBus/RemoteObject.pm
index b922970..f2abf24 100644
--- a/lib/Net/DBus/RemoteObject.pm
+++ b/lib/Net/DBus/RemoteObject.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: RemoteObject.pm,v 1.19 2006/01/06 15:30:08 dan Exp $
+# $Id: RemoteObject.pm,v 1.20 2006/01/27 15:34:24 dan Exp $
=pod
@@ -28,7 +28,7 @@ Net::DBus::RemoteObject - Access objects provided on the bus
my $service = $bus->get_service("org.freedesktop.DBus");
my $object = $service->get_object("/org/freedesktop/DBus");
-
+
print "Names on the bus {\n";
foreach my $name (sort $object->ListNames) {
print " ", $name, "\n";
@@ -61,8 +61,6 @@ our $AUTOLOAD;
use Net::DBus::Binding::Message::MethodCall;
use Net::DBus::Binding::Introspector;
-=pod
-
=item my $object = Net::DBus::RemoteObject->new($service, $object_path[, $interface]);
Creates a new handle to a remote object. The C<$service> parameter is an instance
@@ -94,8 +92,6 @@ sub new {
return $self;
}
-=pod
-
=item my $object = $object->as_interface($interface);
Casts the object to a specific interface, returning a new instance of the
@@ -118,8 +114,6 @@ sub as_interface {
$interface);
}
-=pod
-
=item my $service = $object->get_service
Retrieves a handle for the remote service on which this object is
@@ -132,8 +126,6 @@ sub get_service {
return $self->{service};
}
-=pod
-
=item my $path = $object->get_object_path
Retrieves the unique path identifier for this object within the
@@ -146,6 +138,15 @@ sub get_object_path {
return $self->{object_path};
}
+=item my $object = $object->get_child_object($subpath, [$interface])
+
+Retrieves a handle to a child of this object, identified
+by the relative path C<$subpath>. The returned object
+is an instance of C<Net::DBus::RemoteObject>. The optional
+C<$interface> parameter can be used to immediately cast
+the object to a specific type.
+
+=cut
sub get_child_object {
my $self = shift;
@@ -200,8 +201,6 @@ sub _introspector {
}
-=pod
-
=item $object->connect_to_signal($name, $coderef);
Connects a callback to a signal emitted by the object. The C<$name>
diff --git a/lib/Net/DBus/RemoteService.pm b/lib/Net/DBus/RemoteService.pm
index f570dc0..365e1f4 100644
--- a/lib/Net/DBus/RemoteService.pm
+++ b/lib/Net/DBus/RemoteService.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: RemoteService.pm,v 1.8 2005/12/21 12:04:11 dan Exp $
+# $Id: RemoteService.pm,v 1.9 2006/01/27 15:34:24 dan Exp $
=pod
@@ -57,8 +57,6 @@ use Carp;
use Net::DBus::RemoteObject;
-=pod
-
=item my $service = Net::DBus::RemoteService->new($bus, $owner, $service_name);
Creates a new handle for a remote service. The C<$bus> parameter is an
@@ -88,8 +86,6 @@ sub new {
}
-=pod
-
=item my $bus = $service->get_bus;
Retrieves a handle for the bus to which this service is attached.
@@ -104,8 +100,6 @@ sub get_bus {
}
-=pod
-
=item my $service_name = $service->get_service_name
Retrieves the name of the remote service as known to the bus.
@@ -117,8 +111,6 @@ sub get_service_name {
return $self->{service_name};
}
-=pod
-
=item my $owner_name = $service->get_owner_name;
Retrieves the name of the client owning the service at the
@@ -131,8 +123,6 @@ sub get_owner_name {
return $self->{owner_name};
}
-=pod
-
=item my $object = $service->get_object($object_path[, $interface]);
Retrieves a handle to the remote object provided by the service with
diff --git a/lib/Net/DBus/Service.pm b/lib/Net/DBus/Service.pm
index 1d4d16a..6b56dfd 100644
--- a/lib/Net/DBus/Service.pm
+++ b/lib/Net/DBus/Service.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: Service.pm,v 1.11 2006/01/06 15:53:44 dan Exp $
+# $Id: Service.pm,v 1.12 2006/01/27 15:34:24 dan Exp $
=pod
@@ -56,8 +56,6 @@ and export objects to the bus.
package Net::DBus::Service;
-=pod
-
=item my $service = Net::DBus::Service->new($bus, $name);
Create a new service, attaching to the bus provided in
@@ -87,8 +85,6 @@ sub new {
return $self;
}
-=pod
-
=item my $bus = $service->get_bus;
Retrieves the L<Net::DBus> object to which this service is
@@ -101,9 +97,7 @@ sub get_bus {
return $self->{bus};
}
-=pod
-
-=item my $name = $service-.get_service_name
+=item my $name = $service->get_service_name
Retrieves the qualified name by which this service is
known on the bus.
@@ -203,6 +197,8 @@ sub ListObjects {
return \@objs;
}
+1;
+
=pod
=back
diff --git a/lib/Net/DBus/Test/MockConnection.pm b/lib/Net/DBus/Test/MockConnection.pm
index f79e16a..eb09dcf 100644
--- a/lib/Net/DBus/Test/MockConnection.pm
+++ b/lib/Net/DBus/Test/MockConnection.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: MockConnection.pm,v 1.3 2006/01/06 15:53:44 dan Exp $
+# $Id: MockConnection.pm,v 1.4 2006/01/27 15:34:25 dan Exp $
=pod
@@ -66,6 +66,15 @@ use warnings;
use Net::DBus::Binding::Message::MethodReturn;
+=item my $con = Net::DBus::Test::MockConnection->new()
+
+Create a new mock connection object instance. It is not usually
+neccessary to create instances of this object directly, instead
+the C<test> method on the L<Net::DBus> object can be used to
+get a handle to a test bus.
+
+=cut
+
sub new {
my $class = shift;
my $self = {};
diff --git a/lib/Net/DBus/Test/MockObject.pm b/lib/Net/DBus/Test/MockObject.pm
index 11aaf84..ce963fd 100644
--- a/lib/Net/DBus/Test/MockObject.pm
+++ b/lib/Net/DBus/Test/MockObject.pm
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
-# $Id: MockObject.pm,v 1.3 2006/01/26 19:18:51 dan Exp $
+# $Id: MockObject.pm,v 1.4 2006/01/27 15:34:25 dan Exp $
=pod
@@ -85,8 +85,6 @@ use warnings;
use Net::DBus::Binding::Message::MethodReturn;
use Net::DBus::Binding::Message::Error;
-=pod
-
=item my $object = Net::DBus::Test::MockObject->new($service, $path, $interface);
Create a new mock object, attaching to the service defined by the C<$service>
diff --git a/t/05-pod.t b/t/05-pod.t
new file mode 100644
index 0000000..437887a
--- /dev/null
+++ b/t/05-pod.t
@@ -0,0 +1,4 @@
+use Test::More;
+eval "use Test::Pod 1.00";
+plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
+all_pod_files_ok();
diff --git a/t/45-exporter.t b/t/45-exporter.t
index 6c3b8f4..4c6d63a 100644
--- a/t/45-exporter.t
+++ b/t/45-exporter.t
@@ -46,7 +46,7 @@ dbus_method("NoArgsInterfaceAnnotate", [],["int32"], "org.example.OtherObject",
-my $ins = Net::DBus::Exporter::dbus_introspector($obj);
+my $ins = Net::DBus::Exporter::_dbus_introspector($obj);
is($ins->get_object_path, "/org/example/MyObject", "object path");
ok($ins->has_interface("org.example.MyObject"), "interface registration");
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libnet-dbus-perl.git
More information about the Pkg-perl-cvs-commits
mailing list