abandon attempts to make wxAnyStrPtr behave as bool: user-defined logical operators...

[wxWidgets.git] / interface / wx / protocol / ftp.h

diff --git a/interface/wx/protocol/ftp.h b/interface/wx/protocol/ftp.h
index a78b3d1dfadcee02d699e2b010e95a890ffb0c36..12bbca605f099d4189504b33d3a4c7548a1b2682 100644 (file)
--- a/interface/wx/protocol/ftp.h
+++ b/interface/wx/protocol/ftp.h
@@ -20,8 +20,10 @@ enum TransferMode
     @class wxFTP
 
     wxFTP can be used to establish a connection to an FTP server and perform all the
     @class wxFTP
 
     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
 
     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


@@ -38,25 +40,25 @@ enum TransferMode
         ftp.SetUser("user");
         ftp.SetPassword("password");
 
         ftp.SetUser("user");
         ftp.SetPassword("password");
 

-        if ( !ftp.Connect("ftp.wxwindows.org") )
+        if ( !ftp.Connect("ftp.wxwidgets.org") )

         {
             wxLogError("Couldn't connect");
             return;
         }
 
         {
             wxLogError("Couldn't connect");
             return;
         }
 

-        ftp.ChDir("/pub");
-        wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz");
+        ftp.ChDir("/pub/2.8.9");
+        wxInputStream *i = ftp.GetInputStream("wxWidgets-2.8.9.tar.bz2");

         if ( !in )
         {
         if ( !in )
         {

-            wxLogError("Coudln't get file");
+            wxLogError("Couldn't get the file");

         }
         else
         {
         }
         else
         {

-            size_t size = in-GetSize();
+            size_t size = in->GetSize();

             char *data = new char[size];
             if ( !in->Read(data, size) )
             {
             char *data = new char[size];
             if ( !in->Read(data, size) )
             {

-                wxLogError("Read error");
+                wxLogError("Read error: %d", ftp.GetError());

             }
             else
             {
             }
             else
             {


@@ -67,6 +69,9 @@ enum TransferMode
             delete [] data;
             delete in;
         }
             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
     @endcode
 
     To upload a file you would do (assuming the connection to the server was opened


@@ -97,19 +102,25 @@ public:
     /**
         Destructor will close the connection if connected.
     */
     /**
         Destructor will close the connection if connected.
     */

-    ~wxFTP();
+    virtual ~wxFTP();
+
+
+
+    /**
+        @name Functions for managing the FTP connection
+     */
+    //@{

 
     /**
         Aborts the download currently in process, returns @true if ok, @false
         if an error occurred.
     */
 
     /**
         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
 
     /**
         Send the specified @a command to the FTP server. @a ret specifies


@@ -119,6 +130,96 @@ public:
     */
     bool CheckCommand(const wxString& command, char ret);
 
     */
     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.
     */
     /**
         Returns @true if the given remote file exists, @false otherwise.
     */


@@ -153,7 +254,7 @@ public:
         @see GetFilesList()
     */
     bool GetDirList(wxArrayString& files,
         @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
 
     /**
         Returns the file size in bytes or -1 if the file doesn't exist or the size


@@ -177,8 +278,16 @@ public:
         @see GetDirList()
     */
     bool GetFilesList(wxArrayString& files,
         @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.
 
     /**
         Creates a new input stream on the specified path.
 


@@ -190,95 +299,22 @@ public:
         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
         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).
-    */
-    wxInputStream* GetInputStream(const wxString& path);
-
-    /**
-        Returns the last command result, i.e. the full server reply for the last command.
+                or the fact that the file doesn't exist).

     */
     */

-    const wxString GetLastResult();
+    virtual wxInputStream* GetInputStream(const wxString& path);

 
     /**
 
     /**

-        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.
 
         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);
+    virtual 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);
-
-    /**
-        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);
+    //@}

 };
 
 };