module Ftp_client:sig
..end
Currently implements:
Uq_engines
).
The interface of this module was changed in Ocamlnet-3.3. Before this
release, the module was marked as "experimental". This is no longer
the case, as the interface has been updated, and the missing features
have been added (e.g. STOR
support).
exception FTP_error of exn
exception FTP_protocol_violation of string
exception FTP_timeout of string
typecmd_state =
[ `Init
| `Not_connected
| `Pass_acct_seq
| `Perm_failure
| `Preliminary
| `Proto_error
| `Rename_seq
| `Restart_seq
| `Success
| `Temp_failure
| `User_acct_seq
| `User_pass_seq ]
`Not_connected
: Not connected.`Init
: Just connected, no greeting message arrived yet`Success
: Got the greeting message/last command was successful`Proto_error
: currently unused`Temp_failure
: Last command was not successful, and the code
was between 400 and 499`Perm_failure
: Last command was not successful, and the code
was between 500 and 599`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
| `Ext_active of string * int * Unix.file_descr
| `Ext_passive of int
| `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
ftp_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. | *) |
|
ftp_features : |
(* | The list of features returned by the last FEAT command.
None means that no FEAT command was yet tried.
Some [] means that there are no features (either FEAT
returned an empty list, or the FEAT command is not implemented
by the server). Otherwise the list enumerates pairs
(label,param) where label is the case-sensitive feature
label and param the optional parameter. There is no
defined order for the list of features. | *) |
|
ftp_options : |
(* | Remembers the OPTS commands sent to the server. The list
enumerates pairs (command,optionparam) , where command
is the uppercase command name the option refers to. Only
the last negotiated optionparam for the command is remembered. | *) |
typecmd =
[ `ACCT of string
| `ALLO of int * int option
| `APPE of string * (ftp_state -> Ftp_data_endpoint.local_sender)
| `CDUP
| `CWD of string
| `Connect of string * int
| `DELE of string
| `Disconnect
| `Dummy
| `EPRT
| `EPSV of [ `AF of Unix.socket_domain | `ALL ] option
| `FEAT
| `HELP of string option
| `LANG of string option
| `LIST of
string option *
(ftp_state -> Ftp_data_endpoint.local_receiver)
| `MDTM of string
| `MKD of string
| `MLSD of
string option *
(ftp_state -> Ftp_data_endpoint.local_receiver)
| `MLST of string option
| `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
| `SIZE of string
| `SMNT of string
| `STAT of string option
| `STOR of string * (ftp_state -> Ftp_data_endpoint.local_sender)
| `STOU of ftp_state -> Ftp_data_endpoint.local_sender
| `STRU of structure
| `SYST
| `TYPE of representation
| `USER of string ]
typereply =
int * string
class type ftp_client_pi =object
..end
typeftp_method =
ftp_client_pi -> unit Uq_engines.engine
ftp_method
is a small procedure doing some taskexception FTP_method_temp_failure of int * string
exception FTP_method_perm_failure of int * string
exception FTP_method_unexpected_reply of int * string
val connect_method : host:string -> ?port:int -> unit -> ftp_method
host
val login_method : user:string ->
get_password:(unit -> string) ->
get_account:(unit -> string) -> unit -> ftp_method
user
in. get_password
is called when
the FTP server asks for the password (may be skipped). get_account
is called when the server asks for the account ID (may be skipped).val quit_method : unit -> ftp_method
val walk_method : [ `Dir of string | `File of string | `Stay ] -> ftp_method
`File name
: The name
is interpreted as slash-separated path.
It is always interpreted relative to the home directory of the
user (i.e. the directory after login), even if it begins with a
slash. The FTP command walks to the directory containing name
.`Dir name
: The FTP command walks to the directory name
(same
syntax as for `File
).`Stay
: The FTP command does nothing (stays in the current directory).typefilename =
[ `NVFS of string | `TVFS of string | `Verbatim of string ]
`NVFS name
: The "Network Virtual File System" is the normal way
of accessing FTP files. The client walks into the directory containing
the file using CWD
and CDUP
commands, and calls the file operation
from this directory. For simplicity, this client interprets slashes
in name
as path component separators. The FTP server will never
see these slashes.`TVFS name
: The optional "Trivial Network File System" avoids the
CWD
and CDUP
commands. The tagged name
is normalized (double
slashed removed etc.), and is passed to the server as-is. Before using
the faster TVFS one should check whether it is supported (feature
"TVFS"). Note that even for TVFS there are no special files "."
and ".."!`Verbatim name
: The string name
is passed to the server without
transforming it in any way.val get_method : file:filename ->
representation:representation ->
store:(ftp_state -> Ftp_data_endpoint.local_receiver) ->
unit -> ftp_method
file
from
the server. The file is stored in the local_receiver
that can be
obtained by calling the store
function. The selected representation
remains unchanged.val put_method : ?meth:[ `APPE | `STOR ] ->
file:filename ->
representation:representation ->
store:(ftp_state -> Ftp_data_endpoint.local_sender) ->
unit -> ftp_method
file
to
the server. The file is taken from the local_sender
that can be
obtained by calling the store
function. The selected representation
remains unchanged.
meth
selects the method to use (default `STOR
).
val invoke_method : command:cmd -> unit -> ftp_method
command
.val set_structure_method : structure -> ftp_method
val set_mode_method : transmission_mode -> ftp_method
val rename_method : file_from:filename ->
file_to:filename -> unit -> ftp_method
file_from
into file_to
.
Both file names must be of the same type, either `NVFS
or `Verbatim
.
If `NVFS
, both names must be in the same directory.
val mkdir_method : filename -> ftp_method
val rmdir_method : filename -> ftp_method
val delete_method : filename -> ftp_method
val list_method : dir:filename ->
representation:representation ->
store:(ftp_state -> Ftp_data_endpoint.local_receiver) ->
unit -> ftp_method
dir
using the LIST command.
The representation
must not be `Image
.val nlst_method : dir:filename ->
representation:representation ->
store:(ftp_state -> Ftp_data_endpoint.local_receiver) ->
unit -> ftp_method
dir
using the NLST command
The representation
must not be `Image
.val parse_nlst_document : string -> string list
`NLST
val mdtm_method : file:filename ->
process_result:(float -> unit) -> unit -> ftp_method
file
.
On success, process_result
is called.val size_method : file:filename ->
representation:representation ->
process_result:(int64 -> unit) -> unit -> ftp_method
file
. On success, process_result
is called.
The size depends on representation
.val feat_method : ?process_result:((string * string option) list -> unit) ->
unit -> ftp_method
Ftp_client.ftp_state.ftp_features
)typeentry =
string * (string * string) list
(name, facts)
. The facts are given as pairs
(factname,value)
where factname
is always lowercase.
For parsers for common facts see below.val mlst_method : file:filename ->
process_result:(entry list -> unit) ->
unit -> ftp_method
file
.val mlsd_method : dir:filename ->
store:(ftp_state -> Ftp_data_endpoint.local_receiver) ->
unit -> ftp_method
val parse_mlsd_document : string -> entry list
`MLSD
typeentry_type =
[ `Cdir | `Dir | `File | `Other | `Pdir ]
`File
: entry refers to file`Cdir
: entry refers to the directory being listed`Pdir
: entry is a parent of the directory being listed`Dir
: entry refers to directory`Other
: entry is neither file nor directorytypeentry_perm =
[ `Append
| `Create
| `Delete
| `Delete_member
| `Enter
| `List
| `Mkdir
| `Read
| `Rename
| `Write ]
`Append
: append to file possible`Create
: file can be created in this dir`Delete
: file or dir can be deleted`Enter
: dir can be entered`Rename
: file or dir can be renamed`List
: dir can be listed`Mkdir
: subdir can be created in this dir`Delete_member
: a file or dir can be deleted in this directory`Read
: a file can be retrieved`Write
: a file can be storedNot_found
.val get_name : entry -> string
val get_size : entry -> int64
val get_modify : entry -> float
val get_create : entry -> float
val get_type : entry -> entry_type
val get_unique : entry -> string
val get_perm : entry -> entry_perm list
val get_lang : entry -> string
val get_media_type : entry -> string
val get_charset : entry -> string
val get_unix_mode : entry -> int
val get_unix_uid : entry -> string
val get_unix_gid : entry -> string
class ftp_client :?event_system:Unixqueue.event_system -> 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 # exec (connect_method ~host:"127.0.0.1" ());
client # exec (login_method ~user:"foo"
~get_password:(fun () -> "password")
~get_account:(fun () -> "foo") ());
client # exec (get_method ~file:(`NVFS "path/to/file")
~representation:`Image
~store:(fun _ -> `File_structure ch) ());
The file is stored in buffer
. By using a different netchannel, it
can be stored whereever wanted.
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
.
module Debug:sig
..end