Net::xFTP - Common wrapper functions for use with either Net::FTP, Net::SFTP, Net::SSH2, Net::SFTP::Foreign, Net::OpenSSH, and Net::FSP.
Jim Turner, <http://home.mesh.net/turnerjw/jim>
Copyright (c) 2005-2009 Jim Turner <http://home.mesh.net/turnerjw/jim>. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This is a derived work from Net::FTP and Net::SFTP. Net::FTP is copyrighted by Graham Barr and Net::SFTP is copyrighted by Benjamin Trott and maintained by Dave Rolsky. Both are copyrighted under the same terms as this module.
Many thanks go to these gentlemen whose work made this module possible.
use Net::xFTP;
#Test for needed protocol module.
die "..This server connection needs Net::SFTP!"
unless (Net::xFTP->haveSFTP());
#Establish a new connection to a remote host.
$ftp = Net::xFTP->new('SFTP', "some.host.name", Debug => 0,
user => 'userid', password => 'opensesme')
or die "Cannot connect to some.host.name: $@";
#Establish a "local" (simulated connection) to self.
$ftp = Net::xFTP->new();
#Change the current working directory on the remote host.
$ftp->cwd('/pub') or die
"Cannot change working directory ", $ftp->message();
#Get the current working directory on the remote host.
my $current_remote_path = $ftp->pwd();
#Get a list of files and subdirectories in "/pub".
my @filesAndSubfolders = $ftp->ls('/pub');
#Get a detailed (ls -l) list of files and subdirectories.
my @ls_l_details = $ftp->dir('/pub');
#Create a new subdirectory.
$ftp->mkdir('myownfolder')
or die "Cannot make subdirectory ", $ftp->message();
#Remove an empty subdirectory.
$ftp->rmdir('myownfolder')
or die "Cannot remove subdirectory ", $ftp->message();
#Get the contents of a file on the remote server.
$ftp->get('remote.file', 'local.file')
or die "get failed ", $ftp->message();
#Get the contents of a remote file and write to an open filehandle.
open FHANDLE, ">local.file" or die "Could not open local file ($!)";
print FHANDLE "A Header Line!\n";
flush FHANDLE;
$ftp->get('remote.file', *FHANDLE)
or die "get failed ", $ftp->message();
print FHANDLE "A Footer Line!\n";
close FHANDLE;
#Put a local file onto the remote server.
$ftp->put('local.file', 'remote.file')
or die "put failed ", $ftp->message();
#Read from a file handle putting the content in a remote file.
open FHANDLE "<local.file" or die "Could not open local file ($!)";
$ftp->put(*FHANDLE, 'remote.file')
or die "put failed ", $ftp->message();
close FHANDLE;
#Delete a remote file.
$ftp->delete('some.file')
or die "Cannot delete file ", $ftp->message();
#Rename a remote file.
$ftp->rename('oldfilename', 'newfilename')
or die "Cannot delete file ", $ftp->message();
#Change permissions of a remote file.
$ftp->chmod(755, 'some.file.or.dir')
or die "Cannot change permissions ", $ftp->message();
#Fetch the size of a remote file.
print "remote.file has ".$ftp->size('remote.file')." bytes.\n";
#Copy a remote file to a new remote location.
$ftp->copy('remote.fileA','remote.fileB')
or die "Cannot copy the file ", $ftp->message();
#Move a remote file to a new remote location.
$ftp->move('old/path/old.filename', 'new/path/new.filename')
or die "Cannot move the file ", $ftp->message();
#Disconnect an existing connection.
$ftp->quit();
Even though Net::xFTP will work in a connection-simulating ``local'' mode,
to be truly useful, one needs either Net::FTP, Net::SFTP, or
preferrably both.
Net::SFTP::Attributes is also needed, if using Net::SFTP.
Net::SFTP::Constants is also needed for using the copy,
move functions, or using the put function with a filehandle.
Net::xFTP is a wrapper class to combine common functions of Net::FTP and
Net::SFTP into a single set of functions allowing one to switch seemlessly
between the two without having to make non-trivial code changes. Only
functionality common to both protocols has been implemented here with the
intent and invitation to add more functions and features and mayby other
*FTP-ish modules in the future.
I created this module when I had developed several web application programs which FTP'd data to and from a central server via Net::FTP. The client changed to a new remote server that required Net::SFTP. Faced with rewriting these programs without changing functionality (since for some reason Net::FTP and Net::SFTP use slightly different methods and conventions). I decided instead to simply create a common module that would use the same method calls to do the same things and allow me to specify the protocol in a single place. I also am the author of ptkftp, a Perl/Tk graphical user-interface to Net::FTP and Net::SFTP. I now intend to rewrite it to use Net::xFTP and greatly reduce and simplify the code for that application.
Hopelfully others will find this module useful. Patches adding needed functionality are welcome.
PROTOCOL is the underling module or protocol name. Currently valid
values are: FTP, SFTP, Net::FTP, and Net::SFTP. There are only
two real options - one may either include or omit the ``Net::'' part. A third
option is to pass ``local'', zero, an empty string, or undef in which
case the functions are mapped over the local machine, accessable as if
connected via ftp! For example, the get and put methods simply copy
files from one directory to another on the user's local machine.
If PROTOCOL is local, then the other options, ie. HOST are optional.
Default is local (no remote connection).
HOST is the name of the remote host to which an FTP connection is
required (except with the local protocol.
OPTIONS are passed in a hash like fashion, using key and value pairs.
Possible options are:
user is the user-name or login-id to log in with. For FTP, if not specified, then 'anonymous' is used.
password is the password, if required, for connecting. For FTP, if not specified, then 'anonymous@' is used.
BlockSize specifies the buffer size to use for buffered data transfers. Default is 10240.
Debug specifies the debug level for FTP and toggles it for SFTP. Default is zero (false), which turns debug off for both. Set the numeric level (non-zero) for FTP, and SFTP will accept it as true and turn on debugging.
xftp_home specifies an alternate directory for SFTP to create the ``.ssh'' subdirectory for keeping track of ``known hosts''. The default is $ENV{HOME}. This option is useful for web CGI scripts which run often under a user with no ``home'' directory. The format is: ``/some/path/that/the/user/can/write/to''.
To specify protocol-specific args Not to be passed if the other protocol is used, append ``protocol_'' to the option, ie. ``sftp_ssh_args'' to specify the SFTP option ``ssh_args''.
Unless otherwise stated all methods return either a true or false value, with true meaning that the operation was a success. When a method states that it returns a value, failure will be returned as undef or an empty list.
Always returns undef.
Always returns undef.
PATH, which can be either a file or subdirectory.
PERMISSIONS is an octal number expressed as a decimal. Common values are
777 (full access), 755 (rwxr-xr-x) and 644 (rw-r--r--).
Returns 1 if successful, undef if fails.
OLDFILE to NEWFILE, creating or overwriting it if
necessary. OLDFILE and NEWFILE may be in different directories.
Returns 1 if successful, undef if fails.
$dir. If
$dir is "..", the FTP CDUP command is used to attempt to
move up one directory. If no directory is given then an attempt is made
to change the directory to the root directory. For SFTP, the new directory
is saved and subsequent relative paths have this value appended to them.
Returns 1 if successful, undef if fails.
FILENAME. Calls either the
FTP->delete method or SFTP->do_remove method. For local, calls Perl's
unlink function.
Returns 1 if successful, undef if fails.
DIR, or the current directory in long (ls -l)
format. See also the ls method.
DIR specifies the absolute or relative path. Default is ``.'' (Current
working directory). ``..'' is also valid.
SHOWALL - if true, all files and subdirectory names will be listed.
If false, ``hidden'' files and subdirectories (those whose names begin
with a ``.'') will be omitted. Default is false.
In an array context, returns a sorted list of lines returned from the
server. In a scalar context, returns a reference to the list. Each line
consists of either a file or subdirectory name or ``.'' or ``..''. ``..''
is omitted if DIR is ``/''.
Returns undef on failure.
REMOTE_FILE from the server and store locally. If LOCAL_FILE
is not specified, then a file with the same name as REMOTE_FILE sans
the path information will be created on the current working directory of
the machine the program is running on. LOCAL_FILE can also be an open
file-handle (see example in the SYNOPSIS section). If so, it must be
passed as a typeglob. For local protocol, simply copys REMOTE_FILE
to LOCAL_FILE.
Returns 1 if successful, undef if fails.
DIR is a subdirectory, 0 (false) otherwise.
DIR, or the current directory. Just the file
and or subfolder names are returned. For a full listing (like ls -l),
see the dir method.
DIR specifies the absolute or relative path. Default is ``.'' (Current
working directory). ``..'' is also valid.
SHOWALL - if true, all files and subdirectory names will be listed.
If false, ``hidden'' files and subdirectories (those whose names begin
with a ``.'') will be omitted. Default is false.
In an array context, returns a sorted list of lines returned from the
server. In a scalar context, returns a reference to the list. Each line
consists of either a file or subdirectory name or ``.'' or ``..''. ``..''
is omitted if DIR is ``/''.
Returns undef on failure.
DIR. If RECURSE is true then
mkdir will attempt to create all the directories in the given path.
Calls the mkdir method in FTP or do_mkdir method in SFTP.
Returns 1 if successful, undef if fails.
OLDFILE to NEWFILE, creating or overwriting it if
necessary. OLDFILE and NEWFILE may be in different directories,
unlike rename, which can only change the name (in the same path).
Essentially does a copy, followed by a delete, if successfully
copied.
Returns 1 if successful, undef if fails.
Returns a Net::xFTP handle object, or undef on failure. If it fails, the reason will be in $@.
Net::FTP or Net::SFTP, depending on which underlying
module is being used. Returns an empty string is local is used.
LOCAL_FILE and REMOTE_FILE are
specified as strings representing the absolute or relative path and file
name. If REMOTE_FILE is not specified then the file will be stored in
the current working directory on the remote machine with the same fname
(sans directory information) as LOCAL_FILE. LOCAL_FILE can also be
an open file-handle (see example in the SYNOPSIS section). If so, it
must be passed as a typeglob and REMOTE_FILE must be specified. For
local protocol, simply copies LOCAL_FILE to REMOTE_FILE.
Returns 1 if successful, undef if fails.
NOTE: If for some reason the transfer does not complete and an error is returned then the contents that had been transfered will not be remove automatically.
quit() for FTP, For SFTP, which does not have a terminating
method, simply deletes the SFTP object.
Returns 1 if successful, undef if fails.
DIR. The directory must first be
empty to remove. Calls the rmdir method for FTP and do_rmdir for
SFTP. For local protocol, simiply removes the directory.
Returns 1 if successful, undef if fails.
FILE, or undef on failure. For FTP,
the size method is called, for SFTP: do_stat. For <local>, perl's
stat function.
Net::xFTP is designed for commonality, it may occassionally
be necessary to call a method specific to a given protocol. To do this,
simply invoke the method as follows:
$ftp->{xftp}->method ( args )
Example:
| print ``-FTP size of file = ''.$ftp->{xftp}->size('/pub/myfile').``.\n'' | |
if ($ftp->protocol() eq 'Net::FTP'); |
Add a stat method when this is supported in Net::FTP.
Please report any bugs or feature requests to
bug-net-xftp@rt.cpan.org, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
This is a derived work from Net::FTP and Net::SFTP. Net::FTP is copyrighted by Graham Barr and Net::SFTP is copyrighted by Benjamin Trott and maintained by Dave Rolsky. Both are copyrighted under the same terms as this module.
Many thanks go to these gentlemen whose work made this module possible.
ftp, sftp, xftp, Net::FTP, Net::SFTP, Net::SSH2, Net::SFTP::Foreign, Net::OpenSSH, and Net::FSP