Use /bin/echo for creation of Mac OS X PkgInfo files.

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

diff --git a/interface/wx/protocol/ftp.h b/interface/wx/protocol/ftp.h
index 0455b287a961212c1017b216e685117ffc72aa5b..b6a7992ffcb37a9930f9cb2a7c1339dbe5751010 100644 (file)
--- a/interface/wx/protocol/ftp.h
+++ b/interface/wx/protocol/ftp.h
@@ -3,25 +3,17 @@
 // Purpose:     interface of wxFTP
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxFTP
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/**
-    Transfer modes used by wxFTP.
-*/
-enum TransferMode
-{
-    NONE,       //!< not set by user explicitly.
-    ASCII,
-    BINARY
-};
-

 /**
     @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 +30,31 @@ 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");
+        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 *in = ftp.GetInputStream(filename);

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

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

         }
         else
         {
         }
         else
         {

-            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 +65,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


@@ -89,6 +90,16 @@ enum TransferMode
 class wxFTP : public wxProtocol
 {
 public:
 class wxFTP : public wxProtocol
 {
 public:

+    /**
+        Transfer modes used by wxFTP.
+    */
+    enum TransferMode
+    {
+        NONE,       //!< not set by user explicitly.
+        ASCII,
+        BINARY
+    };
+

     /**
         Default constructor.
     */
     /**
         Default constructor.
     */


@@ -99,6 +110,29 @@ public:
     */
     virtual ~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.
     /**
         Aborts the download currently in process, returns @true if ok, @false
         if an error occurred.


@@ -106,10 +140,9 @@ public:
     virtual 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 +152,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 +276,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 +300,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 +321,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).
+                or the fact that the file doesn't exist).

     */
     virtual 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.
 
         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).

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

 };
 
 };