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