home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl5 / Net / DBus / Binding / PendingCall.pm < prev    next >
Encoding:
Perl POD Document  |  2008-02-20  |  3.9 KB  |  178 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 same terms as Perl itself. Either:
  7. #
  8. # a) the GNU General Public License as published by the Free
  9. #   Software Foundation; either version 2, or (at your option) any
  10. #   later version,
  11. #
  12. # or
  13. #
  14. # b) the "Artistic License"
  15. #
  16. # The file "COPYING" distributed along with this file provides full
  17. # details of the terms and conditions of the two licenses.
  18.  
  19. =pod
  20.  
  21. =head1 NAME
  22.  
  23. Net::DBus::Binding::PendingCall - A handler for pending method replies
  24.  
  25. =head1 SYNOPSIS
  26.  
  27.   my $call = Net::DBus::Binding::PendingCall->new(method_call => $call,
  28.                                                   pending_call => $reply);
  29.  
  30.   # Wait for completion
  31.   $call->block;
  32.  
  33.   # And get the reply message
  34.   my $msg = $call->get_reply;
  35.  
  36. =head1 DESCRIPTION
  37.  
  38. This object is used when it is neccessary to make asynchronous method
  39. calls. It provides the means to be notified when the reply is finally
  40. received.
  41.  
  42. =head1 METHODS
  43.  
  44. =over 4
  45.  
  46. =cut
  47.  
  48. package Net::DBus::Binding::PendingCall;
  49.  
  50. use 5.006;
  51. use strict;
  52. use warnings;
  53.  
  54. use Net::DBus;
  55. use Net::DBus::Binding::Message::MethodReturn;
  56. use Net::DBus::Binding::Message::Error;
  57.  
  58. =item my $call = Net::DBus::Binding::PendingCall->new(method_call => $method_call,
  59.                                                       pending_call => $pending_call);
  60.  
  61. Creates a new pending call object, with the C<method_call> parameter
  62. being a reference to the C<Net::DBus::Binding::Message::MethodCall>
  63. object whose reply is being waiting for. The C<pending_call> parameter
  64. is a reference to the raw C pending call object.
  65.  
  66. =cut
  67.  
  68. sub new {
  69.     my $proto = shift;
  70.     my $class = ref($proto) || $proto;
  71.     my %params = @_;
  72.     my $self = {};
  73.  
  74.     $self->{connection} = exists $params{connection} ? $params{connection} : die "connection parameter is required";
  75.     $self->{method_call} = exists $params{method_call} ? $params{method_call} : die "method_call parameter is required";
  76.     $self->{pending_call} = exists $params{pending_call} ? $params{pending_call} : die "pending_call parameter is required";
  77.  
  78.     bless $self, $class;
  79.  
  80.     return $self;
  81. }
  82.  
  83. =item $call->cancel
  84.  
  85. Cancel the pending call, causing any reply that is later received
  86. to be discarded.
  87.  
  88. =cut
  89.  
  90. sub cancel {
  91.     my $self = shift;
  92.  
  93.     $self->{pending_call}->dbus_pending_call_cancel();
  94. }
  95.  
  96.  
  97. =item my $boolean = $call->get_completed
  98.  
  99. Returns a true value if the pending call has received its reply,
  100. or a timeout has occurred.
  101.  
  102. =cut
  103.  
  104. sub get_completed {
  105.     my $self = shift;
  106.  
  107.     $self->{pending_call}->dbus_pending_call_get_completed();
  108. }
  109.  
  110. =item $call->block
  111.  
  112. Block the caller until the reply is recieved or a timeout
  113. occurrs.
  114.  
  115. =cut
  116.  
  117. sub block {
  118.     my $self = shift;
  119.  
  120.     $self->{pending_call}->dbus_pending_call_block();
  121. }
  122.  
  123. =item my $msg = $call->get_reply;
  124.  
  125. Retrieves the C<Net::DBus::Binding::Message> object associated
  126. with the complete call.
  127.  
  128. =cut
  129.  
  130. sub get_reply {
  131.     my $self = shift;
  132.  
  133.     my $reply = $self->{pending_call}->_steal_reply();
  134.     my $type = $reply->dbus_message_get_type;
  135.     if ($type == &Net::DBus::Binding::Message::MESSAGE_TYPE_ERROR) {
  136.     return $self->{connection}->make_raw_message($reply);
  137.     } elsif ($type == &Net::DBus::Binding::Message::MESSAGE_TYPE_METHOD_RETURN) {
  138.     return $self->{connection}->make_raw_message($reply);
  139.     } else {
  140.     die "unknown method reply type $type";
  141.     }
  142. }
  143.  
  144. =item $call->set_notify($coderef);
  145.  
  146. Sets a notification function to be invoked when the pending
  147. call completes. The callback will be passed a single argument
  148. which is this pending call object.
  149.  
  150. =cut
  151.  
  152. sub set_notify {
  153.     my $self = shift;
  154.     my $cb = shift;
  155.  
  156.     $self->{pending_call}->_set_notify($cb);
  157. }
  158.  
  159. 1;
  160.  
  161. =pod
  162.  
  163. =back
  164.  
  165. =head1 SEE ALSO
  166.  
  167. L<Net::DBus::Binding::Connection>, L<Net::DBus::Binding::Message>, L<Net::DBus::ASyncReply>
  168.  
  169. =head1 AUTHOR
  170.  
  171. Daniel Berrange E<lt>dan@berrange.comE<gt>
  172.  
  173. =head1 COPYRIGHT
  174.  
  175. Copyright 2006 by Daniel Berrange
  176.  
  177. =cut
  178.