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