view release on metacpan or  search on metacpan

lib/App/USBKeyCopyCon.pm  view on Meta::CPAN

package App::USBKeyCopyCon;

use warnings;
use strict;

=head1 NAME

App::USBKeyCopyCon - GUI console for bulk copying of USB keys

=cut

our $VERSION = '1.02';


=head1 SYNOPSIS

To launch the GUI application that this module implements, simply run the
supplied wrapper script:

  usb-key-copy-con

=head1 DESCRIPTION

This module implements an application for bulk copying USB flash drives
(storage devices).  The application was developed to run on Linux and is
probably not particularly portable to other platforms.

From a user's perspective the operation is simple:

=over 4

=item 1

insert a 'master' USB key when prompted - the contents of the key will be
copied into a temporary directory on the hard drive, after which the key can be
removed

=item 2

insert blank keys into all available USB ports - the app will detect when each
new key is inserted, start the copy process and alert the user on completion

=item 3

repeat step 2 as required

=back

The program can write to multiple keys in parallel.  It can also use filtering
on device parameters to only overwrite devices which match the vendor name
and storage capacity specified - other devices will be ignored.

The specifics of reading the master key, preparing a blank key (formatting
parameters etc) are implemented in short 'profile' scripts (a reader and a
writer).  You can supply your own profile scripts if your requirements differ
from those provided.

=head1 DEVELOPER INFORMATION

The remainder of the documentation is targetted at developers who wish to
modify or customise the application.

The application uses the Gtk2 GUI toolkit.  The wrapper script instantiates a
single application object like this:

  use App::USBKeyCopyCon;

  App::USBKeyCopyCon->new->run;

The constructor is responsible for building the user interface and the C<run>
method invokes the Gtk2 event loop.  UI events are dispatched as method calls
on the application object.

=cut

use Moose;

use Gtk2 -init;
use Glib qw(TRUE FALSE);
use Gtk2::SimpleMenu;

use App::USBKeyCopyCon::Chrome;

use Net::DBus;
use Net::DBus::GLib;
use Net::DBus::Dumper;

use POSIX        qw(:sys_wait_h);
use IO::Handle   qw();
use File::Path   qw(mkpath rmtree);
use File::Spec   qw();

use Data::Dumper;

lib/App/USBKeyCopyCon.pm  view on Meta::CPAN

=head2 ready_to_write ( )

This method is called after the master key has been read (or immediately on
startup if the selected profile does not use a reader script) and puts the
application into the mode of waiting for blank keys to be inserted.

=head2 remove_key_from_rack ( udi )

Called from C<hal_device_removed> to remove the indicator widget corresponding
to the USB key which has just been removed.

=head2 require_master_key ( )

Called from the constructor to put the app in the C<MASTER-WAIT> mode (waiting
for the master key to be inserted).  Can also be called from the
C<on_menu_file_new> menu event handler.

=head2 restore_automount ( )

This method is called at exit time restore the original GConf setting for the
GNOME/Nautilus media automount function.

=head2 run ( )

This method is called from the wrapper script.  It's job is to run the Gtk
event loop and when that exits, to call C<clean_temp_dir> and then return.

=head2 say ( message )

Appends a message to the console widget.  (Note, the caller is responsible
for supplying the newline characters).

=head2 scan_for_profiles ( )

Populates the hash of profile data in the C<profiles> attribute.

=head2 select_profile ( profile_name )

This method is used to select which reader/writer scripts will be used.  At
present there is one hard-coded call to this method in the constructor.
Ideally, the user would select from all available profile scripts in the
'confirm master' dialog.

=head2 set_temp_root ( pathname )

Called from C<confirm_master_dialog> based on the temp directory selected by
the user.

=head2 start_master_read ( key_info )

Called from C<hal_device_added> to fork off a 'reader' process to slurp in the
contents of the master key.

=head2 sudo_wrap ( command env-var-names )

If the script is run by a non-root user and sudo is available and the
C<--no-root-check> option was not specified, this method will return a command
string which wraps the supplied command in a call to either C<gksudo> or
C<sudo>.  For all other cases, C<command> is returned unmodified.

The C<gksudo> command is preferred since it gives the user a GUI prompt window
if it is necessary to prompt for a password.  This method handles the different
semantics required to pass environment variables through C<gksudo> and C<sudo>.

=head2 tick ( )

This timer event handler is used to take the child process exit status values
collected by the SIGCHLD handler and pass them to C<master_copy_finished> or
C<copy_finished> as appropriate.

=head2 update_key_progress ( udi, status )

Called from C<on_copier_pipe_read> to update the status icon for a specified
USB key device.  The progress parameter is a number in the range 0-10 for
copies in progress; -1 for a copy that has failed (non-zero exit status from
the 'writer' process); or -2 to indicate a device which did not match the
filter settings and is being ignored.

=head2 writer_script ( )

Returns the path to the script from the currently selected profile, which will
be used to write to the blank keys.

=cut

=head1 AUTHOR

Grant McLean, C<< <grantm at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-app-usbkeycopycon at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-USBKeyCopyCon>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc App::USBKeyCopyCon


You can also look for information at:

=over 4

=item * github: source code repository

L<http://github.com/grantm/usb-key-copy-con>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-USBKeyCopyCon>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/App-USBKeyCopyCon>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/App-USBKeyCopyCon>