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:     wxWindows 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
 107 \membersection{wxFTP::wxFTP}\label{wxftpctor}
 108
 109 \func{}{wxFTP}{\void}
 110
 111 Default constructor.
 112
 113
 114 \membersection{wxFTP::\destruct{wxFTP}}\label{wxftpdtor}
 115
 116 \func{}{\destruct{wxFTP}}{\void}
 117
 118 Destructor will close the connection if connected.
 119
 120
 121 \membersection{wxFTP::Abort}\label{wxftpabort}
 122
 123 \func{bool}{Abort}{\void}
 124
 125 Aborts the download currently in process, returns \true if ok, \false
 126 if an error occurred.
 127
 128
 129 \membersection{wxFTP::CheckCommand}\label{wxftpcheckcommand}
 130
 131 \func{bool}{CheckCommand}{\param{const wxString\&}{ command}, \param{char }{ret}}
 132
 133 Send the specified {\it command} to the FTP server. {\it ret} specifies
 134 the expected result.
 135
 136 \wxheading{Return value}
 137
 138 true if the command has been sent successfully, else false.
 139
 140
 141 \membersection{wxFTP::SendCommand}\label{wxftpsendcommand}
 142
 143 \func{char}{SendCommand}{\param{const wxString\&}{ command}}
 144
 145 Send the specified {\it command} to the FTP server and return the first
 146 character of the return code.
 147
 148
 149 \membersection{wxFTP::GetLastResult}\label{wxftpgetlastresult}
 150
 151 \func{const wxString\&}{GetLastResult}{\void}
 152
 153 Returns the last command result, i.e. the full server reply for the last
 154 command.
 155
 156 % ----------------------------------------------------------------------------
 157
 158
 159 \membersection{wxFTP::ChDir}\label{wxftpchdir}
 160
 161 \func{bool}{ChDir}{\param{const wxString\&}{ dir}}
 162
 163 Change the current FTP working directory.
 164 Returns true if successful.
 165
 166
 167 \membersection{wxFTP::MkDir}\label{wxftpmkdir}
 168
 169 \func{bool}{MkDir}{\param{const wxString\&}{ dir}}
 170
 171 Create the specified directory in the current FTP working directory.
 172 Returns true if successful.
 173
 174
 175 \membersection{wxFTP::RmDir}\label{wxftprmdir}
 176
 177 \func{bool}{RmDir}{\param{const wxString\&}{ dir}}
 178
 179 Remove the specified directory from the current FTP working directory.
 180 Returns true if successful.
 181
 182
 183 \membersection{wxFTP::Pwd}\label{wxftppwd}
 184
 185 \func{wxString}{Pwd}{\void}
 186
 187 Returns the current FTP working directory.
 188
 189 % ----------------------------------------------------------------------------
 190
 191
 192 \membersection{wxFTP::Rename}\label{wxftprename}
 193
 194 \func{bool}{Rename}{\param{const wxString\&}{ src}, \param{const wxString\&}{ dst}}
 195
 196 Rename the specified {\it src} element to {\it dst}. Returns true if successful.
 197
 198 % ----------------------------------------------------------------------------
 199
 200
 201 \membersection{wxFTP::RmFile}\label{wxftprmfile}
 202
 203 \func{bool}{RmFile}{\param{const wxString\&}{ path}}
 204
 205 Delete the file specified by {\it path}. Returns true if successful.
 206
 207 % ----------------------------------------------------------------------------
 208
 209
 210 \membersection{wxFTP::SetAscii}\label{wxftpsetascii}
 211
 212 \func{bool}{SetAscii}{\void}
 213
 214 Sets the transfer mode to ASCII. It will be used for the next transfer.
 215
 216
 217 \membersection{wxFTP::SetBinary}\label{wxftpsetbinary}
 218
 219 \func{bool}{SetBinary}{\void}
 220
 221 Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
 222
 223
 224 \membersection{wxFTP::SetPassive}\label{wxftpsetpassive}
 225
 226 \func{void}{SetPassive}{\param{bool }{pasv}}
 227
 228 If \arg{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
 234 \membersection{wxFTP::SetTransferMode}\label{wxftpsettransfermode}
 235
 236 \func{bool}{SetTransferMode}{\param{TransferMode }{mode}}
 237
 238 Sets the transfer mode to the specified one. It will be used for the next
 239 transfer.
 240
 241 If this function is never called, binary transfer mode is used by default.
 242
 243 % ----------------------------------------------------------------------------
 244
 245
 246 \membersection{wxFTP::SetUser}\label{wxftpsetuser}
 247
 248 \func{void}{SetUser}{\param{const wxString\&}{ user}}
 249
 250 Sets the user name to be sent to the FTP server to be allowed to log in.
 251
 252 \wxheading{Default value}
 253
 254 The default value of the user name is "anonymous".
 255
 256 \wxheading{Remark}
 257
 258 This parameter can be included in a URL if you want to use the URL manager.
 259 For example, you can use: "ftp://a\_user:a\_password@a.host:service/a\_directory/a\_file"
 260 to specify a user and a password.
 261
 262
 263 \membersection{wxFTP::SetPassword}\label{wxftpsetpassword}
 264
 265 \func{void}{SetPassword}{\param{const wxString\&}{ passwd}}
 266
 267 Sets the password to be sent to the FTP server to be allowed to log in.
 268
 269 \wxheading{Default value}
 270
 271 The default value of the user name is your email address. For example, it could
 272 be "username@userhost.domain". This password is built by getting the current
 273 user name and the host name of the local machine from the system.
 274
 275 \wxheading{Remark}
 276
 277 This parameter can be included in a URL if you want to use the URL manager.
 278 For example, you can use: "ftp://a\_user:a\_password@a.host:service/a\_directory/a\_file"
 279 to specify a user and a password.
 280
 281 % ----------------------------------------------------------------------------
 282
 283
 284 \membersection{wxFTP::FileExists}\label{wxftpfileexists}
 285
 286 \func{bool}{FileExists}{\param{const wxString\&}{ filename}}
 287
 288 Returns \true if the given remote file exists, \false otherwise.
 289
 290
 291 \membersection{wxFTP::GetFileSize}\label{wxftpgetfilesize}
 292
 293 \func{int}{GetFileSize}{\param{const wxString\&}{ filename}}
 294
 295 Returns the file size in bytes or $-1$ if the file doesn't exist or the size
 296 couldn't be determined. Notice that this size can be approximative size only
 297 and shouldn't be used for allocating the buffer in which the remote file is
 298 copied, for example.
 299
 300
 301 \membersection{wxFTP::GetDirList}\label{wxftpgetdirlist}
 302
 303 \func{bool}{GetDirList}{\param{wxArrayString\& }{files}, \param{const wxString\&}{ wildcard = ""}}
 304
 305 The GetList function is quite low-level. It returns the list of the files in
 306 the current directory. The list can be filtered using the {\it wildcard} string.
 307 If {\it wildcard} is empty (default), it will return all files in directory.
 308
 309 The form of the list can change from one peer system to another. For example,
 310 for a UNIX peer system, it will look like this:
 311
 312 \begin{verbatim}
 313 -r--r--r--   1 guilhem  lavaux      12738 Jan 16 20:17 cmndata.cpp
 314 -r--r--r--   1 guilhem  lavaux      10866 Jan 24 16:41 config.cpp
 315 -rw-rw-rw-   1 guilhem  lavaux      29967 Dec 21 19:17 cwlex_yy.c
 316 -rw-rw-rw-   1 guilhem  lavaux      14342 Jan 22 19:51 cwy_tab.c
 317 -r--r--r--   1 guilhem  lavaux      13890 Jan 29 19:18 date.cpp
 318 -r--r--r--   1 guilhem  lavaux       3989 Feb  8 19:18 datstrm.cpp
 319 \end{verbatim}
 320
 321 But on Windows system, it will look like this:
 322
 323 \begin{verbatim}
 324 winamp~1 exe    520196 02-25-1999  19:28  winamp204.exe
 325         1 file(s)           520 196 bytes
 326 \end{verbatim}
 327
 328 Return value: true if the file list was successfully retrieved, false
 329 otherwise.
 330
 331 \wxheading{See also}
 332
 333 \helpref{GetFilesList}{wxftpgetfileslist}
 334
 335
 336 \membersection{wxFTP::GetFilesList}\label{wxftpgetfileslist}
 337
 338 \func{bool}{GetFilesList}{\param{wxArrayString\& }{files}, \param{const wxString\&}{ wildcard = ""}}
 339
 340 This function returns the computer-parsable list of the files in the current
 341 directory (optionally only of the files matching the {\it wildcard}, all files
 342 by default). This list always has the same format and contains one full
 343 (including the directory path) file name per line.
 344
 345 Return value: true if the file list was successfully retrieved, false
 346 otherwise.
 347
 348 % ----------------------------------------------------------------------------
 349
 350
 351 \membersection{wxFTP::GetOutputStream}\label{wxftpgetoutputstream}
 352
 353 \func{wxOutputStream *}{GetOutputStream}{\param{const wxString\&}{ file}}
 354
 355 Initializes an output stream to the specified {\it file}. The returned
 356 stream has all but the seek functionality of wxStreams. When the user finishes
 357 writing data, he has to delete the stream to close it.
 358
 359 \wxheading{Return value}
 360
 361 An initialized write-only stream.
 362
 363 \wxheading{See also}
 364
 365 \helpref{wxOutputStream}{wxoutputstream}
 366
 367 % ----------------------------------------------------------------------------
 368
 369
 370 \membersection{wxFTP::GetInputStream}\label{wxftpgetinputstream}
 371
 372 \func{wxInputStream *}{GetInputStream}{\param{const wxString\&}{ path}}
 373
 374 Creates a new input stream on the specified path. You can use all but the seek
 375 functionality of wxStream. Seek isn't available on all streams. For example,
 376 HTTP or FTP streams do not deal with it. Other functions like Tell
 377 are not available for this sort of stream, at present.
 378 You will be notified when the EOF is reached by an error.
 379
 380 \wxheading{Return value}
 381
 382 Returns NULL if an error occurred (it could be a network failure or the fact
 383 that the file doesn't exist).
 384
 385 Returns the initialized stream. You will have to delete it yourself when you
 386 don't need it anymore. The destructor closes the DATA stream connection but
 387 will leave the COMMAND stream connection opened. It means that you can still
 388 send new commands without reconnecting.
 389
 390 \wxheading{Example of a standalone connection (without wxURL)}
 391
 392 \begin{verbatim}
 393   wxFTP ftp;
 394   wxInputStream *in_stream;
 395   char *data;
 396
 397   ftp.Connect("a.host.domain");
 398   ftp.ChDir("a_directory");
 399   in_stream = ftp.GetInputStream("a_file_to_get");
 400
 401   data = new char[in_stream->GetSize()];
 402
 403   in_stream->Read(data, in_stream->GetSize());
 404   if (in_stream->LastError() != wxStream_NOERROR) {
 405     // Do something.
 406   }
 407
 408   delete in_stream; /* Close the DATA connection */
 409
 410   ftp.Close(); /* Close the COMMAND connection */
 411 \end{verbatim}
 412
 413 \wxheading{See also}
 414
 415 \helpref{wxInputStream}{wxinputstream}
 416