interface/wx/protocol/ftp.h

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