module Ftp_client:FTP clientsig
..end
Warning: Experimental code! Not all features described in this interface work as described!
The client is currently only partially implemented. Especially, the STOR and STOU commands are missing. Only IPv4 is supported.
It is intended to implement a large subset of RFC 959 (and later,
the newer FTP-related RFCs). This includes support for EBCDIC,
record files, and block mode.
exception FTP_protocol_error of exn
exception FTP_protocol_violation of string
typecmd_state =
[ `Failure
| `Init
| `Pass_acct_seq
| `Preliminary
| `Proto_error
| `Rename_seq
| `Restart_seq
| `Success
| `User_acct_seq
| `User_pass_seq ]
`Init
: Just connected, no greeting message arrived yet`Success
: Got the greeting message/last command was successful`Proto_error
: currently unused`Failure
: Last command was not successful`Rename_seq
: Used instead of `Success
after the RNFR command`Restart_seq
: Used instead of `Success
after the REST command`User_pass_seq
: Used instead of `Success
after the USER command
when a password must be typed in`User_acct_seq
: Used instead of `Success
after the USER command
when an account ID must be typed in`Pass_acct_seq
: Used instead of `Success
after the PASS command
when an account iD must be typed in`Preliminary
: a reply with code 100 to 199. There will be another
final reply for the commandtypeport =
[ `Active of string * int * Unix.file_descr
| `Passive of string * int
| `Unspecified ]
`Active
means that the server
initiates the data connection to the listening client, and in the
case of `Passive
the client initiates the data connection to the
listening server. The string argument is the IP address as dotted
quad, the int argument is the port number, and the descriptor
is the listening master socket.typeform_code =
[ `ASA | `Non_print | `Telnet ]
form_code
has a meaning when FTP is used to print files:`Non_print
: This is not the case.`Telnet
: Telnet control codes are used for vertical movement`ASA
: ASA (Fortran) control codes are used for vertical movementtyperepresentation =
[ `ASCII of form_code option
| `EBCDIC of form_code option
| `Image ]
`ASCII
: An ASCII variant is used, i.e. the server sends files in
ASCII encoding with CR/LF as end-of-line marker. Supported by all
servers.`EBCDIC
: An EBCDIC variant is used, i.e. the server sends files in
EBCDIC encoding with NEL as end-of-line marker`Image
: The file is transferred in its original binary
representation. Supported by all servers.
This FTP client does not recode the files such that they match the
selected representation. When files are downloaded, they are stored
as they are received. When files are uploaded, they are sent as they
are. The user of this client must do recodings when necessary
(the class Ftp_data_endpoint.data_converter
may be useful for this).
If no representation is selected, FTP servers assume `ASCII None
as default.
typestructure =
[ `File_structure | `Record_structure ]
`File_structure
: Files are simply contiguous streams of bytes`Record_structure
: Files are sequences of records. FTP does
not make a difference between variable and fixed length records.
It is not forbidden that the records are themselves structured
into lines, in fact it can happen that end-of-line markers are
contained in binary records. Operating systems that support
record-structured files often store text files in this format, i.e.
every line is stored in its own record, without end-of-line marker.
If record structure is selected by a STRU command, it is recommended
to use the classes Ftp_data_endpoint.out_record_channel
and
Ftp_data_endpoint.in_record_channel
for the local representation
of the files, otherwise the records may be incorrectly mapped
to the local conventions.
If no structure is selected, FTP servers will assume file structure
as default.
typetransmission_mode =
[ `Block_mode | `Stream_mode ]
`Stream_mode
: This is the simple format that is responsible for
all the failed FTP downloads. It is supported by all FTP servers,
actually, you cannot assume a better transmission mode from an
unknown FTP server. It is unreliable because it cannot distinguish
between a transmission failure and the regular end-of-file condition.`Block_mode
: This is an improved format using frames to protect
the transmitted data. Unfortunately, almost no FTP server supports
it.type
state = {
|
cmd_state : |
(* | the command state | *) |
|
ftp_connected : |
(* | whether connected with the server | *) |
|
ftp_data_conn : |
(* | whether there is a clean data conn | *) |
|
ftp_user : |
(* | successfully sent user identifier | *) |
|
ftp_password : |
(* | successfully sent password | *) |
|
ftp_account : |
(* | successfully sent account identifier | *) |
|
ftp_logged_in : |
(* | whether the user is logged in | *) |
|
ftp_port : |
(* | the selected port | *) |
|
ftp_repr : |
(* | the selected representation | *) |
|
ftp_structure : |
(* | the selected structure | *) |
|
ftp_trans : |
(* | the selected trans mode | *) |
|
ftp_dir : |
(* | The current directory, expressed as list of CWD changes minus CDUP changes. This is only reasonable if CWD does not include slashes. The list is in reverse order, i.e. deepest directory first. | *) |
typecmd =
[ `ACCT of string
| `ALLO of int * int option
| `APPE of string * (state -> Ftp_data_endpoint.local_sender)
| `CDUP
| `CWD of string
| `Connect
| `DELE of string
| `HELP of string option
| `LIST of
string option * (state -> Ftp_data_endpoint.local_receiver)
| `MKD of string
| `MODE of transmission_mode
| `NLST of
string option * (state -> Ftp_data_endpoint.local_receiver)
| `NOOP
| `PASS of string
| `PASV
| `PORT
| `PWD
| `QUIT
| `REIN
| `REST of string
| `RETR of string * (state -> Ftp_data_endpoint.local_receiver)
| `RMD of string
| `RNFR of string
| `RNTO of string
| `SITE of string
| `SMNT of string
| `STAT of string option
| `STOR of string * (state -> Ftp_data_endpoint.local_sender)
| `STOU of unit -> Ftp_data_endpoint.local_sender
| `STRU of structure
| `SYST
| `TYPE of representation
| `USER of string ]
typereply =
int * string
class ftp_client_pi :?event_system:Unixqueue.event_system -> ?onempty:state -> unit -> ?onclose:unit -> unit -> Unix.file_descr ->
object
..end
class type ftp_method =object
..end
ftp_method
is a small procedure doing some task
exception FTP_method_failure of int * string
This does not work yet as intended!
class connect_method :host:string -> ?port:int -> unit ->
ftp_method
host
which must be an IP address
class login_method :user:string -> get_password:(unit -> string) -> get_account:(unit -> string) -> unit ->
ftp_method
user
in.
class get_method :file:string -> representation:representation -> store:(state -> Ftp_data_endpoint.local_receiver) -> unit ->
ftp_method
file
from
the server.
class ftp_client :?event_system:Unixqueue.event_system -> ?onempty:unit -> unit -> unit ->
object
..end
To download a single flat file from a server:
let buffer = Buffer.create 1000 in
let ch = new Netchannels.output_buffer buffer in
let client = new ftp_client() in
client # add (new connect_method ~host:"127.0.0.1");
client # add (new login_method ~user:"foo"
~get_password:(fun () -> "password")
~get_account:(fun () -> "foo") ());
client # add (new get_method ~file:"path/to/file"
~representation:`Image
~store:(fun _ -> `File_structure ch) ());
client # run()
The file is stored in buffer
. By using a different netchannel, it
can be stored whereever wanted.
This piece of code has the disadvantage that the client does not stop when a method fails (in the current version, it always stops, but in a disadvantegous manner - this will be changed). Because of this, it is better to execute the next method only when the previous was successful:
...
client # add ~onsuccess:(fun () ->
client # add ~onsuccess:...
(new login_method
~user:"foo"
~get_password:(fun () -> "password")
~get_account:(fun () -> "foo") ());
)
(new connect_method ~host:"127.0.0.1")
Alternatively, one can also force that the execution stops by raising
an exception in the onerror
callback (not implemented in the current
version).
To download a record-structured text file, use a store
like:
let ch = (as above) in
let rec_ch = new Ftp_data_endpoint.write_out_record_channel
~repr:(`ASCII_unix `Enc_iso88591)
ch
...
... ~store:(fun _ -> `Record_structure rec_ch)
Here, the end-of-record is transcoded to newline. Note that the ASCII
variant (`Enc_iso88591
) is ignored by write_out_record_channel
.
Open: How to select record structure using an FTP method.
Character conversions: To convert an EBCDIC file to ASCII, use something like
let ch = (as above) in
let converter = new Ftp_data_endpoint.data_converter
~fromrepr:(`EBCDIC `Enc_cp1047)
~torepr:(`ASCII_unix `Enc_iso88591) in
let ch_ebcdic = new Netchannels.output_filter converter ch in
...
... ~representation:(`EBCDIC None)
... ~store:(fun _ -> `File_structure ch_ebcdic)
The class data_converter
also performs the transformation of the
end-of-line convention, unlike the similar class
Netconversion.conversion_pipe
.