diff options
author | Diego Nehab <diego@tecgraf.puc-rio.br> | 2004-06-15 06:24:00 +0000 |
---|---|---|
committer | Diego Nehab <diego@tecgraf.puc-rio.br> | 2004-06-15 06:24:00 +0000 |
commit | 58096449c6044b7aade5cd41cfd71c6bec1d273d (patch) | |
tree | 1814ffebe89c4c2556d84f97f66db37a7e8b4554 /doc/ftp.html | |
parent | 9ed7f955e5fc69af9bf1794fa2c8cd227981ba24 (diff) | |
download | luasocket-58096449c6044b7aade5cd41cfd71c6bec1d273d.tar.gz luasocket-58096449c6044b7aade5cd41cfd71c6bec1d273d.tar.bz2 luasocket-58096449c6044b7aade5cd41cfd71c6bec1d273d.zip |
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.
Diffstat (limited to 'doc/ftp.html')
-rw-r--r-- | doc/ftp.html | 272 |
1 files changed, 144 insertions, 128 deletions
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 @@ | |||
35 | 35 | ||
36 | <p> | 36 | <p> |
37 | FTP (File Transfer Protocol) is a protocol used to transfer files | 37 | FTP (File Transfer Protocol) is a protocol used to transfer files |
38 | between hosts. The module <tt>ftp.lua</tt> offers simple FTP support, | 38 | between hosts. The module <tt>ftp.lua</tt> offers simple FTP support. |
39 | allowing applications to download and upload files, and list directory | 39 | Applications can easily download and upload files. |
40 | contents. The implementation conforms to | 40 | The implementation conforms to |
41 | <a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>. | 41 | <a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>. |
42 | </p> | 42 | </p> |
43 | 43 | ||
@@ -49,175 +49,191 @@ URLs MUST conform to | |||
49 | 49 | ||
50 | <blockquote> | 50 | <blockquote> |
51 | <tt> | 51 | <tt> |
52 | [ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][<i>type</i>=a|i|d]</tt> | 52 | [ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][<i>type</i>=a|i]</tt> |
53 | </blockquote> | 53 | </blockquote> |
54 | 54 | ||
55 | <p> | ||
56 | High level functions are provided supporting the most common operations. | ||
57 | These high level functions are implemented on top of a lower level | ||
58 | interface. By using the low-level interface, users can easily create their | ||
59 | own functions to access <em>any</em> operation supported by the FTP | ||
60 | protocol. For that, check the implementation. | ||
61 | </p> | ||
62 | |||
63 | <p> | ||
64 | To use some of the functions in this module, a good understanding of | ||
65 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> | ||
66 | LTN012, Filters sources and sinks</a> is necessary. | ||
67 | </p> | ||
68 | |||
69 | <p> | ||
70 | The following constants can be set to control the default behaviour of | ||
71 | the FTP module: | ||
72 | </p> | ||
73 | |||
74 | <ul> | ||
75 | <li> <tt>PASSWORD</tt>: default anonymous password. | ||
76 | <li> <tt>PORT</tt>: default port used for the control connection; | ||
77 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; | ||
78 | <li> <tt>USER</tt>: default anonymous user; | ||
79 | </ul> | ||
80 | |||
55 | <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 81 | <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
56 | 82 | ||
57 | <p class=name id=get> | 83 | <p class=name id=get> |
58 | socket.ftp.<b>get(</b>url<b>)</b><br> | 84 | ftp.<b>get(</b>url<b>)</b><br> |
59 | socket.ftp.<b>get{</b><br> | 85 | ftp.<b>get{</b><br> |
60 | url = <i>string</i>,<br> | 86 | host = <i>string</i>,<br> |
61 | type = <i>string</i>,<br> | 87 | sink = <i>LTN12 sink</i>,<br> |
62 | user = <i>string</i>,<br> | 88 | argument <i>or</i> path = <i>string</i>,<br> |
63 | password = <i>string</i><br> | 89 | [user = <i>string</i>,]<br> |
90 | [password = <i>string</i>]<br> | ||
91 | [command = <i>string</i>,]<br> | ||
92 | [port = <i>number</i>,]<br> | ||
93 | [type = <i>string</i>,]<br> | ||
94 | [step = <i>LTN12 pump step</i>],<br> | ||
64 | <b>}</b> | 95 | <b>}</b> |
65 | </p> | 96 | </p> |
66 | 97 | ||
67 | <p class=description> | 98 | <p class=description> |
68 | Downloads an URL from a FTP server. | 99 | The <tt>get</tt> function has two forms. The simple form has fixed |
100 | functionality: it downloads the contents of a URL and returns it as a | ||
101 | string. The generic form allows a <em>lot</em> more control, as explained | ||
102 | below. | ||
69 | </p> | 103 | </p> |
70 | 104 | ||
71 | <p class=parameters> | 105 | <p class=parameters> |
72 | The function can be called either directly with a <tt>url</tt> | 106 | If the argument of the <tt>get</tt> function is a table, the function |
73 | or with a <em>request table</em>. | 107 | expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of |
74 | Fields passed explicitly in the request table override those | 108 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes |
75 | present in the <tt>url</tt>. | 109 | precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is |
76 | </p> | 110 | the LTN12 sink that will receive the downloaded data. <tt>Argument</tt> or |
77 | 111 | <tt>path</tt> give the target path to the resource in the server. The | |
78 | <p class=parameters> | 112 | optional arguments are the following: |
79 | The parameter <tt>type</tt> accepts values '<tt>a</tt>' (ASCII, the | ||
80 | default), '<tt>i</tt>' (binary) or '<tt>d</tt>' (directory listing) and | ||
81 | determines the transfer type. If <tt><path></tt> ends with a | ||
82 | '<tt>/</tt>' or <tt>type</tt> is '<tt>d</tt>', a directory listing of | ||
83 | <tt><path></tt> is returned. If no <tt>user</tt> is provided in the | ||
84 | <tt>url</tt> or explicitly, the function tries to log in as user | ||
85 | '<tt>anonymous</tt>'. | ||
86 | </p> | 113 | </p> |
114 | <ul> | ||
115 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for | ||
116 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; | ||
117 | <li><tt>command</tt>: The FTP command used to obtain data. Defaults to | ||
118 | "<tt>retr</tt>", but see example below; | ||
119 | <li><tt>port</tt>: The port to contacct the server at. Defaults to 21; | ||
120 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or | ||
121 | "<tt>a</tt>". Defaults to whatever is the server default; | ||
122 | <li><tt>step</tt>: LTN12 pump step function used to pass data from the | ||
123 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function. | ||
124 | </ul> | ||
87 | 125 | ||
88 | <p class=return> | 126 | <p class=return> |
89 | If successful, the function returns | 127 | If successful, the simple version returns the URL contents as a |
90 | the file content as a string. In case of error, the function returns | 128 | string, and the generic function returns 1. In case of error, both |
91 | <b><tt>nil</tt></b> and an error message describing the error. | 129 | functions return <b><tt>nil</tt></b> and an error message describing the |
130 | error. | ||
92 | </p> | 131 | </p> |
93 | 132 | ||
94 | <pre class=example> | 133 | <pre class=example> |
95 | -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", | 134 | -- load the ftp support |
96 | -- go to directory "pub/lua" and get file "lua.tar.gz" as binary. | 135 | local ftp = require("ftp") |
97 | f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") | ||
98 | 136 | ||
99 | -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", | 137 | -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br", |
100 | -- go to director "pub" and retrieve directory listing of directory "lua" | 138 | -- and get file "lua.tar.gz" from directory "pub/lua" as binary. |
101 | f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d") | 139 | f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") |
102 | |||
103 | -- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br", | ||
104 | -- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe" | ||
105 | -- (actually, fails because of wrong password, of course) | ||
106 | f, e = socket.ftp.get{ | ||
107 | url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe", | ||
108 | user = "diego", | ||
109 | password = "nehab", | ||
110 | type = "i" | ||
111 | } | ||
112 | -- f returns nil, and e returns an appropriate error message | ||
113 | </pre> | 140 | </pre> |
114 | 141 | ||
115 | <!-- get_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 142 | <pre class=example> |
116 | 143 | -- load needed modules | |
117 | <p class=name id=get_cb> | 144 | local ftp = require("ftp") |
118 | socket.ftp.<b>get_cb{</b><br> | 145 | local ltn12 = require("ltn12") |
119 | url = <i>string</i>,<br> | 146 | local url = require("url") |
120 | type = <i>string</i>,<br> | 147 | |
121 | content_cb = <i>receive-callback</i>,<br> | 148 | -- a function that returns a directory listing |
122 | user = <i>string</i>,<br> | 149 | function ls(u) |
123 | password = <i>string</i><br> | 150 | local t = {} |
124 | <b>}</b> | 151 | local p = url.parse(u) |
125 | </p> | 152 | p.command = "nlst" |
126 | 153 | p.sink = ltn12.sink.table(t) | |
127 | <p class=description> | 154 | local r, e = ftp.get(p) |
128 | Same as <a href="#get"><tt>get</tt></a>, but the library returns | 155 | return r and table.concat(t), e |
129 | the content of the downloaded file to the receive callback | 156 | end |
130 | <tt>content_cb</tt>. | 157 | </pre> |
131 | </p> | ||
132 | |||
133 | <p class=note> | ||
134 | Note: for more information on callbacks, refer to | ||
135 | <a href="stream.html#stream">Streaming with callbacks</a>. | ||
136 | </p> | ||
137 | 158 | ||
138 | <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 159 | <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
139 | 160 | ||
140 | <p class=name id=put> | 161 | <p class=name id=put> |
141 | socket.ftp.<b>put(</b>url, content<b>)</b><br> | 162 | ftp.<b>put(</b>url, content<b>)</b><br> |
142 | socket.ftp.<b>put{</b><br> | 163 | ftp.<b>put{</b><br> |
143 | url = <i>string</i>,<br> | 164 | host = <i>string</i>,<br> |
144 | content = <i>string</i>,<br> | 165 | source = <i>LTN12 sink</i>,<br> |
145 | type = <i>string</i>,<br> | 166 | argument <i>or</i> path = <i>string</i>,<br> |
146 | user = <i>string</i>,<br> | 167 | [user = <i>string</i>,]<br> |
147 | password = <i>string</i><br> | 168 | [password = <i>string</i>]<br> |
169 | [command = <i>string</i>,]<br> | ||
170 | [port = <i>number</i>,]<br> | ||
171 | [type = <i>string</i>,]<br> | ||
172 | [step = <i>LTN12 pump step</i>],<br> | ||
148 | <b>}</b> | 173 | <b>}</b> |
149 | </p> | 174 | </p> |
150 | 175 | ||
151 | <p class=description> | 176 | <p class=description> |
152 | Upload a file to a FTP server. | 177 | The <tt>put</tt> function has two forms. The simple form has fixed |
178 | functionality: it uploads a string of content into a URL. The generic form | ||
179 | allows a <em>lot</em> more control, as explained below. | ||
153 | </p> | 180 | </p> |
154 | 181 | ||
155 | <p class=parameters> | 182 | <p class=parameters> |
156 | The function can be called directly with a | 183 | If the argument of the <tt>put</tt> function is a table, the function |
157 | <tt>url</tt> and <tt>content</tt> parameters, or with a | 184 | expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of |
158 | <em>request table</em>. | 185 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes |
159 | Values passed explicitly in the request table override those present in | 186 | precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is |
160 | the <tt>url</tt>. The parameter <tt>type</tt> accept values | 187 | the LTN12 source that will provide the contents to be uploaded. |
161 | '<tt>a</tt>' (ASCII, the default) or '<tt>i</tt>' (binary) and | 188 | <tt>Argument</tt> or |
162 | determines the transfer type. If no <tt>user</tt> is provided, the | 189 | <tt>path</tt> give the target path to the resource in the server. The |
163 | function tries to log in as '<tt>anonymous</tt>'. | 190 | optional arguments are the following: |
164 | </p> | 191 | </p> |
192 | <ul> | ||
193 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for | ||
194 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; | ||
195 | <li><tt>command</tt>: The FTP command used to obtain data. Defaults to | ||
196 | "<tt>retr</tt>", but see example below; | ||
197 | <li><tt>port</tt>: The port to contacct the server at. Defaults to 21; | ||
198 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or | ||
199 | "<tt>a</tt>". Defaults to whatever is the server default; | ||
200 | <li><tt>step</tt>: LTN12 pump step function used to pass data from the | ||
201 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function. | ||
202 | </ul> | ||
165 | 203 | ||
166 | <p class=return> | 204 | <p class=return> |
167 | If successful, the function returns 1. In case of error, the | 205 | Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error |
168 | function returns <b><tt>nil</tt></b> followed by a string describing the error. | 206 | message describing the reason for failure. |
169 | </p> | 207 | </p> |
170 | 208 | ||
171 | <pre class=example> | 209 | <pre class=example> |
172 | -- Log as user "anonymous" on server "ftp.free.org" and store file | 210 | -- load the ftp support |
173 | -- "hello" with contents "hello world!", using binary mode for the transfer | 211 | local ftp = require("ftp") |
174 | r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n") | ||
175 | |||
176 | -- Does exactly the same, but logging in as diego | ||
177 | r, e = socket.ftp.put{ | ||
178 | url = "ftp://ftp.free.org/hello", | ||
179 | type = "i", | ||
180 | user = "diego", | ||
181 | password = "nehab", | ||
182 | content = "hello world\n" | ||
183 | } | ||
184 | </pre> | ||
185 | </blockquote> | ||
186 | |||
187 | <!-- put_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
188 | |||
189 | <p class=name id=put_cb> | ||
190 | socket.ftp.<b>put_cb{</b><br> | ||
191 | url = <i>string</i>,<br> | ||
192 | type = <i>string</i>,<br> | ||
193 | content_cb = <i>send-callback</i>,<br> | ||
194 | user = <i>string</i>,<br> | ||
195 | password = <i>string</i><br> | ||
196 | <b>}</b> | ||
197 | </p> | ||
198 | |||
199 | <p class=description> | ||
200 | Same as <a href="#put"><tt>put</tt></a>, but the | ||
201 | library obtains the contents of the file to be uploaded using the send | ||
202 | callback <tt>content_cb</tt>. | ||
203 | </p> | ||
204 | 212 | ||
205 | <p class=note> | 213 | -- Log as user "diego" on server "ftp.tecgraf.puc-rio.br", |
206 | Note: for more information on callbacks, refer to | 214 | -- using password "nehab", and store a file "README" with contents |
207 | <a href="stream.html#stream">Streaming with callbacks</a>. | 215 | -- "wrong password, of course" |
208 | </p> | 216 | f, e = ftp.put("ftp://diego:nehab@ftp.tecgraf.puc-rio.br/README", "wrong password, of course") |
217 | </pre> | ||
209 | 218 | ||
210 | <pre class=example> | 219 | <pre class=example> |
211 | -- Log as user "anonymous" on server "ftp.free.org" and store file | 220 | -- load the ftp support |
212 | -- "hello" with contents of the same file in the current directory, | 221 | local ftp = require("ftp") |
213 | -- using binary mode for the transfer | 222 | local ltn12 = require("ltn12") |
214 | r, e = socket.ftp.put_cb{ | 223 | |
215 | url = "ftp://ftp.free.org/hello", | 224 | -- Log as user "diego" on server "ftp.tecgraf.puc-rio.br", |
216 | type = "i", | 225 | -- using password "nehab", and append to the file "LOG", sending the |
217 | content_cb = socket.callback.send_file(io.open("hello", "r")) | 226 | -- contents of a local file |
227 | f, e = ftp.put{ | ||
228 | host = "ftp.tecgraf.puc-rio.br", | ||
229 | user = "diego", | ||
230 | password = "nehab", | ||
231 | command = "appe", | ||
232 | argument = "LOG", | ||
233 | source = ltn12.source.file(io.open("LOCAL-LOG", "r")) | ||
218 | } | 234 | } |
219 | </pre> | 235 | </pre> |
220 | </blockquote> | 236 | |
221 | 237 | ||
222 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 238 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
223 | 239 | ||