From 58096449c6044b7aade5cd41cfd71c6bec1d273d Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Tue, 15 Jun 2004 06:24:00 +0000 Subject: Manual is almost done. HTTP is missing. Implemented new distribution scheme. Select is now purely C. HTTP reimplemented seems faster dunno why. LTN12 functions that coroutines fail gracefully. --- doc/ftp.html | 272 +++++++++++++++++++++++++++++++---------------------------- 1 file changed, 144 insertions(+), 128 deletions(-) (limited to 'doc/ftp.html') diff --git a/doc/ftp.html b/doc/ftp.html index 6776a17..a0c9268 100644 --- a/doc/ftp.html +++ b/doc/ftp.html @@ -35,9 +35,9 @@

FTP (File Transfer Protocol) is a protocol used to transfer files -between hosts. The module ftp.lua offers simple FTP support, -allowing applications to download and upload files, and list directory -contents. The implementation conforms to +between hosts. The module ftp.lua offers simple FTP support. +Applications can easily download and upload files. +The implementation conforms to RFC 959.

@@ -49,175 +49,191 @@ URLs MUST conform to
-[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i|d] +[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i]
+

+High level functions are provided supporting the most common operations. +These high level functions are implemented on top of a lower level +interface. By using the low-level interface, users can easily create their +own functions to access any operation supported by the FTP +protocol. For that, check the implementation. +

+ +

+To use some of the functions in this module, a good understanding of + +LTN012, Filters sources and sinks is necessary. +

+ +

+The following constants can be set to control the default behaviour of +the FTP module: +

+ + +

-socket.ftp.get(url)
-socket.ftp.get{
-  url = string,
-  type = string,
-  user = string,
-  password = string
+ftp.get(url)
+ftp.get{
+  host = string,
+  sink = LTN12 sink,
+  argument or path = string,
+  [user = string,]
+  [password = string]
+  [command = string,]
+  [port = number,]
+  [type = string,]
+  [step = LTN12 pump step],
}

-Downloads an URL from a FTP server. +The get function has two forms. The simple form has fixed +functionality: it downloads the contents of a URL and returns it as a +string. The generic form allows a lot more control, as explained +below.

-The function can be called either directly with a url -or with a request table. -Fields passed explicitly in the request table override those -present in the url. -

- -

-The parameter type accepts values 'a' (ASCII, the -default), 'i' (binary) or 'd' (directory listing) and -determines the transfer type. If <path> ends with a -'/' or type is 'd', a directory listing of -<path> is returned. If no user is provided in the -url or explicitly, the function tries to log in as user -'anonymous'. +If the argument of the get function is a table, the function +expects at least the fields host, sink, and one of +argument or path (argument takes +precedence). Host is the server to connect to. Sink is +the LTN12 sink that will receive the downloaded data. Argument or +path give the target path to the resource in the server. The +optional arguments are the following:

+

-If successful, the function returns -the file content as a string. In case of error, the function returns -nil and an error message describing the error. +If successful, the simple version returns the URL contents as a +string, and the generic function returns 1. In case of error, both +functions return nil and an error message describing the +error. 

--- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
--- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
-f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
+-- load the ftp support
+local ftp = require("ftp")
 
 -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
--- go to director "pub" and retrieve directory listing of directory "lua"
-f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d")
-
--- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br",
--- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe"
--- (actually, fails because of wrong password, of course)
-f, e = socket.ftp.get{
-  url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe",
-  user = "diego",
-  password = "nehab",
-  type = "i"
-}
--- f returns nil, and e returns an appropriate error message
+-- and get file "lua.tar.gz" from directory "pub/lua" as binary.
+f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
- - -

-socket.ftp.get_cb{
-  url = string,
-  type = string,
-  content_cb = receive-callback,
-  user = string,
-  password = string
-} -

- -

-Same as get, but the library returns -the content of the downloaded file to the receive callback -content_cb. -

- -

-Note: for more information on callbacks, refer to -Streaming with callbacks. -

+
+-- load needed modules
+local ftp = require("ftp")
+local ltn12 = require("ltn12")
+local url = require("url")
+
+-- a function that returns a directory listing
+function ls(u)
+    local t = {}
+    local p = url.parse(u)
+    p.command = "nlst"
+    p.sink = ltn12.sink.table(t)
+    local r, e = ftp.get(p)
+    return r and table.concat(t), e
+end
+

-socket.ftp.put(url, content)
-socket.ftp.put{
-  url = string,
-  content = string,
-  type = string,
-  user = string,
-  password = string
+ftp.put(url, content)
+ftp.put{
+  host = string,
+  source = LTN12 sink,
+  argument or path = string,
+  [user = string,]
+  [password = string]
+  [command = string,]
+  [port = number,]
+  [type = string,]
+  [step = LTN12 pump step],
}

-Upload a file to a FTP server. +The put function has two forms. The simple form has fixed +functionality: it uploads a string of content into a URL. The generic form +allows a lot more control, as explained below.

-The function can be called directly with a -url and content parameters, or with a -request table. -Values passed explicitly in the request table override those present in -the url. The parameter type accept values -'a' (ASCII, the default) or 'i' (binary) and -determines the transfer type. If no user is provided, the -function tries to log in as 'anonymous'. +If the argument of the put function is a table, the function +expects at least the fields host, source, and one of +argument or path (argument takes +precedence). Host is the server to connect to. Source is +the LTN12 source that will provide the contents to be uploaded. +Argument or +path give the target path to the resource in the server. The +optional arguments are the following:

+

-If successful, the function returns 1. In case of error, the -function returns nil followed by a string describing the error. +Both functions return 1 if successful, or nil and an error +message describing the reason for failure. 

--- Log as user "anonymous" on server "ftp.free.org" and store file
--- "hello" with contents "hello world!", using binary mode for the transfer
-r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n")
-
--- Does exactly the same, but logging in as diego
-r, e = socket.ftp.put{
-  url = "ftp://ftp.free.org/hello",
-  type = "i",
-  user = "diego",
-  password = "nehab",
-  content = "hello world\n"
-}
-
- - - - -

-socket.ftp.put_cb{
-  url = string,
-  type = string,
-  content_cb = send-callback,
-  user = string,
-  password = string
-} -

- -

-Same as put, but the -library obtains the contents of the file to be uploaded using the send -callback content_cb. -

+-- load the ftp support +local ftp = require("ftp") -

-Note: for more information on callbacks, refer to -Streaming with callbacks. -

+-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br", +-- using password "nehab", and store a file "README" with contents +-- "wrong password, of course" +f, e = ftp.put("ftp://diego:nehab@ftp.tecgraf.puc-rio.br/README", "wrong password, of course") + 
--- Log as user "anonymous" on server "ftp.free.org" and store file
--- "hello" with contents of the same file in the current directory, 
--- using binary mode for the transfer
-r, e = socket.ftp.put_cb{
-  url = "ftp://ftp.free.org/hello",
-  type = "i",
-  content_cb = socket.callback.send_file(io.open("hello", "r"))
+-- load the ftp support
+local ftp = require("ftp")
+local ltn12 = require("ltn12")
+
+-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
+-- using password "nehab", and append to the file "LOG", sending the
+-- contents of a local file 
+f, e = ftp.put{
+  host = "ftp.tecgraf.puc-rio.br", 
+  user = "diego",
+  password = "nehab",
+  command = "appe",
+  argument = "LOG",
+  source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
 }
- + -- cgit v1.2.3-55-g6feb