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