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