]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/protocol/ftp.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: protocol/ftp.h
3 // Purpose: interface of wxFTP
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 Transfer modes used by wxFTP.
14 NONE
, //!< not set by user explicitly.
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 (http://www.w3.org/Protocols/rfc959/)
24 for more details about the FTP protocol.
26 wxFTP can thus be used to create a (basic) FTP @b client.
28 To use a command which doesn't involve file transfer (i.e. directory oriented
29 commands) you just need to call a corresponding member function or use the
30 generic wxFTP::SendCommand() method.
31 However to actually transfer files you just get or give a stream to or from this
32 class and the actual data are read or written using the usual stream methods.
34 Example of using wxFTP for file downloading:
39 // if you don't use these lines anonymous login will be used
41 ftp.SetPassword("password");
43 if ( !ftp.Connect("ftp.wxwidgets.org") )
45 wxLogError("Couldn't connect");
49 ftp.ChDir("/pub/2.8.9");
50 const char *filename = "wxWidgets-2.8.9.tar.bz2";
51 int size = ftp.GetFileSize(filename);
54 wxLogError("Couldn't get the file size for \"%s\"", filename);
57 wxInputStream *i = ftp.GetInputStream(filename);
60 wxLogError("Couldn't get the file");
64 char *data = new char[size];
65 if ( !in->Read(data, size) )
67 wxLogError("Read error: %d", ftp.GetError());
71 // file data is in the buffer
79 // gracefully close the connection to the server
83 To upload a file you would do (assuming the connection to the server was opened
87 wxOutputStream *out = ftp.GetOutputStream("filename");
90 out->Write(...); // your data
100 class wxFTP
: public wxProtocol
109 Destructor will close the connection if connected.
117 Connect to the FTP server to default port (21) of the specified @a host.
119 virtual bool Connect(const wxString
& host
);
122 Connect to the FTP server to any port of the specified @a host.
123 By default (@a port = 0), connection is made to default FTP port (21)
124 of the specified @a host.
128 virtual bool Connect(const wxString
& host
, unsigned short port
);
132 @name Functions for managing the FTP connection
137 Aborts the download currently in process, returns @true if ok, @false
138 if an error occurred.
140 virtual bool Abort();
143 Gracefully closes the connection with the server.
145 virtual bool Close();
148 Send the specified @a command to the FTP server. @a ret specifies
151 @return @true if the command has been sent successfully, else @false.
153 bool CheckCommand(const wxString
& command
, char ret
);
156 Returns the last command result, i.e. the full server reply for the last command.
158 const wxString
& GetLastResult();
161 Send the specified @a command to the FTP server and return the first
162 character of the return code.
164 char SendCommand(const wxString
& command
);
167 Sets the transfer mode to ASCII. It will be used for the next transfer.
172 Sets the transfer mode to binary. It will be used for the next transfer.
177 If @a pasv is @true, passive connection to the FTP server is used.
179 This is the default as it works with practically all firewalls.
180 If the server doesn't support passive mode, you may call this function
181 with @false as argument to use an active connection.
183 void SetPassive(bool pasv
);
186 Sets the password to be sent to the FTP server to be allowed to log in.
188 virtual void SetPassword(const wxString
& passwd
);
191 Sets the transfer mode to the specified one. It will be used for the next
194 If this function is never called, binary transfer mode is used by default.
196 bool SetTransferMode(TransferMode mode
);
199 Sets the user name to be sent to the FTP server to be allowed to log in.
201 virtual void SetUser(const wxString
& user
);
208 @name Filesystem commands
213 Change the current FTP working directory.
214 Returns @true if successful.
216 bool ChDir(const wxString
& dir
);
219 Create the specified directory in the current FTP working directory.
220 Returns @true if successful.
222 bool MkDir(const wxString
& dir
);
225 Returns the current FTP working directory.
230 Rename the specified @a src element to @e dst. Returns @true if successful.
232 bool Rename(const wxString
& src
, const wxString
& dst
);
235 Remove the specified directory from the current FTP working directory.
236 Returns @true if successful.
238 bool RmDir(const wxString
& dir
);
241 Delete the file specified by @e path. Returns @true if successful.
243 bool RmFile(const wxString
& path
);
246 Returns @true if the given remote file exists, @false otherwise.
248 bool FileExists(const wxString
& filename
);
251 The GetList() function is quite low-level. It returns the list of the files in
252 the current directory. The list can be filtered using the @a wildcard string.
254 If @a wildcard is empty (default), it will return all files in directory.
255 The form of the list can change from one peer system to another. For example,
256 for a UNIX peer system, it will look like this:
259 -r--r--r-- 1 guilhem lavaux 12738 Jan 16 20:17 cmndata.cpp
260 -r--r--r-- 1 guilhem lavaux 10866 Jan 24 16:41 config.cpp
261 -rw-rw-rw- 1 guilhem lavaux 29967 Dec 21 19:17 cwlex_yy.c
262 -rw-rw-rw- 1 guilhem lavaux 14342 Jan 22 19:51 cwy_tab.c
263 -r--r--r-- 1 guilhem lavaux 13890 Jan 29 19:18 date.cpp
264 -r--r--r-- 1 guilhem lavaux 3989 Feb 8 19:18 datstrm.cpp
267 But on Windows system, it will look like this:
270 winamp~1 exe 520196 02-25-1999 19:28 winamp204.exe
271 1 file(s) 520 196 bytes
274 @return @true if the file list was successfully retrieved, @false otherwise.
278 bool GetDirList(wxArrayString
& files
,
279 const wxString
& wildcard
= wxEmptyString
);
282 Returns the file size in bytes or -1 if the file doesn't exist or the size
283 couldn't be determined.
285 Notice that this size can be approximative size only and shouldn't be used
286 for allocating the buffer in which the remote file is copied, for example.
288 int GetFileSize(const wxString
& filename
);
291 This function returns the computer-parsable list of the files in the current
292 directory (optionally only of the files matching the @e wildcard, all files
295 This list always has the same format and contains one full (including the
296 directory path) file name per line.
298 @return @true if the file list was successfully retrieved, @false otherwise.
302 bool GetFilesList(wxArrayString
& files
,
303 const wxString
& wildcard
= wxEmptyString
);
309 @name Download and upload functions
314 Creates a new input stream on the specified path.
316 You can use all but the seek functionality of wxStreamBase.
317 wxStreamBase::Seek() isn't available on all streams. For example, HTTP or FTP
318 streams do not deal with it. Other functions like wxStreamBase::Tell() are
319 not available for this sort of stream, at present.
321 You will be notified when the EOF is reached by an error.
323 @return Returns @NULL if an error occurred (it could be a network failure
324 or the fact that the file doesn't exist).
326 virtual wxInputStream
* GetInputStream(const wxString
& path
);
329 Initializes an output stream to the specified @a file.
331 The returned stream has all but the seek functionality of wxStreams.
332 When the user finishes writing data, he has to delete the stream to close it.
334 @return An initialized write-only stream.
335 Returns @NULL if an error occurred (it could be a network failure
336 or the fact that the file doesn't exist).
338 virtual wxOutputStream
* GetOutputStream(const wxString
& file
);