NAME
   Net::SFTP::Recursive - Perl class for transfering files recursively and
   securely

SYNOPSIS
     use Net::SFTP::Recursive;

     my %cfg = (user=>'usr_id', password=>'secret',
                local_dir=>'/ftp/dir', remote_dir=>'/remote/dir',
                file_filter=>'ftp*');
     my $sftp = Net::SFTP::Recursive->new;
     # or combine the two together
     my $sftp = Net::SFTP::Recursive->new(%cfg);

     # transfer files from local to remote
     $sftp->rput('/my/local/dir','/remote/dir');

     # transfer files from remote to local
     $sftp->rget('/pub/remotel/dir','/local/dir');

     # pass the output to &my_cb method to process
     $sftp->rget('/pub/mydir', '/local/dir', \&my_cb);

     # with file and dir filters
     $sftp->rget('/pub/mydir', '/local/dir', \&my_cb,
           {file_pat=>'pdf$', dir_pat=>'^f'});

     # you can also use a callback method for get or put method as well
     $sftp->rget('/remote/dir','/my/dir',\&my_cb,{cb4get=>\&myget_cb});
     $sftp->rput('/my/dir','/remote/dir',\&my_cb,{cb4put=>\&mysub_cb});

DESCRIPTION
   This class contains methods to transfer files recursively and securely
   using Net::SFTP and Net::SSH::Perl.

   *Net::SFTP* is a pure-Perl implementation of the Secure File Transfer
   Protocol (SFTP)--file transfer built on top of the SSH protocol.
   *Net::SFTP* uses *Net::SSH::Perl* to build a secure, encrypted tunnel
   through which files can be transferred and managed. It provides a subset
   of the commands listed in the SSH File Transfer Protocol IETF draft,
   which can be found at
   *http://www.openssh.com/txt/draft-ietf-secsh-filexfer-00.txt*.

   SFTP stands for Secure File Transfer Protocol and is a method of
   transferring files between machines over a secure, encrypted connection
   (as opposed to regular FTP, which functions over an insecure
   connection). The security in SFTP comes through its integration with
   SSH, which provides an encrypted transport layer over which the SFTP
   commands are executed, and over which files can be transferred. The SFTP
   protocol defines a client and a server; only the client, not the server,
   is implemented in *Net::SFTP*.

   Because it is built upon SSH, SFTP inherits all of the built-in
   functionality provided by *Net::SSH::Perl*: encrypted communications
   between client and server, multiple supported authentication methods
   (eg. password, public key, etc.).

   This class extends from *Net::SFTP* and inherents all the methods from
   it, plus more methods: *rget*, *rput*, and *local_ls*.

 new ($host, %args)

   Input variables:

     $host - ftp host name or IP address
     %args - configuration parameters

   Variables used or routines called:

     None

   How to use:

      my $obj = new Net::SFTP::Recursive;      # or
      my $obj = Net::SFTP::Recursive->new;     # or
      my $svr = 'ftp.mydomain.com';
      my $obj = Net::SFTP::Recursive->new($svr,
         user=>'usr',password=>'pwd');

   Return: new empty or initialized Net::SFTP::Recursive object.

   Opens a new SFTP connection with a remote host *$host*, and returns a
   *Net::SFTP* object representing that open connection.

   *%args* can contain:

   * user
       The username to use to log in to the remote server. This should be
       your SSH login, and can be empty, in which case the username is
       drawn from the user executing the process.

       See the *login* method in *Net::SSH::Perl* for more details.

   * password
       The password to use to log in to the remote server. This should be
       your SSH password, if you use password authentication in SSH; if you
       use public key authentication, this argument is unused.

       See the *login* method in *Net::SSH::Perl* for more details.

   * debug
       If set to a true value, debugging messages will be printed out for
       both the SSH and SFTP protocols. This automatically turns on the
       *debug* parameter in *Net::SSH::Perl*.

       The default is false.

   * warn
       If given a sub ref, the sub is called with $self and any warning
       message; if set to false, warnings are supressed; otherwise they are
       output with 'warn' (default).

   * ssh_args
       Specifies a reference to a list of named arguments that should be
       given to the constructor of the *Net::SSH::Perl* object underlying
       the *Net::SFTP* connection.

       For example, you could use this to set up your authentication
       identity files, to set a specific cipher for encryption, etc.

       See the *new* method in *Net::SSH::Perl* for more details.

