interface/wx/protocol/ftp.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        protocol/ftp.h
   3 // Purpose:     interface of wxFTP
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxFTP
  10
  11     wxFTP can be used to establish a connection to an FTP server and perform all the
  12     usual operations. Please consult the RFC 959 (http://www.w3.org/Protocols/rfc959/)
  13     for more details about the FTP protocol.
  14
  15     wxFTP can thus be used to create a (basic) FTP @b client.
  16
  17     To use a command which doesn't involve file transfer (i.e. directory oriented
  18     commands) you just need to call a corresponding member function or use the
  19     generic wxFTP::SendCommand() method.
  20     However to actually transfer files you just get or give a stream to or from this
  21     class and the actual data are read or written using the usual stream methods.
  22
  23     Example of using wxFTP for file downloading:
  24
  25     @code
  26         wxFTP ftp;
  27
  28         // if you don't use these lines anonymous login will be used
  29         ftp.SetUser("user");
  30         ftp.SetPassword("password");
  31
  32         if ( !ftp.Connect("ftp.wxwidgets.org") )
  33         {
  34             wxLogError("Couldn't connect");
  35             return;
  36         }
  37
  38         ftp.ChDir("/pub/2.8.9");
  39         const char *filename = "wxWidgets-2.8.9.tar.bz2";
  40         int size = ftp.GetFileSize(filename);
  41         if ( size == -1 )
  42         {
  43             wxLogError("Couldn't get the file size for \"%s\"", filename);
  44         }
  45
  46         wxInputStream *in = ftp.GetInputStream(filename);
  47         if ( !in )
  48         {
  49             wxLogError("Couldn't get the file");
  50         }
  51         else
  52         {
  53             char *data = new char[size];
  54             if ( !in->Read(data, size) )
  55             {
  56                 wxLogError("Read error: %d", ftp.GetError());
  57             }
  58             else
  59             {
  60                 // file data is in the buffer
  61                 ...
  62             }
  63
  64             delete [] data;
  65             delete in;
  66         }
  67
  68         // gracefully close the connection to the server
  69         ftp.Close();
  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         Transfer modes used by wxFTP.
  94     */
  95     enum TransferMode
  96     {
  97         NONE,       //!< not set by user explicitly.
  98         ASCII,
  99         BINARY
 100     };
 101
 102     /**
 103         Default constructor.
 104     */
 105     wxFTP();
 106
 107     /**
 108         Destructor will close the connection if connected.
 109     */
 110     virtual ~wxFTP();
 111
 112
 113
 114     //@{
 115     /**
 116         Connect to the FTP server to default port (21) of the specified @a host.
 117      */
 118     virtual bool Connect(const wxString& host);
 119
 120     /**
 121         Connect to the FTP server to any port of the specified @a host.
 122         By default (@a port = 0), connection is made to default FTP port (21)
 123         of the specified @a host.
 124
 125         @since 2.9.1
 126      */
 127     virtual bool Connect(const wxString& host, unsigned short port);
 128     //@}
 129
 130     /**
 131         @name Functions for managing the FTP connection
 132      */
 133     //@{
 134
 135     /**
 136         Aborts the download currently in process, returns @true if ok, @false
 137         if an error occurred.
 138     */
 139     virtual bool Abort();
 140
 141     /**
 142         Gracefully closes the connection with the server.
 143     */
 144     virtual bool Close();
 145
 146     /**
 147         Send the specified @a command to the FTP server. @a ret specifies
 148         the expected result.
 149
 150         @return @true if the command has been sent successfully, else @false.
 151     */
 152     bool CheckCommand(const wxString& command, char ret);
 153
 154     /**
 155         Returns the last command result, i.e. the full server reply for the last command.
 156     */
 157     const wxString& GetLastResult();
 158
 159     /**
 160         Send the specified @a command to the FTP server and return the first
 161         character of the return code.
 162     */
 163     char SendCommand(const wxString& command);
 164
 165     /**
 166         Sets the transfer mode to ASCII. It will be used for the next transfer.
 167     */
 168     bool SetAscii();
 169
 170     /**
 171         Sets the transfer mode to binary. It will be used for the next transfer.
 172     */
 173     bool SetBinary();
 174
 175     /**
 176         If @a pasv is @true, passive connection to the FTP server is used.
 177
 178         This is the default as it works with practically all firewalls.
 179         If the server doesn't support passive mode, you may call this function
 180         with @false as argument to use an active connection.
 181     */
 182     void SetPassive(bool pasv);
 183
 184     /**
 185         Sets the password to be sent to the FTP server to be allowed to log in.
 186     */
 187     virtual void SetPassword(const wxString& passwd);
 188
 189     /**
 190         Sets the transfer mode to the specified one. It will be used for the next
 191         transfer.
 192
 193         If this function is never called, binary transfer mode is used by default.
 194     */
 195     bool SetTransferMode(TransferMode mode);
 196
 197     /**
 198         Sets the user name to be sent to the FTP server to be allowed to log in.
 199     */
 200     virtual void SetUser(const wxString& user);
 201
 202     //@}
 203
 204
 205
 206     /**
 207         @name Filesystem commands
 208      */
 209     //@{
 210
 211     /**
 212         Change the current FTP working directory.
 213         Returns @true if successful.
 214     */
 215     bool ChDir(const wxString& dir);
 216
 217     /**
 218         Create the specified directory in the current FTP working directory.
 219         Returns @true if successful.
 220     */
 221     bool MkDir(const wxString& dir);
 222
 223     /**
 224         Returns the current FTP working directory.
 225     */
 226     wxString Pwd();
 227
 228     /**
 229         Rename the specified @a src element to @e dst. Returns @true if successful.
 230     */
 231     bool Rename(const wxString& src, const wxString& dst);
 232
 233     /**
 234         Remove the specified directory from the current FTP working directory.
 235         Returns @true if successful.
 236     */
 237     bool RmDir(const wxString& dir);
 238
 239     /**
 240         Delete the file specified by @e path. Returns @true if successful.
 241     */
 242     bool RmFile(const wxString& path);
 243
 244     /**
 245         Returns @true if the given remote file exists, @false otherwise.
 246     */
 247     bool FileExists(const wxString& filename);
 248
 249     /**
 250         The GetList() function is quite low-level. It returns the list of the files in
 251         the current directory. The list can be filtered using the @a wildcard string.
 252
 253         If @a wildcard is empty (default), it will return all files in directory.
 254         The form of the list can change from one peer system to another. For example,
 255         for a UNIX peer system, it will look like this:
 256
 257         @verbatim
 258         -r--r--r--   1 guilhem  lavaux      12738 Jan 16 20:17 cmndata.cpp
 259         -r--r--r--   1 guilhem  lavaux      10866 Jan 24 16:41 config.cpp
 260         -rw-rw-rw-   1 guilhem  lavaux      29967 Dec 21 19:17 cwlex_yy.c
 261         -rw-rw-rw-   1 guilhem  lavaux      14342 Jan 22 19:51 cwy_tab.c
 262         -r--r--r--   1 guilhem  lavaux      13890 Jan 29 19:18 date.cpp
 263         -r--r--r--   1 guilhem  lavaux       3989 Feb  8 19:18 datstrm.cpp
 264         @endverbatim
 265
 266         But on Windows system, it will look like this:
 267
 268         @verbatim
 269         winamp~1 exe    520196 02-25-1999  19:28  winamp204.exe
 270             1 file(s)           520 196 bytes
 271         @endverbatim
 272
 273         @return @true if the file list was successfully retrieved, @false otherwise.
 274
 275         @see GetFilesList()
 276     */
 277     bool GetDirList(wxArrayString& files,
 278                     const wxString& wildcard = wxEmptyString);
 279
 280     /**
 281         Returns the file size in bytes or -1 if the file doesn't exist or the size
 282         couldn't be determined.
 283
 284         Notice that this size can be approximative size only and shouldn't be used
 285         for allocating the buffer in which the remote file is copied, for example.
 286     */
 287     int GetFileSize(const wxString& filename);
 288
 289     /**
 290         This function returns the computer-parsable list of the files in the current
 291         directory (optionally only of the files matching the @e wildcard, all files
 292         by default).
 293
 294         This list always has the same format and contains one full (including the
 295         directory path) file name per line.
 296
 297         @return @true if the file list was successfully retrieved, @false otherwise.
 298
 299         @see GetDirList()
 300     */
 301     bool GetFilesList(wxArrayString& files,
 302                       const wxString& wildcard = wxEmptyString);
 303
 304     //@}
 305
 306
 307     /**
 308         @name Download and upload functions
 309      */
 310
 311     //@{
 312     /**
 313         Creates a new input stream on the specified path.
 314
 315         You can use all but the seek functionality of wxStreamBase.
 316         wxStreamBase::Seek() isn't available on all streams. For example, HTTP or FTP
 317         streams do not deal with it. Other functions like wxStreamBase::Tell() are
 318         not available for this sort of stream, at present.
 319
 320         You will be notified when the EOF is reached by an error.
 321
 322         @return Returns @NULL if an error occurred (it could be a network failure
 323                 or the fact that the file doesn't exist).
 324     */
 325     virtual wxInputStream* GetInputStream(const wxString& path);
 326
 327     /**
 328         Initializes an output stream to the specified @a file.
 329
 330         The returned stream has all but the seek functionality of wxStreams.
 331         When the user finishes writing data, he has to delete the stream to close it.
 332
 333         @return An initialized write-only stream.
 334                 Returns @NULL if an error occurred (it could be a network failure
 335                 or the fact that the file doesn't exist).
 336     */
 337     virtual wxOutputStream* GetOutputStream(const wxString& file);
 338
 339     //@}
 340 };
 341