FTP(3)

NAME
POE::Component::Client::FTP - Implements an FTP client POE Component

SYNOPSIS
 use POE::Component::Client::FTP;

 POE::Component::Client::FTP->spawn (
   Alias      => 'ftp',
   Username   => 'test',
   Password   => 'test',
   RemoteAddr => 'localhost',
   Events     => [ qw( authenticated put_ready put_error put_closed
                       get_connected get_data get_done size ) ]
 );

 # we are authenticated
 sub authenticated {
   $poe_kernel->post('ftp', 'command', 'args');
 }

 # data cnnection is ready for data
 sub put_ready {
   my ($status, $line, $param) = @_[ARG0..ARG3];

   open FILE, "/etc/passwd" or die $!;
   $poe_kernel->post('ftp', 'put_data', $_) while (<FILE>);
   close FILE;
   $poe_kernel->post('ftp', 'put_close');
 }

 # something bad happened
 sub put_error {
   my ($error, $param) = @_[ARG0,ARG1];

   warn "ERROR: '$error' occured while trying to STOR '$param'";
 }

 # data connection closed
 sub put_closed {
   my ($param) = @_[ARG0];
 }

 # file on the way...
 sub get_connected {
   my ($filename) = @_[ARG0];
 }

 # getting data from the file...
 sub get_data {
   my ($data, $filename) = @_[ARG0,ARG1];

 }

 # and its done
 sub get_done {
   my ($filename) = @_[ARG0];
 }

 # response to a size command
 sub size {
   my ($code, $size, $filename) = @_[ARG0,ARG1,ARG2];

   print "$filename was $size";
 }

 $poe_kernel->run();

Latest version and samples script can be found at: <http://www.wush.net/poe/ftp>

DESCRIPTION
Client module for FTP

CAVEATS
Untested.

METHODS

spawn
Alias      - session name
Username   - account username
Password   - account password
LocalAddr  - unused
LocalPort  - unused
RemoteAddr - ftp server
RemotePort - ftp port
Timeout    - unused
Blocksize  - unused
Events     - events you are interested in receiving.  See OUTPUT.

INPUT

cd [path]
cdup
delete [filename]
dir
get [filename]
ls
mdtm [filename]
mkdir [dir name]
mode [active passive]
noop
pwd
rmdir [dir name]
site [command]
size [filename]
type [A|I]
quit
put_data
    After receiving a put_ready event you can post put_data events to send data to the server.

put_close
    Closes the data connection. put_closed will be emit when connection is flushed and closed.

OUTPUT
Output is for "simple" ftp events is simply "event". Error cases are "event_error". ARG0 is the numeric code, ARG1 is the text response, and ARG2 is the parameter you made the call with. This is useful since commands such as size do not remind you of this in the server response.

Output for "complex" or data socket ftp commands is creates "event_connection" upon socket connection, "event_data" for each item of data, and "event_done" when all data is done being sent.

Output from put is "put_error" for an error creating a connection or "put_ready". If you receive "put_ready" you can post "put_data" commands to the component to have it write. A "put_done" command closes and writes. Upon completion, a "put_closed" or "put_error" is posted back to you.

SEE ALSO
the POE manpage, the perl manpage, the Net::FTP module, RFC 959

TODO

Improve local queueing of send data
    Perhaps I should be looking at the high_ and low_ marks given by the Wheel. Should also honor the block-size set forth by the spawn. This is trivial by playing with sendq.

Active transfer mode
    Low priority since I do not really see the importance.

More sample scripts and documentation

BUGS
Error checking assumes a closed socket is normal.
    No way around this I think. The actual return on failure is off of the server response code, so it should be fine.

AUTHORS & COPYRIGHT
Copyright (c) 2002 Michael Ching. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.