view release on metacpan or  search on metacpan

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

=head1 NAME

App::Smbxfer - A "modulino" (module/program hybrid) for file
transfer between Samba shares and the local filesystem.


=head1 MODULINO: MOTIVATION AND DESCRIPTION

This software provides a subset of the features of smbclient.  The main
motivation for its existence was a limitation in smbclient causing a timeout
that precluded transfer of large files.

An especially useful way to apply this modulino is to invoke it as a
non-interactive command-line tool.  This can be an effective way to create cron
jobs for backup of data TO Samba shares.

As a module, it provides functions to conduct file transfers, get information on
Samba filesystem objects, and to perform validations on "SMB path specs," Samba
location identifiers of the form:

    smb://server/share/path/to/something


=head1 VERSION

This documentation refers to App::Smbxfer version 0.01.


=head1 MODULE: FUNCTIONS

Functions in App::Smbxfer are used to aid with transferring files between Samba
shares and the local filesysem.  This is the context in which the following
functions are provided.

=head2 usage

Prints command-line usage information.

=head2 options

Prints command-line options.

=head2 run

"main() method" for running module as a command-line program.

=head2 credentials

    my ($username, $password, $domain) = credentials( $credentials_file );

Load SMB access credentials from the specified filename, which should be
formatted as expected by the smb* suite of tools (smbclient, etc.)

=head2 validated_paths

    my ($local_path, $remote_smb_path_spec) = validated_paths(
        SMB => $smb,
        SOURCE => $source,
        DEST => $dest,
        SOURCE_IS_LOCAL => $whether_or_not_source_is_local_path
    );

Given source, destination paths as expected by modulino's run()
function, performs validations and returns normalized forms of both paths in
order (source, dest).

=head2 do_smb_transfer

    do_smb_transfer(
        SMB_OBJECT =>        $smb,
        LOCAL_PATH =>        $local_path,
        SMB_PATH_SPEC =>     $remote_smb_path_spec,
        SOURCE_IS_LOCAL =>   $whether_or_not_source_is_local_path,
        RECURSIVE =>         1,
        CREATE_PARENTS =>    1
    );

Handles setup for upload/download, then delegates responsibility for file
transfer to the appropriate handler.

=head2 parse_smb_spec

    my ($smb_parent_path, $smb_path, $smb_share_spec) =
        ( parse_smb_spec( $smb_path_spec ) )[2,3,4];

Given a Samba location identifier with optional leading 'smb:', returns a
number of potentially useful pieces of the path (server, share, path name,
basename, etc.).

The following are returned (in order):

=over

=item 0

Server

=item 1

Share

=item 2

Parent path

=item 3

Path

=item 4

Share spec

=item 5

Path spec

=item 6

Parent path spec

=item 7

Basename

=back

=for Enhancement
    cleanup to fix returning a long list of variables?

=cut

=head2 create_smb_dir_path