home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / lib / perl5 / Net / DBus / ASyncReply.pm < prev    next >
Encoding:
Perl POD Document  |  2006-06-03  |  3.8 KB  |  169 lines
  1. # -*- perl -*-
  2. #
  3. # Copyright (C) 2006 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: RemoteObject.pm,v 1.20 2006/01/27 15:34:24 dan Exp $
  20.  
  21. =pod
  22.  
  23. =head1 NAME
  24.  
  25. Net::DBus::ASyncReply - asynchronous method reply handler
  26.  
  27. =head1 SYNOPSIS
  28.  
  29.   use Net::DBus::Annotation qw(:call);
  30.  
  31.   my $object = $service->get_object("/org/example/systemMonitor");
  32.  
  33.   # List processes & get on with other work until
  34.   # the list is returned.
  35.   my $asyncreply = $object->list_processes(dbus_call_async, "someuser");
  36.  
  37.   while (!$asyncreply->is_ready) {
  38.     ... do some background work..
  39.   }
  40.  
  41.   my $processes = $asyncreply->get_result;
  42.  
  43.  
  44. =head1 DESCRIPTION
  45.  
  46. This object provides a handler for receiving asynchronous
  47. method replies. An asynchronous reply object is generated
  48. when making remote method call with the C<dbus_call_async>
  49. annotation set.
  50.  
  51. =head1 METHODS
  52.  
  53. =over 4
  54.  
  55. =cut
  56.  
  57. package Net::DBus::ASyncReply;
  58.  
  59. use strict;
  60. use warnings;
  61.  
  62.  
  63. sub _new {
  64.     my $proto = shift;
  65.     my $class = ref($proto) || $proto;
  66.     my $self = {};
  67.     my %params = @_;
  68.  
  69.     $self->{pending_call} = $params{pending_call} ? $params{pending_call} : die "pending_call parameter is required";
  70.     $self->{introspector} = $params{introspector} ? $params{introspector} : undef;
  71.     $self->{method_name} = $params{method_name} ? $params{method_name} : ($self->{introspector} ? die "method_name is parameter required for introspection" : undef);
  72.  
  73.     bless $self, $class;
  74.  
  75.     return $self;
  76. }
  77.  
  78.  
  79. =item $asyncreply->discard_result;
  80.  
  81. Indicates that the caller is no longer interested in
  82. recieving the reply & that it should be discarded. After
  83. calling this method, this object should not be used again.
  84.  
  85. =cut
  86.  
  87. sub discard_result {
  88.     my $self = shift;
  89.  
  90.     $self->{pending_call}->cancel;
  91. }
  92.  
  93.  
  94. =item $asyncreply->wait_for_result;
  95.  
  96. Blocks the caller waiting for completion of the of the
  97. asynchronous reply. Upon returning from this method, the
  98. result can be obtained with the C<get_result> method.
  99.  
  100. =cut
  101.  
  102. sub wait_for_result {
  103.     my $self = shift;
  104.  
  105.     $self->{pending_call}->block;
  106. }
  107.  
  108. =item my $boolean = $asyncreply->is_ready;
  109.  
  110. Returns a true value if the asynchronous reply is now
  111. complete (or a timeout has occurred). When this method
  112. returns true, the result can be obtained with the C<get_result>
  113. method.
  114.  
  115. =cut
  116.  
  117. sub is_ready {
  118.     my $self = shift;
  119.  
  120.     return $self->{pending_call}->get_completed;
  121. }
  122.  
  123.  
  124. =item my @data = $asyncreply->get_result;
  125.  
  126. Retrieves the data associated with the asynchronous reply.
  127. If a timeout occurred, then this method will throw an
  128. exception. This method can only be called once the reply
  129. is complete, as indicated by the C<is_ready> method
  130. returning a true value. After calling this method, this
  131. object should no longer be used.
  132.  
  133. =cut
  134.  
  135. sub get_result {
  136.     my $self = shift;
  137.  
  138.     my $reply = $self->{pending_call}->get_reply;
  139.  
  140.     my @reply;
  141.     if ($self->{introspector}) {
  142.     @reply = $self->{introspector}->decode($reply, "methods", $self->{method_name}, "returns");
  143.     } else {
  144.     @reply = $reply->get_args_list;
  145.     }
  146.  
  147.     return wantarray ? @reply : $reply[0];
  148. }
  149.  
  150. 1;
  151.  
  152. =pod
  153.  
  154. =back
  155.  
  156. =head1 AUTHOR
  157.  
  158. Daniel Berrange <dan@berrange.com>
  159.  
  160. =head1 COPYRIGHT
  161.  
  162. Copright (C) 2006, Daniel Berrange.
  163.  
  164. =head1 SEE ALSO
  165.  
  166. L<Net::DBus>, L<Net::DBus::RemoteObject>, L<Net::DBus::Annotation>
  167.  
  168. =cut
  169.