[library-interface documentation isn't available - but it's probably not needed, because of being really simple (look at headers for documentation)]

DRftp user documentation

Files

Documentation
doc/: this documentation
Runtime
drftp.so: drftp library (you must compile it first :-) )
drftp.pl: drftp-server (perl script)
drfcl.pl: drftp-distributed client (perl script)
pftpcl.pm: perl-module, includes pFtpClient object
Samples
s.s: shell script that runs and inits drftp-server
s.i: sample file containing user, password and some useful user-functions (init commands for drftp)
s.w: sample work-file
tp: defines function for controlling drftp-server
Other
README: some basic information
COPYING: copying and using conditions

Tutorial

This client was written as fully automated, so there isn't any user-friendly interface (for now). Here is shown how communication works (there is one more user-friendly way shown below):

 0$ mkfifo f
 1$ ./drftp.pl < f > o &
 2$ p=$!
 3$ echo 'anonymous:an@:server.domain.org:21:0:3000' > f
 4$ echo '$cmaxclients = 1; $dmaxclients = 1; addFiles "work";' > f; kill -1 $p
d5$ echo 'setCApaddr "192.168.1.1:2000";' > f; kill -1 $p
d6 connecting distributed client from 192.168.1.1, port 2000
 7 sleeping
 8$ echo 'saveFiles "work";' > f; kill -1 $p
 9$ cat work
10 looks good, all work done (or wanna only interrupt)...
11$ kill $p

d4.5$ ./drfcl drftp-script-computer 3000
d4.6 Using address 192.168.1.1:2000
d5.5 <pressing return>

(d means operation for distributed client) Looks easy, so what does it mean:

On the first line there is executed drftp perl-script
On the third line options are given him in following format: user:password:ftp-server:ftp-port:flags:distributed_port, where flags include use_passive (0-bit) - boolean that says if passive-connection should be used (note - some servers do not support it) and distributed_port is port for distributed clients - if < 0 distributed clients will not be supported, if 0 random port will be used, if greater, exactly this port will be used.
On the fourth line there is set max number of local and distributed clients and addFiles will tell perl, which files to download/upload - format of this will be described later. HUP is sent to the script to tell the perl there are waiting commands on stdin.
On the eighth line current status of work is saved.
On the eleventh line script is killed

Following rows only for distributed clients:
On the line 4.5 there is executed distributed client
On 4.6 it prints from which address it will be connected
On 5 perl is informed from which address it can accept distributed client - just for security
On 5.5 client starts to connect to drftp-server and it should accept this connection

File "work" consists of new-line separated records with the following format:

, where what_to_do can be g (get) or p (put) or G/P (get/put but already done), type is type of the file (f - file, d - directory, l - symlink, a - autodetect), remote_file is name of the remote file (full name with slash as the first character), local_file is name of the local file, link_perm is the file on which the link points or permission for the local_file (in this case rwx------). The example is in file "s.w".

Files s.?

File s.s (shell script) will run drftp.pl and automatically make some other actions: It will write content of $1.i to the $1.f and redirect input of drftp.pl from $1.f. Also defines shell-function rf$1 accepting one argument which will it write to the $1.f and then will send HUP to the drftp.pl. So, drftp can be launched by command . ./s.s s. File s.i contains header with user:passwd:... and some useful perl-commands and user-functions (one of them automatically shuts down ftp when finished). So, previous example rewritten by using s.? files looks like following:

 0$ cp s.i profile1.i; cp s.w profile1.w; vi profile1.i profile1.w
 1$ . ./s.s profile1
d5$ rfprofile1 'setCApaddr "192.168.1.1:2000";'
d6  connecting distributed client from 192.168.1.1, port 2000
 7  working...
 8  done, drftp three times beeps and exits

As you see it's really much more easier... On the line 0 new profile is created from s.? files, edited user/passwd, server etc. On the lien 1 drftp is started, it reads login-information from profile1.i and also sets some user-functions, reads profile1.w (usually, it depends on variable user_fname, seconds line in profile1.i). Connecting of distributed client is the same... Then drftp works and when done, it beeps and exits (one user-function in s.i/profile1.i).

Full description of user-interface

The only user-interface are the perl-commands, you can change some variables and call some functions. You must send these commands to stdin of drftp-server (named pipe recommended) and then kill him with HUP signal.
And see Tutorial first where described executing and initing drftp-server/client.

User interface of drftp-server - variables

List of variables, RO means you shouldn't modify it.