METHODS
   The following are the common methods, routines, and functions defined in
   this classes.

 Exported Tag: All

   The *:all* tag includes all the methods or sub-rountines defined in this
   class.

     use Net::SFTP::Recursive qw(:all);

   It includes the following sub-routines:

  rget ($remote, $local, \&callback, $ar)

   Input variables:

     $remote - remote path on ftp server
     $local  - local path for storing the files and directories
     \&callback - a sub routine to process the intermediate information
     $ar     - hash ref for additional parameters
         file_pat - pattern for filtering file name such as
           .txt$ - all the files with .txt extension
         dir_pat  - pattern for filtering directory name
           ^F   - all the dir starting with F
         cb4get - sub ref for passing to get method. See callback
                  in get method in Net::SFTP

   Variables used or routines called:

     None

   How to use:

     my $svt = 'ftp.mydomain.com';
     my %cfg = (user=>'test_user', password => 'secure', debug=>1);
     my $sftp = Net::SFTP::Recursive->new($svr, %cfg);
        $sftp->rget('/pub/mydir', '/local/dir', \&my_cb);
     # with file and dir filters
        $sftp->rget('/pub/mydir', '/local/dir', \&my_cb,
           {file_pat=>'pdf$', dir_pat=>'^f', cb4get=>\&myget_cb});

   Return: $msg - number of files transferred

   Downloads files and/or sub-directory from *$remote* to *$local*. If
   *$local* is specified, it is opened/created, and the contents of the
   remote file *$remote* are written to *$local*. In addition, its
   filesystem attributes (atime, mtime, permissions, etc.) will be set to
   those of the remote file.

   If *rget* is called in a non-void context, returns the contents of
   *$remote* (as well as writing them to *$local*, if *$local* is provided.
   Undef is returned on failure.

   *$local* is default to the current directory if it is not specified.

   If *\&callback* is specified, it should be a reference to a subroutine.
   The subroutine will be executed at each iteration of transfering a file.
   The callback function will receive as arguments: a *Net::SFTP* object
   with an open SFTP connection; the remote file path and name; the local
   file path and name and the hash reference containing atime, mtime,
   flags, uid, gid, perm, and size in bytes). You can use this mechanism to
   provide status messages, download progress meters, etc.:

       sub callback {
           my($sftp, $remote, $local, $ar) = @_;
           print "Copied from $remote to $local ($ar->{size} Bytes)\n";
       }

  rput ($local, $remote, \&callback, $ar)

   Input variables:

     $local  - local path for storing the files and directories
     $remote - remote path on ftp server
     \&callback - a sub routine to process the intermediate information
     $ar     - hash ref for additional parameters
         file_pat - pattern for filtering file name such as
           .txt$ - all the files with .txt extension
         dir_pat  - pattern for filtering directory name
           ^F   - all the dir starting with F
         cb4put - sub ref for passing to get method. See callback
                  in put method in Net::SFTP

   Variables used or routines called:

     None

   How to use:

     my $svt = 'ftp.mydomain.com';
     my %cfg = (user=>'test_user', password => 'secure', debug=>1);
     my $sftp = Net::SFTP::Recursive->new($svr, %cfg);
        $sftp->rput('/local/mydir', '/remote/dir', \&my_cb);
     # with file and dir filters
        $sftp->rput('/local/mydir', '/remote/dir', \&my_cb,
           {file_pat=>'pdf$', dir_pat=>'^f', cb4put=>\&myput_cb});

   Return: $msg - number of files transferred

   Downloads files and/or sub-directory from *$remote* to *$local*. If
   *$local* is specified, it is opened/created, and the contents of the
   remote file *$remote* are written to *$local*. In addition, its
   filesystem attributes (atime, mtime, permissions, etc.) will be set to
   those of the remote file.

   If *rget* is called in a non-void context, returns the contents of
   *$remote* (as well as writing them to *$local*, if *$local* is provided.
   Undef is returned on failure.

   *$local* is default to the current directory if it is not specified.

   If *\&callback* is specified, it should be a reference to a subroutine.
   The subroutine will be executed at each iteration of transfering a file.
   The callback function will receive as arguments: a *Net::SFTP* object
   with an open SFTP connection; the remote file path and name; the local
   file path and name and the hash reference containing atime, mtime,
   flags, uid, gid, perm, and size in bytes). You can use this mechanism to
   provide status messages, download progress meters, etc.:

       sub callback {
           my($sftp, $local, $remote, $ar) = @_;
           print "Copied from $remote to $local ($ar->{size} Bytes)\n";
       }

  local_ls ($ldr[,$sr[,$hr]])

   Input variables:

     $ldr    - local path for files and sub-directories to be listed
     $sr     - sub ref for processing each file stat
     $hr     - hash ref for passing any additional parameters
         file_pat - pattern for filtering file name such as
           .txt$ - all the files with .txt extension
         dir_pat  - pattern for filtering directory name
           ^F   - all the dir starting with F
         cb4put - sub ref for passing to get method. See callback
                  in put method in Net::SFTP

   Variables used or routines called:

     None

   How to use:

     my $svt = 'ftp.mydomain.com';
     my %cfg = (user=>'test_user', password => 'secure', debug=>1);
     my $sftp = Net::SFTP::Recursive->new($svr, %cfg);
     # just get the result in list
     my @dir = $sftp->local_ls('/local/dir');
     # pass additional parameters and get the result as scalar (array ref)
     my $ar2 = $sftp->local_ls('/local/dir',undef,
           {file_pat=>'pdf$', dir_pat=>'^f'}
        );
     # process the file in proc_file sub routine
     $sftp->local_ls('/local/dir',\&proc_file);

   Return: @r or \@r depends on the caller subroutine.

   This methods fetches a directory listing of *$ldr*.

   If *$sr* is specified, for each entry in the directory, *$sr* will be
   called and given a reference to a hash with three keys: *filename*, the
   name of the entry in the directory listing; *longname*, an entry in a
   "long" listing like "ls -l"; and *a*, a *Net::SFTP::Attributes* object,
   which contains the file attributes of the entry (atime, mtime,
   permissions, etc.).

   If *$subref* is not specified, returns a list of directory entries, each
   of which is a reference to a hash as described in the previous
   paragraph.

HISTORY
   * Version 0.10
       This version includes the *rget*, *rput* and *local_ls* methods. It
       is released on 07/12/2005.

       07/13/2005 (htu) - changed *rput* so that it is passing a
       *Net::SFTP::Attributes* object to *do_mkdir*. Changed version to
       0.11.

SEE ALSO (some of docs that I check often)
       Data::Describe, Oracle::Loader, CGI::Getopt, File::Xcopy

AUTHOR
       Copyright (c) 2005 Hanming Tu. All rights reserved.

       This package is free software and is provided "as is" without
       express or implied warranty. It may be used, redistributed and/or
       modified under the terms of the Perl Artistic License (see
       http://www.perl.com/perl/misc/Artistic.html)

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.