]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/protocol/ftp.h
automated changes: many (pure) virtual specifiers added
[wxWidgets.git] / interface / wx / protocol / ftp.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: protocol/ftp.h
3 // Purpose: interface of wxFTP
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 Transfer modes used by wxFTP.
11 */
12 enum TransferMode
13 {
14 NONE, //!< not set by user explicitly.
15 ASCII,
16 BINARY
17 };
18
19 /**
20 @class wxFTP
21
22 wxFTP can be used to establish a connection to an FTP server and perform all the
23 usual operations. Please consult the RFC 959 for more details about the FTP
24 protocol.
25
26 To use a command which doesn't involve file transfer (i.e. directory oriented
27 commands) you just need to call a corresponding member function or use the
28 generic wxFTP::SendCommand() method.
29 However to actually transfer files you just get or give a stream to or from this
30 class and the actual data are read or written using the usual stream methods.
31
32 Example of using wxFTP for file downloading:
33
34 @code
35 wxFTP ftp;
36
37 // if you don't use these lines anonymous login will be used
38 ftp.SetUser("user");
39 ftp.SetPassword("password");
40
41 if ( !ftp.Connect("ftp.wxwindows.org") )
42 {
43 wxLogError("Couldn't connect");
44 return;
45 }
46
47 ftp.ChDir("/pub");
48 wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz");
49 if ( !in )
50 {
51 wxLogError("Coudln't get file");
52 }
53 else
54 {
55 size_t size = in-GetSize();
56 char *data = new char[size];
57 if ( !in->Read(data, size) )
58 {
59 wxLogError("Read error");
60 }
61 else
62 {
63 // file data is in the buffer
64 ...
65 }
66
67 delete [] data;
68 delete in;
69 }
70 @endcode
71
72 To upload a file you would do (assuming the connection to the server was opened
73 successfully):
74
75 @code
76 wxOutputStream *out = ftp.GetOutputStream("filename");
77 if ( out )
78 {
79 out->Write(...); // your data
80 delete out;
81 }
82 @endcode
83
84 @library{wxnet}
85 @category{net}
86
87 @see wxSocketBase
88 */
89 class wxFTP : public wxProtocol
90 {
91 public:
92 /**
93 Default constructor.
94 */
95 wxFTP();
96
97 /**
98 Destructor will close the connection if connected.
99 */
100 virtual ~wxFTP();
101
102 /**
103 Aborts the download currently in process, returns @true if ok, @false
104 if an error occurred.
105 */
106 virtual bool Abort();
107
108 /**
109 Change the current FTP working directory.
110 Returns @true if successful.
111 */
112 bool ChDir(const wxString& dir);
113
114 /**
115 Send the specified @a command to the FTP server. @a ret specifies
116 the expected result.
117
118 @return @true if the command has been sent successfully, else @false.
119 */
120 bool CheckCommand(const wxString& command, char ret);
121
122 /**
123 Returns @true if the given remote file exists, @false otherwise.
124 */
125 bool FileExists(const wxString& filename);
126
127 /**
128 The GetList() function is quite low-level. It returns the list of the files in
129 the current directory. The list can be filtered using the @a wildcard string.
130
131 If @a wildcard is empty (default), it will return all files in directory.
132 The form of the list can change from one peer system to another. For example,
133 for a UNIX peer system, it will look like this:
134
135 @verbatim
136 -r--r--r-- 1 guilhem lavaux 12738 Jan 16 20:17 cmndata.cpp
137 -r--r--r-- 1 guilhem lavaux 10866 Jan 24 16:41 config.cpp
138 -rw-rw-rw- 1 guilhem lavaux 29967 Dec 21 19:17 cwlex_yy.c
139 -rw-rw-rw- 1 guilhem lavaux 14342 Jan 22 19:51 cwy_tab.c
140 -r--r--r-- 1 guilhem lavaux 13890 Jan 29 19:18 date.cpp
141 -r--r--r-- 1 guilhem lavaux 3989 Feb 8 19:18 datstrm.cpp
142 @endverbatim
143
144 But on Windows system, it will look like this:
145
146 @verbatim
147 winamp~1 exe 520196 02-25-1999 19:28 winamp204.exe
148 1 file(s) 520 196 bytes
149 @endverbatim
150
151 @return @true if the file list was successfully retrieved, @false otherwise.
152
153 @see GetFilesList()
154 */
155 bool GetDirList(wxArrayString& files,
156 const wxString& wildcard = "");
157
158 /**
159 Returns the file size in bytes or -1 if the file doesn't exist or the size
160 couldn't be determined.
161
162 Notice that this size can be approximative size only and shouldn't be used
163 for allocating the buffer in which the remote file is copied, for example.
164 */
165 int GetFileSize(const wxString& filename);
166
167 /**
168 This function returns the computer-parsable list of the files in the current
169 directory (optionally only of the files matching the @e wildcard, all files
170 by default).
171
172 This list always has the same format and contains one full (including the
173 directory path) file name per line.
174
175 @return @true if the file list was successfully retrieved, @false otherwise.
176
177 @see GetDirList()
178 */
179 bool GetFilesList(wxArrayString& files,
180 const wxString& wildcard = "");
181
182 /**
183 Creates a new input stream on the specified path.
184
185 You can use all but the seek functionality of wxStreamBase.
186 wxStreamBase::Seek() isn't available on all streams. For example, HTTP or FTP
187 streams do not deal with it. Other functions like wxStreamBase::Tell() are
188 not available for this sort of stream, at present.
189
190 You will be notified when the EOF is reached by an error.
191
192 @return Returns @NULL if an error occurred (it could be a network failure
193 or the fact that the file doesn't exist).
194 */
195 virtual wxInputStream* GetInputStream(const wxString& path);
196
197 /**
198 Returns the last command result, i.e. the full server reply for the last command.
199 */
200 const wxString GetLastResult();
201
202 /**
203 Initializes an output stream to the specified @e file.
204
205 The returned stream has all but the seek functionality of wxStreams.
206 When the user finishes writing data, he has to delete the stream to close it.
207
208 @return An initialized write-only stream.
209
210 @see wxOutputStream
211 */
212 virtual wxOutputStream* GetOutputStream(const wxString& file);
213
214 /**
215 Create the specified directory in the current FTP working directory.
216 Returns @true if successful.
217 */
218 bool MkDir(const wxString& dir);
219
220 /**
221 Returns the current FTP working directory.
222 */
223 wxString Pwd();
224
225 /**
226 Rename the specified @a src element to @e dst. Returns @true if successful.
227 */
228 bool Rename(const wxString& src, const wxString& dst);
229
230 /**
231 Remove the specified directory from the current FTP working directory.
232 Returns @true if successful.
233 */
234 bool RmDir(const wxString& dir);
235
236 /**
237 Delete the file specified by @e path. Returns @true if successful.
238 */
239 bool RmFile(const wxString& path);
240
241 /**
242 Send the specified @a command to the FTP server and return the first
243 character of the return code.
244 */
245 char SendCommand(const wxString& command);
246
247 /**
248 Sets the transfer mode to ASCII. It will be used for the next transfer.
249 */
250 bool SetAscii();
251
252 /**
253 Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
254 */
255 bool SetBinary();
256
257 /**
258 If @a pasv is @true, passive connection to the FTP server is used.
259
260 This is the default as it works with practically all firewalls.
261 If the server doesn't support passive move, you may call this function with
262 @false argument to use active connection.
263 */
264 void SetPassive(bool pasv);
265
266 /**
267 Sets the password to be sent to the FTP server to be allowed to log in.
268 */
269 virtual void SetPassword(const wxString& passwd);
270
271 /**
272 Sets the transfer mode to the specified one. It will be used for the next
273 transfer.
274
275 If this function is never called, binary transfer mode is used by default.
276 */
277 bool SetTransferMode(TransferMode mode);
278
279 /**
280 Sets the user name to be sent to the FTP server to be allowed to log in.
281 */
282 virtual void SetUser(const wxString& user);
283 };
284