$cmaxclients: max number of local-clients, you can modify it when running, when you lower it, some clients will be disconnected as soon as possible
$dmaxclients: max number of distributed clients, you can modify it as described for $cmaxclients
$confreq: how often to try to connect
$syserrwait: how long wait for initing any action when unexpected error occurs
$ktimeout: time after inactive client is killed
$dlev: debug-level, when first bit set, print all unexpected local-errors, when >= 2 inform about creating and destroying clients, when >= 4 inform about timeout-actions, when >= 6 inform about connecting/disconnecting clients, when >= 8 inform about every high-level action, when >= 10 inform about every low-level action
${,c,d}running: RO, number of connected clients (c means local, d distributed)
${,c,d}waiting: RO, number of waiting clients (connected, but do nothing)
${,c,d}xting: RO, number of getting/putting clients
${,c,d}nclients: RO, number of created clients
@cl: RO, all clients, order in this array is changed by many actions, use client->{'cid'} as key
@filesin: files waiting for their get/put
@filesdone: files downloaded/uploaded
@filesnow: RO, files now downloading/uploading (xting)
$tsel: timeout for select, set to -1 (means infinite timeout) at the start of the loop
$rsel: RO, return code from last select, note - it's return code from C-function, not from perl function select
$ctm: RO, current loop time (this variable is set after select returns and it's not modified in any other loop's part - used instead of time(), which isn't constant)
$gs: global status - C++ class (see if_perl.xs for interface :-) ), other common variables usually used by C++-part, you needn't probably use it
$todestr: number of clients that should test {'todestr'}
$toldestr: number of clients that should test {'toldestr'}

User interface - functions

List of functions available for user-interface

addFiles filename: loads work from file filename, format is described in Tutorial
saveFiles filename: saves current status of work to file filename
setCApaddr paddr: sets the address from that can be accepted clients, the format of paddr is n.n.n.n:port.
findCid cid: returns number of client identified by cid
killCl n: kills the n-th client's ftp-connection, return -1 if already killed, 0 if ok and 1 if it has been destroyed in killCl
ckillCl n: destroys the n-th client, returns 1
changedStatus n oldst [oldfinf [newst]]: updates drftp-server variables, you should call this function when doing any action not supported by user-interface. oldfinf should be value of (defined cl->{'finf'}) before the action or -1 if you do not want to check for finf-changing. The default of oldfinf is -1, default of newst is getStatus().

Members and functions of client-structure (hash array)

{'cid'}: client identification (as pid on UNIX)
{'distr'}: when non-zero, distributed client
{'finf'}: file currently xting
{'files'}: when xting directory, contains its files
{'destr'}: destroy-command, when setting this member, client will be "destroyed" at the end of loop. When set to 1 it's only closed, when 0 it's killed, when -1 it's c-killed (killed and destroyed). Variable $todestr must be incremented, when setting this member.
{'ldestr'}: the same as {'destr'}, but waits for completing current action. You must advance $toldestr variable, when setting this member.

Members and functions of fileinfo-structure (hash array)

{'act'}: what to do, gGpP (get/put), when upper, already done
{'ft'}: file-type, fdlua (file, directory, symlink, unknown, autodetect); note - autodetect is not supported for put
{'rem'}: remote name of the file
{'loc'}: local name of the file
{'oth'}: contains permission for file/dir, destination for symlink
{'err'}: last error
{'tail'}: user-defined
{'size'}: size of the file (only internal)

User functions

All user functions must be assigned by $userfunc = sub { ... }; or $userfunc = \&mysub;.

$userfunc: main user function, if defined, it's called every loop (after testing ktimeout)
$usersetfd: user function, if defined, called after calling setFds and computing time to select and before select
$usertestrep: can be used to test some special reply's, called when $cl->go() returns, two arguments are passed to that function - client and return code from go(), simply returning second argument has no effect.
Note: if second argument is $FtpClient::RT_CONT, reply from server can be incomplete and return-code can be unset.
$usertestfile: can be used to test parameters of processed file, if it returns <= 0 file will be ignored, if other file will be appended to @filesdone or @filesin dependent on case of ->{'act'}
usercreat: used to create file/directory/symlink, three argument are passed - client, fileinfo, and filetype (-2 for directory, 0 for file, -3 for symlink); there is default function dummy_usercreat, you can call it and check only some special situation
useropen: used to open file/directory/symlink, arguments are the same as for usercreat; you can modify member {'files'} of client to avoid reading files in main open-function; there is default function dummy_useropen
userclose: used to close file/directory/symlink; there is default function dummy_userclose, it calls close for filetype file and closedir for directory

Description of drfcl.pl

There is no way, how to configure distributed client when running. There are only two arguments for this program - drftp-server-hostname and his port. Also one option (-m<number>) for setting $masq variable. variable $masq tells what to masquerade - 0. bit means to masquerade PORT command, 1. bit means to masquerade PASV reply. The default value is 3 (masquerade both).

Client 1.5.0 and higher recognises following perl-variables (with their defaults):

$localport=0;

use this port for client-socket bind)

$localaddr=$ENV{'HOSTNAME'};

use this address for client-socket

$forceaddr="";

use this address instead of that received from drftp-server

$forceport=0;

use this port instead of that received from drftp-server

$forceuser="";

use this user instead of that sent by drftp-server

$forcepass="";

use this password instead of that sent by drftp-server