Module Ftp_client

module Ftp_client: sig .. 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_error of exn

exception FTP_protocol_violation of string

type cmd_state = [ `Init
       | `Pass_acct_seq
       | `Perm_failure
       | `Preliminary
       | `Proto_error
       | `Rename_seq
       | `Restart_seq
       | `Success
       | `Temp_failure
       | `User_acct_seq
       | `User_pass_seq ] 

type port = [ `Active of string * int * Unix.file_descr
       | `Passive of string * int
       | `Unspecified ] 

type form_code = [ `ASA | `Non_print | `Telnet ] 

type representation = [ `ASCII of form_code option
       | `EBCDIC of form_code option
       | `Image ] 

type structure = [ `File_structure | `Record_structure ] 

type transmission_mode = [ `Block_mode | `Stream_mode ] 

type cmd = [ `ACCT of string
       | `ALLO of int * int option
       | `APPE of string * (ftp_state -> Ftp_data_endpoint.local_sender)
       | `CDUP
       | `CWD of string
       | `Connect
       | `DELE of string
       | `Dummy
       | `FEAT
       | `HELP of string option
       | `LIST of
           string option *
           (ftp_state -> Ftp_data_endpoint.local_receiver)
       | `MDTM of string
       | `MKD of string
       | `MODE of transmission_mode
       | `NLST of
           string option *
           (ftp_state -> Ftp_data_endpoint.local_receiver)
       | `NOOP
       | `OPTS of string * string option
       | `PASS of string
       | `PASV
       | `PORT
       | `PWD
       | `QUIT
       | `REIN
       | `REST of string
       | `RETR of
           string * (ftp_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 * (ftp_state -> Ftp_data_endpoint.local_sender)
       | `STOU of unit -> Ftp_data_endpoint.local_sender
       | `STRU of structure
       | `SYST
       | `TYPE of representation
       | `USER of string ] 

type reply = int * string 

class ftp_client_pi : ?event_system:Unixqueue.event_system -> ?onempty:ftp_state -> unit -> ?onclose:unit -> unit -> ?onerrorstate:exn -> unit -> ?onusererror:exn -> unit -> Unix.file_descr -> object .. end

module Action: sig .. end

class type ftp_method = object .. end

exception FTP_method_temp_failure of int * string

exception FTP_method_perm_failure of int * string

exception FTP_method_unexpected_reply of int * string

class connect_method : host:string -> ?port:int -> unit -> ftp_method

class login_method : user:string -> get_password:(unit -> string) -> get_account:(unit -> string) -> unit -> ftp_method

class walk_method : [ `Dir of string | `File of string | `Stay ] -> ftp_method

type filename = [ `NVFS of string | `Verbatim of string ] 

class get_method : file:filename -> representation:representation -> store:(ftp_state -> Ftp_data_endpoint.local_receiver) -> unit -> ftp_method

class invoke_method : command:cmd -> process_result:(ftp_state -> int * string -> unit) -> unit -> ftp_method

class set_structure_method : structure -> ftp_method

class set_mode_method : transmission_mode -> ftp_method

class rename_method : file_from:filename -> file_to:filename -> unit -> ftp_method

class mkdir_method : filename -> ftp_method

class rmdir_method : filename -> ftp_method

class delete_method : filename -> ftp_method

class list_method : dir:filename -> representation:representation -> store:(ftp_state -> Ftp_data_endpoint.local_receiver) -> unit -> ftp_method

class nlst_method : dir:filename -> representation:representation -> store:(ftp_state -> Ftp_data_endpoint.local_receiver) -> unit -> ftp_method

class mdtm_method : file:filename -> process_result:(float -> unit) -> unit -> ftp_method

class ftp_client : ?event_system:Unixqueue.event_system -> ?onempty:unit -> unit -> unit -> object .. end

Examples and Discussion

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.