// Purpose: interface of wxFTP
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
/**
@class wxFTP
- @headerfile ftp.h wx/protocol/ftp.h
wxFTP can be used to establish a connection to an FTP server and perform all the
- usual operations. Please consult the RFC 959 for more details about the FTP
- protocol.
+ usual operations. Please consult the RFC 959 (http://www.w3.org/Protocols/rfc959/)
+ for more details about the FTP protocol.
+
+ wxFTP can thus be used to create a (basic) FTP @b client.
To use a command which doesn't involve file transfer (i.e. directory oriented
commands) you just need to call a corresponding member function or use the
ftp.SetUser("user");
ftp.SetPassword("password");
- if ( !ftp.Connect("ftp.wxwindows.org") )
+ if ( !ftp.Connect("ftp.wxwidgets.org") )
{
wxLogError("Couldn't connect");
return;
}
- ftp.ChDir("/pub");
- wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz");
+ ftp.ChDir("/pub/2.8.9");
+ const char *filename = "wxWidgets-2.8.9.tar.bz2";
+ int size = ftp.GetFileSize(filename);
+ if ( size == -1 )
+ {
+ wxLogError("Couldn't get the file size for \"%s\"", filename);
+ }
+
+ wxInputStream *i = ftp.GetInputStream(filename);
if ( !in )
{
- wxLogError("Coudln't get file");
+ wxLogError("Couldn't get the file");
}
else
{
- size_t size = in-GetSize();
char *data = new char[size];
if ( !in->Read(data, size) )
{
- wxLogError("Read error");
+ wxLogError("Read error: %d", ftp.GetError());
}
else
{
delete [] data;
delete in;
}
+
+ // gracefully close the connection to the server
+ ftp.Close();
@endcode
To upload a file you would do (assuming the connection to the server was opened
/**
Destructor will close the connection if connected.
*/
- ~wxFTP();
+ virtual ~wxFTP();
+
+
+
+ //@{
+ /**
+ Connect to the FTP server to default port (21) of the specified @a host.
+ */
+ virtual bool Connect(const wxString& host);
+
+ /**
+ Connect to the FTP server to any port of the specified @a host.
+ By default (@a port = 0), connection is made to default FTP port (21)
+ of the specified @a host.
+
+ @since 2.9.1
+ */
+ virtual bool Connect(const wxString& host, unsigned short port);
+ //@}
+
+ /**
+ @name Functions for managing the FTP connection
+ */
+ //@{
/**
Aborts the download currently in process, returns @true if ok, @false
if an error occurred.
*/
- bool Abort();
+ virtual bool Abort();
/**
- Change the current FTP working directory.
- Returns @true if successful.
+ Gracefully closes the connection with the server.
*/
- bool ChDir(const wxString& dir);
+ virtual bool Close();
/**
Send the specified @a command to the FTP server. @a ret specifies
*/
bool CheckCommand(const wxString& command, char ret);
+ /**
+ Returns the last command result, i.e. the full server reply for the last command.
+ */
+ const wxString& GetLastResult();
+
+ /**
+ Send the specified @a command to the FTP server and return the first
+ character of the return code.
+ */
+ char SendCommand(const wxString& command);
+
+ /**
+ Sets the transfer mode to ASCII. It will be used for the next transfer.
+ */
+ bool SetAscii();
+
+ /**
+ Sets the transfer mode to binary. It will be used for the next transfer.
+ */
+ bool SetBinary();
+
+ /**
+ If @a pasv is @true, passive connection to the FTP server is used.
+
+ This is the default as it works with practically all firewalls.
+ If the server doesn't support passive mode, you may call this function
+ with @false as argument to use an active connection.
+ */
+ void SetPassive(bool pasv);
+
+ /**
+ Sets the password to be sent to the FTP server to be allowed to log in.
+ */
+ virtual void SetPassword(const wxString& passwd);
+
+ /**
+ Sets the transfer mode to the specified one. It will be used for the next
+ transfer.
+
+ If this function is never called, binary transfer mode is used by default.
+ */
+ bool SetTransferMode(TransferMode mode);
+
+ /**
+ Sets the user name to be sent to the FTP server to be allowed to log in.
+ */
+ virtual void SetUser(const wxString& user);
+
+ //@}
+
+
+
+ /**
+ @name Filesystem commands
+ */
+ //@{
+
+ /**
+ Change the current FTP working directory.
+ Returns @true if successful.
+ */
+ bool ChDir(const wxString& dir);
+
+ /**
+ Create the specified directory in the current FTP working directory.
+ Returns @true if successful.
+ */
+ bool MkDir(const wxString& dir);
+
+ /**
+ Returns the current FTP working directory.
+ */
+ wxString Pwd();
+
+ /**
+ Rename the specified @a src element to @e dst. Returns @true if successful.
+ */
+ bool Rename(const wxString& src, const wxString& dst);
+
+ /**
+ Remove the specified directory from the current FTP working directory.
+ Returns @true if successful.
+ */
+ bool RmDir(const wxString& dir);
+
+ /**
+ Delete the file specified by @e path. Returns @true if successful.
+ */
+ bool RmFile(const wxString& path);
+
/**
Returns @true if the given remote file exists, @false otherwise.
*/
@see GetFilesList()
*/
bool GetDirList(wxArrayString& files,
- const wxString& wildcard = "");
+ const wxString& wildcard = wxEmptyString);
/**
Returns the file size in bytes or -1 if the file doesn't exist or the size
@see GetDirList()
*/
bool GetFilesList(wxArrayString& files,
- const wxString& wildcard = "");
+ const wxString& wildcard = wxEmptyString);
+
+ //@}
+
+ /**
+ @name Download and upload functions
+ */
+
+ //@{
/**
Creates a new input stream on the specified path.
You will be notified when the EOF is reached by an error.
@return Returns @NULL if an error occurred (it could be a network failure
- or the fact that the file doesn't exist).
+ or the fact that the file doesn't exist).
*/
- wxInputStream* GetInputStream(const wxString& path);
+ virtual wxInputStream* GetInputStream(const wxString& path);
/**
- Returns the last command result, i.e. the full server reply for the last command.
- */
- const wxString GetLastResult();
-
- /**
- Initializes an output stream to the specified @e file.
+ Initializes an output stream to the specified @a file.
The returned stream has all but the seek functionality of wxStreams.
When the user finishes writing data, he has to delete the stream to close it.
@return An initialized write-only stream.
-
- @see wxOutputStream
+ Returns @NULL if an error occurred (it could be a network failure
+ or the fact that the file doesn't exist).
*/
- wxOutputStream* GetOutputStream(const wxString& file);
-
- /**
- Create the specified directory in the current FTP working directory.
- Returns @true if successful.
- */
- bool MkDir(const wxString& dir);
-
- /**
- Returns the current FTP working directory.
- */
- wxString Pwd();
-
- /**
- Rename the specified @a src element to @e dst. Returns @true if successful.
- */
- bool Rename(const wxString& src, const wxString& dst);
-
- /**
- Remove the specified directory from the current FTP working directory.
- Returns @true if successful.
- */
- bool RmDir(const wxString& dir);
+ virtual wxOutputStream* GetOutputStream(const wxString& file);
- /**
- Delete the file specified by @e path. Returns @true if successful.
- */
- bool RmFile(const wxString& path);
-
- /**
- Send the specified @a command to the FTP server and return the first
- character of the return code.
- */
- char SendCommand(const wxString& command);
-
- /**
- Sets the transfer mode to ASCII. It will be used for the next transfer.
- */
- bool SetAscii();
-
- /**
- Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
- */
- bool SetBinary();
-
- /**
- If @a pasv is @true, passive connection to the FTP server is used.
-
- This is the default as it works with practically all firewalls.
- If the server doesn't support passive move, you may call this function with
- @false argument to use active connection.
- */
- void SetPassive(bool pasv);
-
- /**
- Sets the password to be sent to the FTP server to be allowed to log in.
- */
- void SetPassword(const wxString& passwd);
-
- /**
- Sets the transfer mode to the specified one. It will be used for the next
- transfer.
-
- If this function is never called, binary transfer mode is used by default.
- */
- bool SetTransferMode(TransferMode mode);
-
- /**
- Sets the user name to be sent to the FTP server to be allowed to log in.
- */
- void SetUser(const wxString& user);
+ //@}
};
projects / wxWidgets.git / blobdiff