view release on metacpan or  search on metacpan

lib/AnyEvent/FTP/Client.pm  view on Meta::CPAN

for the server to send to.

=head1 METHODS

Unless otherwise specified, these methods will return an AnyEvent condition variable
(AnyEvent->condvar) or an object that implements its interface (methods C<recv>, C<cb>).
On success the C<send> will be used on the condition variable, on failure C<croak> will be
used instead.  Unless otherwise specified the object sent (for both success and failure)
will be an instance of L<AnyEvent::FTP::Client::Response>.

As an example, here is a fairly thorough handling of a response to the standard FTP C<HELP>
command:

 $client->help->cb(sub {
   my $res = eval { shift->recv };
   if(my $error = $@)
   {
     # $error isa AnyEvent::FTP::Client::Response with a 4xx or 5xx
     # code
     my $code = $error->code;
     # the message component is always a list ref, even if
     # the response had just one message line
     my @msg  = @{ $error->message };
     # $error is stringified into something human readable when
     # it is streated as a string
     warn "error trying FTP HELP command: $error";
   }
   else
   {
     # $res isa AnyEvent::FTP::Client::Response with a 2xx or 3xx
     # code
     my $code = $res->code;
     # the message component is always a list ref, even if
     # the response had just one message line
     my @msg = @{ $res->message };
     # $res is stringified into something human readable when
     # it is streated as a string
     print "help message: $res";
   }
 });

=head2 connect

 $client->connect(@remote_host);

Connect to the FTP server.  The remote host may be specified in one
of these ways:

=over 4

=item $client-E<gt>connect($host, [ $port ])

The host and port of the remote server.  If not specified, the default FTP port will be used (21).

=item $client-E<gt>connect($uri)

The URI of the remote FTP server.  C<$uri> must be either an instance of L<URI> with the C<ftp>
scheme, or a string with an FTP URL.

If you use this method to connect to the FTP server, connect will also attempt to login with
the username and password specified in the URL (or anonymous FTP if no credentials are
specified).

If there is a path included in the URL, then connect will also do a C<CWD> so that you start
in that directory.

=back

=head2 login

 $client->login($user, $pass);

Attempt to login to the FTP server which has already been connected to using
the C<connect> method.  This is not necessary if you used C<connect> with a URI.

=head2 retr

 $client->retr($filename, $local, %options)

Retrieve the given file from the server and use C<$local> to store the results.

Returns an instance of L<AnyEvent::FTP::Client::Transfer>, which supports the
AnyEvent condition variable interface (that is it has C<cb> and C<recv> methods).
Its callback will be called when the transfer is complete.

C<$local> may be one of

=over 4

=item scalar reference

The contents of the file will be stored in the scalar referred to by the reference.

 my $local;
 $client->retr('foo.txt', \$local);

=item file handle

The content of the remote file will be written into the local file handle as it is
received

 open my $fh, '>', 'foo.txt';
 binmode $fh;
 $client->retr('foo.txt', $fh);

=item the name of the local file

If C<$local> is just a regular non reference scalar, then it will be treated as the
local filename, which will be created and written to as data is received from the
server.

 $client->retr('foo.txt', 'foo.txt');

=item subroutine reference / callback reference

The contents of the file will be passed to the callback as they are received.

 $client->retr('foo.txt', sub {
     my ($data) = @_;
     # Do something with $data
   },