Mercurial > luasocket

comparison doc/ftp.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4
5 <head>
6 <meta name="description" content="LuaSocket: FTP support">
7 <meta name="keywords" content="Lua, LuaSocket, FTP, Network, Library, Support">
8 <title>LuaSocket: FTP support</title>
9 <link rel="stylesheet" href="reference.css" type="text/css">
10 </head>
11
12 <body>
13
14 <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15
16 <div class=header>
17 <hr>
18 <center>
19 <table summary="LuaSocket logo">
20 <tr><td align=center><a href="http://www.lua.org">
21 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
22 </a></td></tr>
23 <tr><td align=center valign=top>Network support for the Lua language
24 </td></tr>
25 </table>
26 <p class=bar>
27 <a href="home.html">home</a> &middot;
28 <a href="home.html#download">download</a> &middot;
29 <a href="installation.html">installation</a> &middot;
30 <a href="introduction.html">introduction</a> &middot;
31 <a href="reference.html">reference</a>
32 </p>
33 </center>
34 <hr>
35 </div>
36
37 <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39 <h2 id=ftp>FTP</h2>
40
41 <p>
42 FTP (File Transfer Protocol) is a protocol used to transfer files
43 between hosts. The <tt>ftp</tt> namespace offers thorough support
44 to FTP, under a simple interface. The implementation conforms to
45 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
46 </p>
47
48 <p>
49 High level functions are provided supporting the most common operations.
50 These high level functions are implemented on top of a lower level
51 interface. Using the low-level interface, users can easily create their
52 own functions to access <em>any</em> operation supported by the FTP
53 protocol. For that, check the implementation.
54 </p>
55
56 <p>
57 To really benefit from this module, a good understanding of
58 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
59 LTN012, Filters sources and sinks</a> is necessary.
60 </p>
61
62 <p>
63 To obtain the <tt>ftp</tt> namespace, run:
64 </p>
65
66 <pre class=example>
67 -- loads the FTP module and any libraries it requires
68 local ftp = require("socket.ftp")
69 </pre>
70
71 <p>
72 URLs MUST conform to
73 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
74 1738</a>, that is, an URL is a string in the form:
75 </p>
76
77 <blockquote>
78 <tt>
79 [ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i]</tt>
80 </blockquote>
81
82 <p>
83 The following constants in the namespace can be set to control the default behavior of
84 the FTP module:
85 </p>
86
87 <ul>
88 <li> <tt>PASSWORD</tt>: default anonymous password.
89 <li> <tt>PORT</tt>: default port used for the control connection;
90 <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
91 <li> <tt>USER</tt>: default anonymous user;
92 </ul>
93
94
95 <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
96
97 <p class=name id=get>
98 ftp.<b>get(</b>url<b>)</b><br>
99 ftp.<b>get{</b><br>
100 &nbsp;&nbsp;host = <i>string</i>,<br>
101 &nbsp;&nbsp;sink = <i>LTN12 sink</i>,<br>
102 &nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
103 &nbsp;&nbsp;[user = <i>string</i>,]<br>
104 &nbsp;&nbsp;[password = <i>string</i>]<br>
105 &nbsp;&nbsp;[command = <i>string</i>,]<br>
106 &nbsp;&nbsp;[port = <i>number</i>,]<br>
107 &nbsp;&nbsp;[type = <i>string</i>,]<br>
108 &nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
109 &nbsp;&nbsp;[create = <i>function</i>]<br>
110 <b>}</b>
111 </p>
112
113 <p class=description>
114 The <tt>get</tt> function has two forms. The simple form has fixed
115 functionality: it downloads the contents of a URL and returns it as a
116 string. The generic form allows a <em>lot</em> more control, as explained
117 below.
118 </p>
119
120 <p class=parameters>
121 If the argument of the <tt>get</tt> function is a table, the function
122 expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
123 <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
124 precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
125 the <em>simple</em>
126 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
127 sink that will receive the downloaded data. <tt>Argument</tt> or
128 <tt>path</tt> give the target path to the resource in the server. The
129 optional arguments are the following:
130 </p>
131 <ul>
132 <li><tt>user</tt>, <tt>password</tt>: User name and password used for
133 authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
134 <li><tt>command</tt>: The FTP command used to obtain data. Defaults to
135 "<tt>retr</tt>", but see example below;
136 <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
137 <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
138 "<tt>a</tt>". Defaults to whatever is the server default;
139 <li><tt>step</tt>:
140 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
141 pump step function used to pass data from the
142 server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
143 <li><tt>create</tt>: An optional function to be used instead of
144 <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
145 </ul>
146
147 <p class=return>
148 If successful, the simple version returns the URL contents as a
149 string, and the generic function returns 1. In case of error, both
150 functions return <b><tt>nil</tt></b> and an error message describing the
151 error.
152 </p>
153
154 <pre class=example>
155 -- load the ftp support
156 local ftp = require("socket.ftp")
157
158 -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
159 -- and get file "lua.tar.gz" from directory "pub/lua" as binary.
160 f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
161 </pre>
162
163 <pre class=example>
164 -- load needed modules
165 local ftp = require("socket.ftp")
166 local ltn12 = require("ltn12")
167 local url = require("socket.url")
168
169 -- a function that returns a directory listing
170 function nlst(u)
171 local t = {}
172 local p = url.parse(u)
173 p.command = "nlst"
174 p.sink = ltn12.sink.table(t)
175 local r, e = ftp.get(p)
176 return r and table.concat(t), e
177 end
178 </pre>
179
180 <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
181
182 <p class=name id=put>
183 ftp.<b>put(</b>url, content<b>)</b><br>
184 ftp.<b>put{</b><br>
185 &nbsp;&nbsp;host = <i>string</i>,<br>
186 &nbsp;&nbsp;source = <i>LTN12 sink</i>,<br>
187 &nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
188 &nbsp;&nbsp;[user = <i>string</i>,]<br>
189 &nbsp;&nbsp;[password = <i>string</i>]<br>
190 &nbsp;&nbsp;[command = <i>string</i>,]<br>
191 &nbsp;&nbsp;[port = <i>number</i>,]<br>
192 &nbsp;&nbsp;[type = <i>string</i>,]<br>
193 &nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
194 &nbsp;&nbsp;[create = <i>function</i>]<br>
195 <b>}</b>
196 </p>
197
198 <p class=description>
199 The <tt>put</tt> function has two forms. The simple form has fixed
200 functionality: it uploads a string of content into a URL. The generic form
201 allows a <em>lot</em> more control, as explained below.
202 </p>
203
204 <p class=parameters>
205 If the argument of the <tt>put</tt> function is a table, the function
206 expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
207 <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
208 precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
209 the <em>simple</em>
210 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
211 source that will provide the contents to be uploaded.
212 <tt>Argument</tt> or
213 <tt>path</tt> give the target path to the resource in the server. The
214 optional arguments are the following:
215 </p>
216 <ul>
217 <li><tt>user</tt>, <tt>password</tt>: User name and password used for
218 authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
219 <li><tt>command</tt>: The FTP command used to send data. Defaults to
220 "<tt>stor</tt>", but see example below;
221 <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
222 <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
223 "<tt>a</tt>". Defaults to whatever is the server default;
224 <li><tt>step</tt>:
225 <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
226 pump step function used to pass data from the
227 server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
228 <li><tt>create</tt>: An optional function to be used instead of
229 <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
230 </ul>
231
232 <p class=return>
233 Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
234 message describing the reason for failure.
235 </p>
236
237 <pre class=example>
238 -- load the ftp support
239 local ftp = require("socket.ftp")
240
241 -- Log as user "fulano" on server "ftp.example.com",
242 -- using password "silva", and store a file "README" with contents
243 -- "wrong password, of course"
244 f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
245 "wrong password, of course")
246 </pre>
247
248 <pre class=example>
249 -- load the ftp support
250 local ftp = require("socket.ftp")
251 local ltn12 = require("ltn12")
252
253 -- Log as user "fulano" on server "ftp.example.com",
254 -- using password "silva", and append to the remote file "LOG", sending the
255 -- contents of the local file "LOCAL-LOG"
256 f, e = ftp.put{
257 host = "ftp.example.com",
258 user = "fulano",
259 password = "silva",
260 command = "appe",
261 argument = "LOG",
262 source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
263 }
264 </pre>
265
266
267 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
268
269 <div class=footer>
270 <hr>
271 <center>
272 <p class=bar>
273 <a href="home.html">home</a> &middot;
274 <a href="home.html#download">download</a> &middot;
275 <a href="installation.html">installation</a> &middot;
276 <a href="introduction.html">introduction</a> &middot;
277 <a href="reference.html">reference</a>
278 </p>
279 <p>
280 <small>
281 Last modified by Diego Nehab on <br>
282 Thu Apr 20 00:25:18 EDT 2006
283 </small>
284 </p>
285 </center>
286 </div>
287
288 </body>
289 </html>