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