]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/ftp.tex
don't make read-only text controls editable when enabled
[wxWidgets.git] / docs / latex / wx / ftp.tex
CommitLineData
d9a50173
VZ
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: ftp.tex
3%% Purpose: wxFTP documentation
4%% Author: Guilhem Lavaux, Vadim Zeitlin
5%% Modified by:
6%% Created: ~1997
7%% RCS-ID: $Id$
fc2171bd 8%% Copyright: (c) wxWidgets team
8795498c 9%% License: wxWindows license
d9a50173
VZ
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
7d2946d2
GL
12\section{\class{wxFTP}}\label{wxftp}
13
d9a50173
VZ
14wxFTP can be used to establish a connection to an FTP server and perform all the
15usual operations. Please consult the RFC 959 for more details about the FTP
16protocol.
17
18To use a commands which doesn't involve file transfer (i.e. directory oriented
19commands) you just need to call a corresponding member function or use the
20generic \helpref{SendCommand}{wxftpsendcommand} method. However to actually
21transfer files you just get or give a stream to or from this class and the
22actual data are read or written using the usual stream methods.
23
24Example of using wxFTP for file downloading:
25
26\begin{verbatim}
27 wxFTP ftp;
28
29 // if you don't use these lines anonymous login will be used
30 ftp.SetUser("user");
31 ftp.SetPassword("password");
32
33 if ( !ftp.Connect("ftp.wxwindows.org") )
34 {
35 wxLogError("Couldn't connect");
36 return;
37 }
38
39 ftp.ChDir("/pub");
fc2171bd 40 wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz");
d9a50173
VZ
41 if ( !in )
42 {
43 wxLogError("Coudln't get file");
44 }
45 else
46 {
90e3949c 47 size_t size = in->GetSize();
d9a50173
VZ
48 char *data = new char[size];
49 if ( !in->Read(data, size) )
50 {
51 wxLogError("Read error");
52 }
53 else
54 {
55 // file data is in the buffer
56 ...
57 }
58
59 delete [] data;
60 delete in;
61 }
62\end{verbatim}
63
64To upload a file you would do (assuming the connection to the server was opened
65successfully):
66
67\begin{verbatim}
68 wxOutputStream *out = ftp.GetOutputStream("filename");
69 if ( out )
70 {
71 out->Write(...); // your data
72 delete out;
73 }
74\end{verbatim}
75
76\wxheading{Constants}
77
78wxFTP defines constants corresponding to the two supported transfer modes:
79
80\begin{verbatim}
81enum TransferMode
82{
83 ASCII,
84 BINARY
85};
86\end{verbatim}
87
7d2946d2
GL
88\wxheading{Derived from}
89
90\helpref{wxProtocol}{wxprotocol}
91
954b8ae6
JS
92\wxheading{Include files}
93
9a1b2c28 94<wx/protocol/ftp.h>
954b8ae6 95
7d2946d2
GL
96\wxheading{See also}
97
98\helpref{wxSocketBase}{wxsocketbase}
99
100% ----------------------------------------------------------------------------
101% Members
102% ----------------------------------------------------------------------------
103
296ec7d3 104\latexignore{\rtfignore{\wxheading{Members}}}
7d2946d2 105
e2454588 106
f0e8a2d0 107\membersection{wxFTP::wxFTP}\label{wxftpctor}
d9a50173
VZ
108
109\func{}{wxFTP}{\void}
110
111Default constructor.
7d2946d2 112
e2454588 113
f0e8a2d0 114\membersection{wxFTP::\destruct{wxFTP}}\label{wxftpdtor}
d9a50173
VZ
115
116\func{}{\destruct{wxFTP}}{\void}
117
118Destructor will close the connection if connected.
119
e2454588 120
2b5f62a0
VZ
121\membersection{wxFTP::Abort}\label{wxftpabort}
122
123\func{bool}{Abort}{\void}
124
43e8916f
MW
125Aborts the download currently in process, returns \true if ok, \false
126if an error occurred.
2b5f62a0 127
e2454588 128
f0e8a2d0 129\membersection{wxFTP::CheckCommand}\label{wxftpcheckcommand}
d9a50173
VZ
130
131\func{bool}{CheckCommand}{\param{const wxString\&}{ command}, \param{char }{ret}}
7d2946d2 132
605d715d 133Send the specified {\it command} to the FTP server. {\it ret} specifies
7d2946d2
GL
134the expected result.
135
136\wxheading{Return value}
137
cc81d32f 138true if the command has been sent successfully, else false.
7d2946d2 139
e2454588 140
d9a50173
VZ
141\membersection{wxFTP::SendCommand}\label{wxftpsendcommand}
142
143\func{char}{SendCommand}{\param{const wxString\&}{ command}}
144
145Send the specified {\it command} to the FTP server and return the first
146character of the return code.
7d2946d2 147
e2454588 148
f0e8a2d0 149\membersection{wxFTP::GetLastResult}\label{wxftpgetlastresult}
7d2946d2
GL
150
151\func{const wxString\&}{GetLastResult}{\void}
152
d9a50173
VZ
153Returns the last command result, i.e. the full server reply for the last
154command.
7d2946d2
GL
155
156% ----------------------------------------------------------------------------
157
e2454588 158
f0e8a2d0 159\membersection{wxFTP::ChDir}\label{wxftpchdir}
7d2946d2 160
6be663cf 161\func{bool}{ChDir}{\param{const wxString\&}{ dir}}
7d2946d2
GL
162
163Change the current FTP working directory.
cc81d32f 164Returns true if successful.
7d2946d2 165
e2454588 166
f0e8a2d0 167\membersection{wxFTP::MkDir}\label{wxftpmkdir}
7d2946d2 168
6be663cf 169\func{bool}{MkDir}{\param{const wxString\&}{ dir}}
7d2946d2
GL
170
171Create the specified directory in the current FTP working directory.
cc81d32f 172Returns true if successful.
7d2946d2 173
e2454588 174
f0e8a2d0 175\membersection{wxFTP::RmDir}\label{wxftprmdir}
7d2946d2 176
6be663cf 177\func{bool}{RmDir}{\param{const wxString\&}{ dir}}
7d2946d2
GL
178
179Remove the specified directory from the current FTP working directory.
cc81d32f 180Returns true if successful.
7d2946d2 181
e2454588 182
f0e8a2d0 183\membersection{wxFTP::Pwd}\label{wxftppwd}
7d2946d2
GL
184
185\func{wxString}{Pwd}{\void}
186
187Returns the current FTP working directory.
188
189% ----------------------------------------------------------------------------
190
e2454588 191
f0e8a2d0 192\membersection{wxFTP::Rename}\label{wxftprename}
7d2946d2 193
6be663cf 194\func{bool}{Rename}{\param{const wxString\&}{ src}, \param{const wxString\&}{ dst}}
7d2946d2 195
cc81d32f 196Rename the specified {\it src} element to {\it dst}. Returns true if successful.
7d2946d2
GL
197
198% ----------------------------------------------------------------------------
199
e2454588 200
f0e8a2d0 201\membersection{wxFTP::RmFile}\label{wxftprmfile}
7d2946d2 202
6be663cf 203\func{bool}{RmFile}{\param{const wxString\&}{ path}}
7d2946d2 204
cc81d32f 205Delete the file specified by {\it path}. Returns true if successful.
7d2946d2
GL
206
207% ----------------------------------------------------------------------------
208
e2454588 209
f0e8a2d0 210\membersection{wxFTP::SetAscii}\label{wxftpsetascii}
d9a50173
VZ
211
212\func{bool}{SetAscii}{\void}
213
214Sets the transfer mode to ASCII. It will be used for the next transfer.
215
e2454588 216
f0e8a2d0 217\membersection{wxFTP::SetBinary}\label{wxftpsetbinary}
d9a50173
VZ
218
219\func{bool}{SetBinary}{\void}
220
221Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
222
e2454588 223
f0e8a2d0 224\membersection{wxFTP::SetPassive}\label{wxftpsetpassive}
e2454588
VZ
225
226\func{void}{SetPassive}{\param{bool }{pasv}}
227
228If \arg{pasv} is \true, passive connection to the FTP server is used. This is
229the default as it works with practically all firewalls. If the server doesn't
230support passive move, you may call this function with \false argument to use
231active connection.
232
233
f0e8a2d0 234\membersection{wxFTP::SetTransferMode}\label{wxftpsettransfermode}
d9a50173
VZ
235
236\func{bool}{SetTransferMode}{\param{TransferMode }{mode}}
237
238Sets the transfer mode to the specified one. It will be used for the next
239transfer.
240
241If this function is never called, binary transfer mode is used by default.
242
243% ----------------------------------------------------------------------------
244
e2454588 245
f0e8a2d0 246\membersection{wxFTP::SetUser}\label{wxftpsetuser}
721b32e0 247
9a1b2c28
GL
248\func{void}{SetUser}{\param{const wxString\&}{ user}}
249
250Sets the user name to be sent to the FTP server to be allowed to log in.
251
252\wxheading{Default value}
253
254The default value of the user name is "anonymous".
255
256\wxheading{Remark}
257
258This parameter can be included in a URL if you want to use the URL manager.
294e9a7a 259For example, you can use: "ftp://a\_user:a\_password@a.host:service/a\_directory/a\_file"
9a1b2c28
GL
260to specify a user and a password.
261
e2454588 262
f0e8a2d0 263\membersection{wxFTP::SetPassword}\label{wxftpsetpassword}
721b32e0 264
9a1b2c28
GL
265\func{void}{SetPassword}{\param{const wxString\&}{ passwd}}
266
267Sets the password to be sent to the FTP server to be allowed to log in.
268
269\wxheading{Default value}
270
271The default value of the user name is your email address. For example, it could
272be "username@userhost.domain". This password is built by getting the current
273user name and the host name of the local machine from the system.
274
275\wxheading{Remark}
276
277This parameter can be included in a URL if you want to use the URL manager.
294e9a7a 278For example, you can use: "ftp://a\_user:a\_password@a.host:service/a\_directory/a\_file"
9a1b2c28
GL
279to specify a user and a password.
280
281% ----------------------------------------------------------------------------
721b32e0 282
e2454588 283
2b5f62a0
VZ
284\membersection{wxFTP::FileExists}\label{wxftpfileexists}
285
286\func{bool}{FileExists}{\param{const wxString\&}{ filename}}
287
43e8916f 288Returns \true if the given remote file exists, \false otherwise.
2b5f62a0 289
e2454588 290
2b5f62a0
VZ
291\membersection{wxFTP::GetFileSize}\label{wxftpgetfilesize}
292
293\func{int}{GetFileSize}{\param{const wxString\&}{ filename}}
294
295Returns the file size in bytes or $-1$ if the file doesn't exist or the size
296couldn't be determined. Notice that this size can be approximative size only
297and shouldn't be used for allocating the buffer in which the remote file is
298copied, for example.
299
e2454588 300
d9a50173
VZ
301\membersection{wxFTP::GetDirList}\label{wxftpgetdirlist}
302
303\func{bool}{GetDirList}{\param{wxArrayString\& }{files}, \param{const wxString\&}{ wildcard = ""}}
9a1b2c28
GL
304
305The GetList function is quite low-level. It returns the list of the files in
605d715d 306the current directory. The list can be filtered using the {\it wildcard} string.
8e907a13 307If {\it wildcard} is empty (default), it will return all files in directory.
9a1b2c28
GL
308
309The form of the list can change from one peer system to another. For example,
310for a UNIX peer system, it will look like this:
296ec7d3 311
9a1b2c28
GL
312\begin{verbatim}
313-r--r--r-- 1 guilhem lavaux 12738 Jan 16 20:17 cmndata.cpp
314-r--r--r-- 1 guilhem lavaux 10866 Jan 24 16:41 config.cpp
315-rw-rw-rw- 1 guilhem lavaux 29967 Dec 21 19:17 cwlex_yy.c
316-rw-rw-rw- 1 guilhem lavaux 14342 Jan 22 19:51 cwy_tab.c
317-r--r--r-- 1 guilhem lavaux 13890 Jan 29 19:18 date.cpp
318-r--r--r-- 1 guilhem lavaux 3989 Feb 8 19:18 datstrm.cpp
319\end{verbatim}
320
321But on Windows system, it will look like this:
296ec7d3 322
9a1b2c28
GL
323\begin{verbatim}
324winamp~1 exe 520196 02-25-1999 19:28 winamp204.exe
325 1 file(s) 520 196 bytes
326\end{verbatim}
327
cc81d32f 328Return value: true if the file list was successfully retrieved, false
8e907a13 329otherwise.
9a1b2c28 330
d9a50173
VZ
331\wxheading{See also}
332
333\helpref{GetFilesList}{wxftpgetfileslist}
334
e2454588 335
d9a50173
VZ
336\membersection{wxFTP::GetFilesList}\label{wxftpgetfileslist}
337
338\func{bool}{GetFilesList}{\param{wxArrayString\& }{files}, \param{const wxString\&}{ wildcard = ""}}
339
340This function returns the computer-parsable list of the files in the current
341directory (optionally only of the files matching the {\it wildcard}, all files
342by default). This list always has the same format and contains one full
343(including the directory path) file name per line.
344
cc81d32f 345Return value: true if the file list was successfully retrieved, false
d9a50173
VZ
346otherwise.
347
9a1b2c28
GL
348% ----------------------------------------------------------------------------
349
e2454588 350
f0e8a2d0 351\membersection{wxFTP::GetOutputStream}\label{wxftpgetoutputstream}
7d2946d2 352
6be663cf 353\func{wxOutputStream *}{GetOutputStream}{\param{const wxString\&}{ file}}
7d2946d2 354
605d715d 355Initializes an output stream to the specified {\it file}. The returned
6be663cf 356stream has all but the seek functionality of wxStreams. When the user finishes
7d2946d2
GL
357writing data, he has to delete the stream to close it.
358
359\wxheading{Return value}
360
361An initialized write-only stream.
6be663cf 362
7f42cff1
GL
363\wxheading{See also}
364
365\helpref{wxOutputStream}{wxoutputstream}
0492c5a0 366
9a1b2c28
GL
367% ----------------------------------------------------------------------------
368
e2454588 369
f0e8a2d0 370\membersection{wxFTP::GetInputStream}\label{wxftpgetinputstream}
9a1b2c28
GL
371
372\func{wxInputStream *}{GetInputStream}{\param{const wxString\&}{ path}}
373
43e8916f 374Creates a new input stream on the specified path. You can use all but the seek
fa482912 375functionality of wxStream. Seek isn't available on all streams. For example,
43e8916f 376HTTP or FTP streams do not deal with it. Other functions like Tell
fa482912 377are not available for this sort of stream, at present.
9a1b2c28
GL
378You will be notified when the EOF is reached by an error.
379
380\wxheading{Return value}
381
f6bcfd97 382Returns NULL if an error occurred (it could be a network failure or the fact
9a1b2c28
GL
383that the file doesn't exist).
384
fa482912
JS
385Returns the initialized stream. You will have to delete it yourself when you
386don't need it anymore. The destructor closes the DATA stream connection but
387will leave the COMMAND stream connection opened. It means that you can still
388send new commands without reconnecting.
9a1b2c28
GL
389
390\wxheading{Example of a standalone connection (without wxURL)}
391
392\begin{verbatim}
393 wxFTP ftp;
70be2567 394 wxInputStream *in_stream;
9a1b2c28
GL
395 char *data;
396
397 ftp.Connect("a.host.domain");
70be2567
VS
398 ftp.ChDir("a_directory");
399 in_stream = ftp.GetInputStream("a_file_to_get");
9a1b2c28 400
90e3949c 401 data = new char[in_stream->GetSize()];
9a1b2c28 402
90e3949c 403 in_stream->Read(data, in_stream->GetSize());
70be2567 404 if (in_stream->LastError() != wxStream_NOERROR) {
9a1b2c28
GL
405 // Do something.
406 }
407
70be2567 408 delete in_stream; /* Close the DATA connection */
9a1b2c28
GL
409
410 ftp.Close(); /* Close the COMMAND connection */
411\end{verbatim}
412
413\wxheading{See also}
414
415\helpref{wxInputStream}{wxinputstream}
721b32e0 416