interface/protocol/ftp.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        protocol/ftp.h
   3 // Purpose:     documentation for wxFTP class
   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     @seealso
  79     wxSocketBase
  80 */
  81 class wxFTP : public wxProtocol
  82 {
  83 public:
  84     /**
  85         Default constructor.
  86     */
  87 #define wxFTP()     /* implementation is private */
  88
  89     /**
  90         Destructor will close the connection if connected.
  91     */
  92 #define ~wxFTP()     /* implementation is private */
  93
  94     /**
  95         Aborts the download currently in process, returns @true if ok, @false
  96         if an error occurred.
  97     */
  98     bool Abort();
  99
 100     /**
 101         Change the current FTP working directory.
 102         Returns @true if successful.
 103     */
 104     bool ChDir(const wxString& dir);
 105
 106     /**
 107         Send the specified @e command to the FTP server. @e ret specifies
 108         the expected result.
 109
 110         @returns @true if the command has been sent successfully, else @false.
 111     */
 112     bool CheckCommand(const wxString& command, char ret);
 113
 114     /**
 115         Returns @true if the given remote file exists, @false otherwise.
 116     */
 117     bool FileExists(const wxString& filename);
 118
 119     /**
 120         The GetList function is quite low-level. It returns the list of the files in
 121         the current directory. The list can be filtered using the @e wildcard string.
 122         If @e wildcard is empty (default), it will return all files in directory.
 123
 124         The form of the list can change from one peer system to another. For example,
 125         for a UNIX peer system, it will look like this:
 126         But on Windows system, it will look like this:
 127         Return value: @true if the file list was successfully retrieved, @false
 128         otherwise.
 129
 130         @sa 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
 149         Return value: @true if the file list was successfully retrieved, @false
 150         otherwise.
 151     */
 152     bool GetFilesList(wxArrayString& files,
 153                       const wxString& wildcard = "");
 154
 155     /**
 156         Creates a new input stream on the specified path. You can use all but the seek
 157         functionality of wxStream. Seek isn't available on all streams. For example,
 158         HTTP or FTP streams do not deal with it. Other functions like Tell
 159         are not available for this sort of stream, at present.
 160         You will be notified when the EOF is reached by an error.
 161
 162         @returns Returns @NULL if an error occurred (it could be a network failure
 163                    or the fact that the file doesn't exist).
 164     */
 165     wxInputStream * GetInputStream(const wxString& path);
 166
 167     /**
 168         Returns the last command result, i.e. the full server reply for the last
 169         command.
 170     */
 171     const wxString GetLastResult();
 172
 173     /**
 174         Initializes an output stream to the specified @e file. The returned
 175         stream has all but the seek functionality of wxStreams. When the user finishes
 176         writing data, he has to delete the stream to close it.
 177
 178         @returns An initialized write-only stream.
 179
 180         @sa wxOutputStream
 181     */
 182     wxOutputStream * GetOutputStream(const wxString& file);
 183
 184     /**
 185         Create the specified directory in the current FTP working directory.
 186         Returns @true if successful.
 187     */
 188     bool MkDir(const wxString& dir);
 189
 190     /**
 191         Returns the current FTP working directory.
 192     */
 193 #define wxString Pwd()     /* implementation is private */
 194
 195     /**
 196         Rename the specified @e src element to @e dst. Returns @true if successful.
 197     */
 198     bool Rename(const wxString& src, const wxString& dst);
 199
 200     /**
 201         Remove the specified directory from the current FTP working directory.
 202         Returns @true if successful.
 203     */
 204     bool RmDir(const wxString& dir);
 205
 206     /**
 207         Delete the file specified by @e path. Returns @true if successful.
 208     */
 209     bool RmFile(const wxString& path);
 210
 211     /**
 212         Send the specified @e command to the FTP server and return the first
 213         character of the return code.
 214     */
 215     char SendCommand(const wxString& command);
 216
 217     /**
 218         Sets the transfer mode to ASCII. It will be used for the next transfer.
 219     */
 220     bool SetAscii();
 221
 222     /**
 223         Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
 224     */
 225     bool SetBinary();
 226
 227     /**
 228         If @e pasv is @true, passive connection to the FTP server is used. This is
 229         the default as it works with practically all firewalls. If the server doesn't
 230         support passive move, you may call this function with @false argument to use
 231         active connection.
 232     */
 233     void SetPassive(bool pasv);
 234
 235     /**
 236         Sets the password to be sent to the FTP server to be allowed to log in.
 237     */
 238     void SetPassword(const wxString& passwd);
 239
 240     /**
 241         Sets the transfer mode to the specified one. It will be used for the next
 242         transfer.
 243
 244         If this function is never called, binary transfer mode is used by default.
 245     */
 246     bool SetTransferMode(TransferMode mode);
 247
 248     /**
 249         Sets the user name to be sent to the FTP server to be allowed to log in.
 250     */
 251     void SetUser(const wxString& user);
 252 };