[libnet-dbus-perl] 103/335: Added POD documentation. Fix caching of objects so that primary object is cached, not the one cast to an interface

[Intrigeri]

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 5a7e8cff2d7446f35350dc24e66e7cfa66591dd3
Author: Daniel P. Berrange <dan at berrange.com>
Date:   Mon Sep 12 22:17:53 2005 +0000

    Added POD documentation. Fix caching of objects so that primary object is cached, not the one cast to an interface
---
 lib/Net/DBus/RemoteService.pm | 134 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 122 insertions(+), 12 deletions(-)

diff --git a/lib/Net/DBus/RemoteService.pm b/lib/Net/DBus/RemoteService.pm
index 657bb5d..6f942b8 100644
--- a/lib/Net/DBus/RemoteService.pm
+++ b/lib/Net/DBus/RemoteService.pm
@@ -1,3 +1,35 @@
+=pod
+
+=head1 NAME
+
+Net::DBus::RemoteService - access services on the bus
+
+=head1 SYNOPSIS
+
+  my $bus = Net::DBus->find;
+  my $service = $bus->get_service("org.freedesktop.DBus");
+
+  if ($service->is_online) {
+    my $object = $service->get_object("/org/freedesktop/DBus");
+    foreach (@{$object->ListNames}) {
+       print "$_\n";
+    }
+  }
+
+=head1 DESCRIPTION
+
+This object provides a handle to a remote service on the
+bus. From this handle it is possible to access objects
+associated with the service. If a service is not running,
+an attempt will be made to activate it the first time a
+method is called against one of its objects.
+
+=head1 METHODS
+
+=over 4
+
+=cut
+
 package Net::DBus::RemoteService;
 
 use 5.006;
@@ -5,10 +37,22 @@ use strict;
 use warnings;
 use Carp;
 
-our $VERSION = '0.0.1';
-
 use Net::DBus::RemoteObject;
 
+=pod
+
+=item my $service = Net::DBus::RemoteService->new($bus, $service_name);
+
+Creates a new handle for a remote service. The C<$bus> parameter is an
+instance of L<Net::DBus>, while C<$service_name> is the name of the 
+service on the bus. Service names consist of two or more tokens, separated
+by periods, while the tokens comprise the letters a-z, A-Z, 0-9 and _,
+for example C<org.freedesktop.DBus>. There is generally no need to call
+this constructor, instead the C<get_service> method on L<Net::DBus> should
+be used. This caches handles to remote services, eliminating repeated 
+retrieval of introspection data.
+
+=cut
 
 sub new {
     my $class = shift;
@@ -23,6 +67,33 @@ sub new {
     return $self;
 }
 
+
+=pod
+
+=item my $boolean = $service->is_online
+
+Returns a true value if the service is currently attached to the
+the bus. If a false value is returned, then no client on the bus
+is currently provide this service, and the first method call 
+made on a remote object will trigger the startup of the service.
+
+=cut
+
+sub is_online {
+    my $self = shift;
+
+    return $self->get_bus->has_service($self->get_service_name);
+}
+
+=pod
+
+=item my $bus = $service->get_bus;
+
+Retrieves a handle for the bus to which this service is attached.
+The returned object will be an instance of L<Net::DBus>.
+
+=cut
+
 sub get_bus {
     my $self = shift;
 
@@ -30,28 +101,67 @@ sub get_bus {
 }
 
 
+=pod
+
+=item my $service_name = $service->get_service_name
+
+Retrieves the name of the remote service as known to the bus.
+
+=cut
+
 sub get_service_name {
     my $self = shift;
     return $self->{service_name};
 }
 
+=pod
+
+=item my $object = $service->get_object($object_path[, $interface]);
+
+Retrieves a handle to the remote object provided by the service  with
+the name of C<$object_path>. If the optional C<$interface> parameter is
+provided, the object will immediately be cast to the designated 
+interface. NB, it is only neccessary to cast an object to a specific
+interface if there are multiple interfaces on the object providing
+methods with the same name, or the remote object does support 
+introspection. The returned object will be an instance of L<Net::DBus::RemoteObject>.
+
+=cut
+
 sub get_object {
     my $self = shift;
     my $object_path = shift;
     
     unless (defined $self->{objects}->{$object_path}) {
-	if (@_) {
-	    my $interface = shift;
-	    $self->{objects}->{$object_path} = Net::DBus::RemoteObject->new($self,
-									    $object_path,
-									    $interface);
-	} else {
-	    $self->{objects}->{$object_path} = Net::DBus::RemoteObject->new($self,
-									    $object_path);
-	}
+	$self->{objects}->{$object_path} = Net::DBus::RemoteObject->new($self,
+									$object_path);
+    }
+
+    if (@_) {
+	my $interface = shift;
+	return $self->{objects}->{$object_path}->as_interface($interface);
+    } else {
+	return $self->{objects}->{$object_path};
     }
-    return $self->{objects}->{$object_path};
 }
 
 1;
  
+
+=pod
+
+=back
+
+=head1 AUTHOR
+
+Daniel Berrange <dan at berrange.com>
+
+=head1 COPYRIGHT
+
+Copright (C) 2004-2005, Daniel Berrange. 
+
+=head1 SEE ALSO
+
+L<Net::DBus::RemoteObject>, L<Net::DBus::Service>, L<Net::DBus>
+
+=cut

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libnet-dbus-perl.git