git.gag.com Git - debian/amanda/blob - perl/Amanda/Interactive.pm

   1 # Copyright (c) 2010 Zmanda, Inc.  All Rights Reserved.
   2 #
   3 # This program is free software; you can redistribute it and/or modify it
   4 # under the terms of the GNU General Public License version 2 as published
   5 # by the Free Software Foundation.
   6 #
   7 # This program is distributed in the hope that it will be useful, but
   8 # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
   9 # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  10 # for more details.
  11 #
  12 # You should have received a copy of the GNU General Public License along
  13 # with this program; if not, write to the Free Software Foundation, Inc.,
  14 # 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  15 #
  16 # Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  17 # Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  18
  19 package Amanda::Interactive;
  20
  21 =head1 NAME
  22
  23 Amanda::Interactive -- Parent class for user interactivity modules
  24
  25 =head1 SYNOPSIS
  26
  27     use Amanda::Interactive;
  28
  29     my $inter = Amanda::Interactive->new(name => 'stdin',
  30                                          inter_conf => $inter_conf);
  31     $inter->user_request(
  32         message => "Insert Volume labelled 'MY_LABEL-001'",
  33         finished_cb => sub {
  34             my ($err, $reply) = @_;
  35             if ($err) {
  36                 # error from the script
  37             } elsif (!defined $reply) {
  38                 # request aborted
  39             } else {
  40                 # use reply
  41             }
  42         });
  43
  44 =head1 SUMMARY
  45
  46 This package provides a way for Amanda programs to communicate interactively
  47 with the user.  The program can send a message to the user and await a textual
  48 response.  The package operates asynchronously (see L<Amanda::MainLoop>), so
  49 the program may continue with other activities while waiting for an answer from
  50 the user.
  51
  52 Several interactivity modules are (or soon will be) available, and can be
  53 selected by the user.
  54
  55 =head1 INTERFACE
  56
  57 A new object is create with the C<new> function as follows:
  58
  59     my $inter = Amanda::Interactive->new(
  60         name => $interactive_name,
  61         inter_conf => $inter_conf);
  62
  63 Where C<$interactive_name> is the name of the desired interactivity module
  64 (e.g., C<'stdin'>).
  65
  66 =head2 INTERACTIVE OBJECTS
  67
  68 =head3 user_request
  69
  70   $inter->user_request(message     => $message,
  71                        label       => $label,
  72                        err         => $err,
  73                        finished_cb => $finished_cb);
  74
  75 This method return immediately.  It sends C<message> to the user and waits for a
  76 reply.  The C<label> and C<err> parameters .. well, what do they do? (TODO)
  77
  78 The C<user_request> method's C<finished_cb> as parameter is similar to the
  79 callback of the same name in L<Amanda::Changer>.  In the even of an error, it
  80 is called with an C<Amanda::Changer::Error> object as first argument.  If the
  81 request is answered, then the second argument is the user's response.  If the
  82 request is aborted (see C<abort>, below), then both arguments are C<undef>.
  83
  84 =head3 abort
  85
  86   $inter->abort()
  87
  88 This method will abort all pending C<user_request> invocations, invoking their
  89 C<finished_cb> with C<(undef, undef)>.
  90
  91 =cut
  92
  93 sub new {
  94     shift eq 'Amanda::Interactive'
  95         or return;
  96     my %params = @_;
  97     my $name = $params{'name'};
  98
  99     die("No name for Amanda::Interactive->(new)") if !defined $name;
 100
 101     my $pkgname = "Amanda::Interactive::$name";
 102     my $filename = $pkgname;
 103     $filename =~ s|::|/|g;
 104     $filename .= '.pm';
 105
 106     if (!exists $INC{$filename}) {
 107         eval "use $pkgname;";
 108         if ($@) {
 109             my $err = $@;
 110             die ($err);
 111         }
 112     }
 113
 114     my $inter = $pkgname->new(%params);
 115
 116     return $inter;
 117 }
 118
 119 1;