docs/latex/wx/ftp.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        ftp.tex
   3 %% Purpose:     wxFTP documentation
   4 %% Author:      Guilhem Lavaux, Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     ~1997
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets team
   9 %% License:     wxWidgets license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxFTP}}\label{wxftp}
  13
  14 wxFTP can be used to establish a connection to an FTP server and perform all the
  15 usual operations. Please consult the RFC 959 for more details about the FTP
  16 protocol.
  17
  18 To use a commands 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 \helpref{SendCommand}{wxftpsendcommand} method. However to actually
  21 transfer files you just get or give a stream to or from this class and the
  22 actual data are read or written using the usual stream methods.
  23
  24 Example of using wxFTP for file downloading:
  25
  26 \begin{verbatim}
  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.wxwindows.org") )
  34     {
  35         wxLogError("Couldn't connect");
  36         return;
  37     }
  38
  39     ftp.ChDir("/pub");
  40     wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz");
  41     if ( !in )
  42     {
  43         wxLogError("Coudln't get file");
  44     }
  45     else
  46     {
  47         size_t size = in->GetSize();
  48         char *data = new char[size];
  49         if ( !in->Read(data, size) )
  50         {
  51             wxLogError("Read error");
  52         }
  53         else
  54         {
  55             // file data is in the buffer
  56             ...
  57         }
  58
  59         delete [] data;
  60         delete in;
  61     }
  62 \end{verbatim}
  63
  64 To upload a file you would do (assuming the connection to the server was opened
  65 successfully):
  66
  67 \begin{verbatim}
  68         wxOutputStream *out = ftp.GetOutputStream("filename");
  69         if ( out )
  70         {
  71             out->Write(...); // your data
  72             delete out;
  73         }
  74 \end{verbatim}
  75
  76 \wxheading{Constants}
  77
  78 wxFTP defines constants corresponding to the two supported transfer modes:
  79
  80 \begin{verbatim}
  81 enum TransferMode
  82 {
  83     ASCII,
  84     BINARY
  85 };
  86 \end{verbatim}
  87
  88 \wxheading{Derived from}
  89
  90 \helpref{wxProtocol}{wxprotocol}
  91
  92 \wxheading{Include files}
  93
  94 <wx/protocol/ftp.h>
  95
  96 \wxheading{See also}
  97
  98 \helpref{wxSocketBase}{wxsocketbase}
  99
 100 % ----------------------------------------------------------------------------
 101 % Members
 102 % ----------------------------------------------------------------------------
 103
 104 \latexignore{\rtfignore{\wxheading{Members}}}
 105
 106 \membersection{wxFTP::wxFTP}
 107
 108 \func{}{wxFTP}{\void}
 109
 110 Default constructor.
 111
 112 \membersection{wxFTP::\destruct{wxFTP}}
 113
 114 \func{}{\destruct{wxFTP}}{\void}
 115
 116 Destructor will close the connection if connected.
 117
 118 \membersection{wxFTP::Abort}\label{wxftpabort}
 119
 120 \func{bool}{Abort}{\void}
 121
 122 Aborts the download currently in process, returns {\tt true} if ok, {\tt false}
 123 if an error occured.
 124
 125 \membersection{wxFTP::CheckCommand}
 126
 127 \func{bool}{CheckCommand}{\param{const wxString\&}{ command}, \param{char }{ret}}
 128
 129 Send the specified {\it command} to the FTP server. {\it ret} specifies
 130 the expected result.
 131
 132 \wxheading{Return value}
 133
 134 true if the command has been sent successfully, else false.
 135
 136 \membersection{wxFTP::SendCommand}\label{wxftpsendcommand}
 137
 138 \func{char}{SendCommand}{\param{const wxString\&}{ command}}
 139
 140 Send the specified {\it command} to the FTP server and return the first
 141 character of the return code.
 142
 143 \membersection{wxFTP::GetLastResult}
 144
 145 \func{const wxString\&}{GetLastResult}{\void}
 146
 147 Returns the last command result, i.e. the full server reply for the last
 148 command.
 149
 150 % ----------------------------------------------------------------------------
 151
 152 \membersection{wxFTP::ChDir}
 153
 154 \func{bool}{ChDir}{\param{const wxString\&}{ dir}}
 155
 156 Change the current FTP working directory.
 157 Returns true if successful.
 158
 159 \membersection{wxFTP::MkDir}
 160
 161 \func{bool}{MkDir}{\param{const wxString\&}{ dir}}
 162
 163 Create the specified directory in the current FTP working directory.
 164 Returns true if successful.
 165
 166 \membersection{wxFTP::RmDir}
 167
 168 \func{bool}{RmDir}{\param{const wxString\&}{ dir}}
 169
 170 Remove the specified directory from the current FTP working directory.
 171 Returns true if successful.
 172
 173 \membersection{wxFTP::Pwd}
 174
 175 \func{wxString}{Pwd}{\void}
 176
 177 Returns the current FTP working directory.
 178
 179 % ----------------------------------------------------------------------------
 180
 181 \membersection{wxFTP::Rename}
 182
 183 \func{bool}{Rename}{\param{const wxString\&}{ src}, \param{const wxString\&}{ dst}}
 184
 185 Rename the specified {\it src} element to {\it dst}. Returns true if successful.
 186
 187 % ----------------------------------------------------------------------------
 188
 189 \membersection{wxFTP::RmFile}
 190
 191 \func{bool}{RmFile}{\param{const wxString\&}{ path}}
 192
 193 Delete the file specified by {\it path}. Returns true if successful.
 194
 195 % ----------------------------------------------------------------------------
 196
 197 \membersection{wxFTP::SetAscii}
 198
 199 \func{bool}{SetAscii}{\void}
 200
 201 Sets the transfer mode to ASCII. It will be used for the next transfer.
 202
 203 \membersection{wxFTP::SetBinary}
 204
 205 \func{bool}{SetBinary}{\void}
 206
 207 Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
 208
 209 \membersection{wxFTP::SetTransferMode}
 210
 211 \func{bool}{SetTransferMode}{\param{TransferMode }{mode}}
 212
 213 Sets the transfer mode to the specified one. It will be used for the next
 214 transfer.
 215
 216 If this function is never called, binary transfer mode is used by default.
 217
 218 % ----------------------------------------------------------------------------
 219
 220 \membersection{wxFTP::SetUser}
 221
 222 \func{void}{SetUser}{\param{const wxString\&}{ user}}
 223
 224 Sets the user name to be sent to the FTP server to be allowed to log in.
 225
 226 \wxheading{Default value}
 227
 228 The default value of the user name is "anonymous".
 229
 230 \wxheading{Remark}
 231
 232 This parameter can be included in a URL if you want to use the URL manager.
 233 For example, you can use: "ftp://a\_user:a\_password@a.host:service/a\_directory/a\_file"
 234 to specify a user and a password.
 235
 236 \membersection{wxFTP::SetPassword}
 237
 238 \func{void}{SetPassword}{\param{const wxString\&}{ passwd}}
 239
 240 Sets the password to be sent to the FTP server to be allowed to log in.
 241
 242 \wxheading{Default value}
 243
 244 The default value of the user name is your email address. For example, it could
 245 be "username@userhost.domain". This password is built by getting the current
 246 user name and the host name of the local machine from the system.
 247
 248 \wxheading{Remark}
 249
 250 This parameter can be included in a URL if you want to use the URL manager.
 251 For example, you can use: "ftp://a\_user:a\_password@a.host:service/a\_directory/a\_file"
 252 to specify a user and a password.
 253
 254 % ----------------------------------------------------------------------------
 255
 256 \membersection{wxFTP::FileExists}\label{wxftpfileexists}
 257
 258 \func{bool}{FileExists}{\param{const wxString\&}{ filename}}
 259
 260 Returns {\tt true} if the given remote file exists, {\tt false} otherwise.
 261
 262 \membersection{wxFTP::GetFileSize}\label{wxftpgetfilesize}
 263
 264 \func{int}{GetFileSize}{\param{const wxString\&}{ filename}}
 265
 266 Returns the file size in bytes or $-1$ if the file doesn't exist or the size
 267 couldn't be determined. Notice that this size can be approximative size only
 268 and shouldn't be used for allocating the buffer in which the remote file is
 269 copied, for example.
 270
 271 \membersection{wxFTP::GetDirList}\label{wxftpgetdirlist}
 272
 273 \func{bool}{GetDirList}{\param{wxArrayString\& }{files}, \param{const wxString\&}{ wildcard = ""}}
 274
 275 The GetList function is quite low-level. It returns the list of the files in
 276 the current directory. The list can be filtered using the {\it wildcard} string.
 277 If {\it wildcard} is empty (default), it will return all files in directory.
 278
 279 The form of the list can change from one peer system to another. For example,
 280 for a UNIX peer system, it will look like this:
 281
 282 \begin{verbatim}
 283 -r--r--r--   1 guilhem  lavaux      12738 Jan 16 20:17 cmndata.cpp
 284 -r--r--r--   1 guilhem  lavaux      10866 Jan 24 16:41 config.cpp
 285 -rw-rw-rw-   1 guilhem  lavaux      29967 Dec 21 19:17 cwlex_yy.c
 286 -rw-rw-rw-   1 guilhem  lavaux      14342 Jan 22 19:51 cwy_tab.c
 287 -r--r--r--   1 guilhem  lavaux      13890 Jan 29 19:18 date.cpp
 288 -r--r--r--   1 guilhem  lavaux       3989 Feb  8 19:18 datstrm.cpp
 289 \end{verbatim}
 290
 291 But on Windows system, it will look like this:
 292
 293 \begin{verbatim}
 294 winamp~1 exe    520196 02-25-1999  19:28  winamp204.exe
 295         1 file(s)           520 196 bytes
 296 \end{verbatim}
 297
 298 Return value: true if the file list was successfully retrieved, false
 299 otherwise.
 300
 301 \wxheading{See also}
 302
 303 \helpref{GetFilesList}{wxftpgetfileslist}
 304
 305 \membersection{wxFTP::GetFilesList}\label{wxftpgetfileslist}
 306
 307 \func{bool}{GetFilesList}{\param{wxArrayString\& }{files}, \param{const wxString\&}{ wildcard = ""}}
 308
 309 This function returns the computer-parsable list of the files in the current
 310 directory (optionally only of the files matching the {\it wildcard}, all files
 311 by default). This list always has the same format and contains one full
 312 (including the directory path) file name per line.
 313
 314 Return value: true if the file list was successfully retrieved, false
 315 otherwise.
 316
 317 % ----------------------------------------------------------------------------
 318
 319 \membersection{wxFTP::GetOutputStream}
 320
 321 \func{wxOutputStream *}{GetOutputStream}{\param{const wxString\&}{ file}}
 322
 323 Initializes an output stream to the specified {\it file}. The returned
 324 stream has all but the seek functionality of wxStreams. When the user finishes
 325 writing data, he has to delete the stream to close it.
 326
 327 \wxheading{Return value}
 328
 329 An initialized write-only stream.
 330
 331 \wxheading{See also}
 332
 333 \helpref{wxOutputStream}{wxoutputstream}
 334
 335 % ----------------------------------------------------------------------------
 336
 337 \membersection{wxFTP::GetInputStream}\label{wxftpgetinput}
 338
 339 \func{wxInputStream *}{GetInputStream}{\param{const wxString\&}{ path}}
 340
 341 Creates a new input stream on the the specified path. You can use all but the seek
 342 functionality of wxStream. Seek isn't available on all streams. For example,
 343 http or ftp streams do not deal with it. Other functions like Tell
 344 are not available for this sort of stream, at present.
 345 You will be notified when the EOF is reached by an error.
 346
 347 \wxheading{Return value}
 348
 349 Returns NULL if an error occurred (it could be a network failure or the fact
 350 that the file doesn't exist).
 351
 352 Returns the initialized stream. You will have to delete it yourself when you
 353 don't need it anymore. The destructor closes the DATA stream connection but
 354 will leave the COMMAND stream connection opened. It means that you can still
 355 send new commands without reconnecting.
 356
 357 \wxheading{Example of a standalone connection (without wxURL)}
 358
 359 \begin{verbatim}
 360   wxFTP ftp;
 361   wxInputStream *in_stream;
 362   char *data;
 363
 364   ftp.Connect("a.host.domain");
 365   ftp.ChDir("a_directory");
 366   in_stream = ftp.GetInputStream("a_file_to_get");
 367
 368   data = new char[in_stream->GetSize()];
 369
 370   in_stream->Read(data, in_stream->GetSize());
 371   if (in_stream->LastError() != wxStream_NOERROR) {
 372     // Do something.
 373   }
 374
 375   delete in_stream; /* Close the DATA connection */
 376
 377   ftp.Close(); /* Close the COMMAND connection */
 378 \end{verbatim}
 379
 380 \wxheading{See also}
 381
 382 \helpref{wxInputStream}{wxinputstream}
 383