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