home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / lib / perl5 / Net / DBus / Binding / PendingCall.pm < prev    next >
Encoding:
Perl POD Document  |  2006-06-03  |  3.9 KB  |  167 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: PendingCall.pm,v 1.8 2006/01/27 15:34:24 dan Exp $
  20.  
  21. =pod
  22.  
  23. =head1 NAME
  24.  
  25. Net::DBus::Binding::PendingCall - A handler for pending method replies
  26.  
  27. =head1 SYNOPSIS
  28.  
  29.   my $call = Net::DBus::Binding::PendingCall->new(method_call => $call,
  30.                                                   pending_call => $reply);
  31.  
  32.   # Wait for completion
  33.   $call->block;
  34.  
  35.   # And get the reply message
  36.   my $msg = $call->get_reply;
  37.  
  38. =head1 DESCRIPTION
  39.  
  40. This object is used when it is neccessary to make asynchronous method
  41. calls. It provides the means to be notified when the reply is finally
  42. received.
  43.  
  44. =head1 METHODS
  45.  
  46. =over 4
  47.  
  48. =cut
  49.  
  50. package Net::DBus::Binding::PendingCall;
  51.  
  52. use 5.006;
  53. use strict;
  54. use warnings;
  55. use Carp;
  56.  
  57. use Net::DBus;
  58. use Net::DBus::Binding::Message::MethodReturn;
  59. use Net::DBus::Binding::Message::Error;
  60.  
  61. =item my $call = Net::DBus::Binding::PendingCall->new(method_call => $method_call,
  62.                                                       pending_call => $pending_call);
  63.  
  64. Creates a new pending call object, with the C<method_call> parameter
  65. being a reference to the C<Net::DBus::Binding::Message::MethodCall>
  66. object whose reply is being waiting for. The C<pending_call> parameter
  67. is a reference to the raw C pending call object.
  68.  
  69. =cut
  70.  
  71. sub new {
  72.     my $proto = shift;
  73.     my $class = ref($proto) || $proto;
  74.     my %params = @_;
  75.     my $self = {};
  76.  
  77.     $self->{method_call} = exists $params{method_call} ? $params{method_call} : die "method_call parameter is required";
  78.     $self->{pending_call} = exists $params{pending_call} ? $params{pending_call} : die "pending_call parameter is required";
  79.  
  80.     bless $self, $class;
  81.  
  82.     return $self;
  83. }
  84.  
  85. =item $call->cancel
  86.  
  87. Cancel the pending call, causing any reply that is later received
  88. to be discarded.
  89.  
  90. =cut
  91.  
  92. sub cancel {
  93.     my $self = shift;
  94.  
  95.     $self->{pending_call}->dbus_pending_call_cancel();
  96. }
  97.  
  98.  
  99. =item my $boolean = $call->get_completed
  100.  
  101. Returns a true value if the pending call has received its reply,
  102. or a timeout has occurred.
  103.  
  104. =cut
  105.  
  106. sub get_completed {
  107.     my $self = shift;
  108.  
  109.     $self->{pending_call}->dbus_pending_call_get_completed();
  110. }
  111.  
  112. =item $call->block
  113.  
  114. Block the caller until the reply is recieved or a timeout
  115. occurrs.
  116.  
  117. =cut
  118.  
  119. sub block {
  120.     my $self = shift;
  121.  
  122.     $self->{pending_call}->dbus_pending_call_block();
  123. }
  124.  
  125. =item my $msg = $call->get_reply;
  126.  
  127. Retrieves the C<Net::DBus::Binding::Message> object associated
  128. with the complete call.
  129.  
  130. =cut
  131.  
  132. sub get_reply {
  133.     my $self = shift;
  134.  
  135.     my $reply = $self->{pending_call}->dbus_pending_call_steal_reply();
  136.     my $type = $reply->dbus_message_get_type;
  137.     if ($type == &Net::DBus::Binding::Message::MESSAGE_TYPE_ERROR) {
  138.     return Net::DBus::Binding::Message::Error->new(replyto => $self->{method_call},
  139.                                message => $reply);
  140.     } elsif ($type == &Net::DBus::Binding::Message::MESSAGE_TYPE_METHOD_RETURN) {
  141.     return Net::DBus::Binding::Message::MethodReturn->new(call => $self->{method_call},
  142.                                   message => $reply);
  143.     } else {
  144.     confess "unknown method reply type $type";
  145.     }
  146. }
  147.  
  148. 1;
  149.  
  150. =pod
  151.  
  152. =back
  153.  
  154. =head1 SEE ALSO
  155.  
  156. L<Net::DBus::Binding::Connection>, L<Net::DBus::Binding::Message>, L<Net::DBus::ASyncReply>
  157.  
  158. =head1 AUTHOR
  159.  
  160. Daniel Berrange E<lt>dan@berrange.comE<gt>
  161.  
  162. =head1 COPYRIGHT
  163.  
  164. Copyright 2006 by Daniel Berrange
  165.  
  166. =cut
  167.