home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / lib / perl5 / Net / DBus / RemoteService.pm < prev    next >
Encoding:
Perl POD Document  |  2006-02-19  |  4.2 KB  |  175 lines
  1. # -*- perl -*-
  2. #
  3. # Copyright (C) 2004-2005 Daniel P. Berrange
  4. #
  5. # This program is free software; you can redistribute it and/or modify
  6. # it under the terms of the GNU General Public License as published by
  7. # the Free Software Foundation; either version 2 of the License, or
  8. # (at your option) any later version.
  9. #
  10. # This program is distributed in the hope that it will be useful,
  11. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13. # GNU General Public License for more details.
  14. #
  15. # You should have received a copy of the GNU General Public License
  16. # along with this program; if not, write to the Free Software
  17. # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18. #
  19. # $Id: RemoteService.pm,v 1.9 2006/01/27 15:34:24 dan Exp $
  20.  
  21. =pod
  22.  
  23. =head1 NAME
  24.  
  25. Net::DBus::RemoteService - Access services provided on the bus
  26.  
  27. =head1 SYNOPSIS
  28.  
  29.   my $bus = Net::DBus->find;
  30.   my $service = $bus->get_service("org.freedesktop.DBus");
  31.  
  32.   my $object = $service->get_object("/org/freedesktop/DBus");
  33.   foreach (@{$object->ListNames}) {
  34.     print "$_\n";
  35.   }
  36.  
  37. =head1 DESCRIPTION
  38.  
  39. This object provides a handle to a remote service on the
  40. bus. From this handle it is possible to access objects
  41. associated with the service. If a service is not running,
  42. an attempt will be made to activate it the first time a
  43. method is called against one of its objects.
  44.  
  45. =head1 METHODS
  46.  
  47. =over 4
  48.  
  49. =cut
  50.  
  51. package Net::DBus::RemoteService;
  52.  
  53. use 5.006;
  54. use strict;
  55. use warnings;
  56. use Carp;
  57.  
  58. use Net::DBus::RemoteObject;
  59.  
  60. =item my $service = Net::DBus::RemoteService->new($bus, $owner, $service_name);
  61.  
  62. Creates a new handle for a remote service. The C<$bus> parameter is an
  63. instance of L<Net::DBus>, C<$owner> is the name of the client providing the
  64. service, while C<$service_name> is the well known name of the  service on 
  65. the bus. Service names consist of two or more tokens, separated
  66. by periods, while the tokens comprise the letters a-z, A-Z, 0-9 and _,
  67. for example C<org.freedesktop.DBus>. There is generally no need to call
  68. this constructor, instead the C<get_service> method on L<Net::DBus> should
  69. be used. This caches handles to remote services, eliminating repeated 
  70. retrieval of introspection data.
  71.  
  72. =cut
  73.  
  74. sub new {
  75.     my $class = shift;
  76.     my $self = {};
  77.  
  78.     $self->{bus} = shift;
  79.     $self->{owner_name} = shift;
  80.     $self->{service_name} = shift;
  81.     $self->{objects} = {};
  82.  
  83.     bless $self, $class;
  84.  
  85.     return $self;
  86. }
  87.  
  88.  
  89. =item my $bus = $service->get_bus;
  90.  
  91. Retrieves a handle for the bus to which this service is attached.
  92. The returned object will be an instance of L<Net::DBus>.
  93.  
  94. =cut
  95.  
  96. sub get_bus {
  97.     my $self = shift;
  98.  
  99.     return $self->{bus};
  100. }
  101.  
  102.  
  103. =item my $service_name = $service->get_service_name
  104.  
  105. Retrieves the name of the remote service as known to the bus.
  106.  
  107. =cut
  108.  
  109. sub get_service_name {
  110.     my $self = shift;
  111.     return $self->{service_name};
  112. }
  113.  
  114. =item my $owner_name = $service->get_owner_name;
  115.  
  116. Retrieves the name of the client owning the service at the
  117. time it was connected to. 
  118.  
  119. =cut
  120.  
  121. sub get_owner_name {
  122.     my $self = shift;
  123.     return $self->{owner_name};
  124. }
  125.  
  126. =item my $object = $service->get_object($object_path[, $interface]);
  127.  
  128. Retrieves a handle to the remote object provided by the service  with
  129. the name of C<$object_path>. If the optional C<$interface> parameter is
  130. provided, the object will immediately be cast to the designated 
  131. interface. NB, it is only neccessary to cast an object to a specific
  132. interface if there are multiple interfaces on the object providing
  133. methods with the same name, or the remote object does support 
  134. introspection. The returned object will be an instance of L<Net::DBus::RemoteObject>.
  135.  
  136. =cut
  137.  
  138. sub get_object {
  139.     my $self = shift;
  140.     my $object_path = shift;
  141.     
  142.     unless (defined $self->{objects}->{$object_path}) {
  143.     $self->{objects}->{$object_path} = Net::DBus::RemoteObject->new($self,
  144.                                     $object_path);
  145.     }
  146.  
  147.     if (@_) {
  148.     my $interface = shift;
  149.     return $self->{objects}->{$object_path}->as_interface($interface);
  150.     } else {
  151.     return $self->{objects}->{$object_path};
  152.     }
  153. }
  154.  
  155. 1;
  156.  
  157.  
  158. =pod
  159.  
  160. =back
  161.  
  162. =head1 AUTHOR
  163.  
  164. Daniel Berrange <dan@berrange.com>
  165.  
  166. =head1 COPYRIGHT
  167.  
  168. Copright (C) 2004-2005, Daniel Berrange. 
  169.  
  170. =head1 SEE ALSO
  171.  
  172. L<Net::DBus::RemoteObject>, L<Net::DBus::Service>, L<Net::DBus>
  173.  
  174. =cut
  175.