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