view release on metacpan or  search on metacpan

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

The tasks of reading a master key and writing to a blank key are delegated to
'reader' and 'writer' scripts.  A pair of reader/writer scripts is supplied but
the application also supports using different scripts as dictated by a user
selection.  The supplied scripts assume file-by-file copying and format the
blank keys with a VFAT filesystem.  An alternate script might for example, use
C<dd> to write a complete filesystem image in a single operation.

A pair of scripts is referred to as a copying 'profile'.  The user can select a
profile via a command-line option or from a drop-down list when confirming the
master key.

The supplied scripts are called:

  copyfiles-reader.sh
  copyfiles-writer.sh

A profile does not need to include a reader script.  If a profile which only
includes a writer script is selected (via the command-line options) then the
application will go immediately into the mode of waiting for blank keys.

=head2 Profile Script API

The filename of the reader script must end with C<-reader> (followed by an
optional extension) and similarly, the filename of the writer script must end
with C<-writer>.

The reader/writer scripts do not have to be shell scripts - they merely need to
be executable.  The application ignores the file extension if it is present.

Both reader and writer scripts are assumed to have succeeded if they have an
exit status of 0.  A non-zero exit status will be considered a failure.

When the master key reader script is invoked, the following environment
variables will be set:

  USB_BLOCK_DEVICE    e.g.: /dev/sdb
  USB_MOUNT_DIR       e.g.: /tmp/usb-copy.nnnnn/mount/sdb
  USB_MASTER_ROOT     e.g.: /tmp/usb-copy.nnnnn/master

The writer script will be passed the same set of variables and one extra:

  USB_VOLUME_NAME     e.g.: FREE-STUFF

Be warned that this variable may be empty - depending on what was returned from
running C<dosfslabel> against the master key.  It is entirely reasonable for a
custom writer script to ignore this variable altogether and either use a
hardcoded volume label or not use one at all.

The writer script can also indicate progress (for updating the progress bar in
the icon) by writing lines to STDOUT in the following format:

  {x/y}

Where '{'  is the first character on a line; 'x' is an integer indicating the
number of steps completed; and 'y' is an integer indicating the total number
of steps. For example if the script output this line:

  {4/8}

the status icon would be updated to indicate 50% complete.

=head1 METHODS

=head2 Constructor

The C<new> method is used to create an application object.  It in turn calls
C<BUILD> to create and populate the application window and hook into HAL (the
Hardware Abstraction Layer) via DBus to get notifications of devices been
added/removed.

=head2 add_key_to_rack ( key_info )

Called from C<hal_device_added> if the newly added device matches the current
device filter settings.  The C<key_info> parameter supplied is a hashref of
device properties as returned by C<hal_device_properties>.  A GUI widget
representing the new USB key is added to the user interface and a data
structure to track the copying process is created.

=head2 build_console ( )

Called from C<build_ui> to create the scrolled text window for displaying
progress messages.

=head2 build_filters ( )

Called from C<build_ui> to create the toolbar of drop-down menus and text
entries for the device filter settings.

=head2 build_key_rack ( )

Called from C<build_ui> to create the container widget to house the
per-key status indicators.

=head2 build_menu ( )

Called from C<build_ui> to create the application menu and hook the menu
items up to handler methods.

=head2 build_ui ( )

Called from the constructor to create the main application window and populate
it with Gtk widgets.

=head2 check_for_root_user ( )

Called on startup to check that either the script is running as root or that sudo
is available.  In the latter case, sudo (or gksudo) will be used to invoke the
read/writer scripts.

If the script is not running with root permissions; and sudo is not available;
and the C<--no-root-check> option was not specified, this method will die with
an appropriate error message.

=head2 clean_temp_dir ( )

Called from the C<run> method immediately before the application exits.  This
method is responsible for removing the temporary directories containing the
master copy of the files and the mount points for the blank keys.

When running as a non-root user, this method needs to use sudo in order to