1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/ftpsess.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,510 @@
1.4 +/**
1.5 +* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +* EPOC32 FTP Engine header file
1.19 +* Author: Philippe Gabriel
1.20 +* Exports set of APIs simplyfying access to the FTP protocol
1.21 +*
1.22 +*
1.23 +*/
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +
1.29 +/**
1.30 + @file FTPSESS.H
1.31 + @internalComponent
1.32 +*/
1.33 +
1.34 +#if !defined(__FTPSESS_H__)
1.35 +#define __FTPSESS_H__
1.36 +#include <e32base.h>
1.37 +#include <es_sock.h>
1.38 +#include <f32file.h>
1.39 +
1.40 +/**
1.41 +The very first release
1.42 +*/
1.43 +
1.44 +/** FTPSESS.DLL major version number. */
1.45 +#define FTPSESS_VERSION_MAJOR 0x01 // The very first release
1.46 +/** FTPSESS.DLL minor version number. */
1.47 +#define FTPSESS_VERSION_MINOR 0x03
1.48 +/** FTPSESS.DLL version number. */
1.49 +#define FTPSESS_VERSION_NUMBER (FTPSESS_VERSION_MAJOR<<8)|FTPSESS_VERSION_MINOR
1.50 +
1.51 +// Following Def as per RFC 959
1.52 +/** Default server port.
1.53 +@internalComponent */
1.54 +const TUint KDefaultServerPiPort = 21;
1.55 +//
1.56 +// MInterface definition to provide callback functions to the client
1.57 +//
1.58 +
1.59 +class MFtpSessionNotifier
1.60 +/** FTP session callback interface.
1.61 +*
1.62 +* An FTP session client implements this interface to receive status and results
1.63 +* from asynchronous FTP operations.
1.64 +*
1.65 +* Note that, as defined in RFC959, FTP does not allow concurrent execution of
1.66 +* several requests. Hence, even though calling an FTP function and getting the
1.67 +* result through this interface are asynchronous operations, these events happen
1.68 +* in a sequential manner. Each notification that the client receives corresponds
1.69 +* to only one currently outstanding operation.
1.70 +* @internalComponent
1.71 +*/
1.72 + {
1.73 +public:
1.74 +//
1.75 +// Operation completion return codes.
1.76 +//
1.77 +/** FTP engine/session operation completeness codes. */
1.78 + enum TOpComp
1.79 + {
1.80 + /** Operation completed normally. */
1.81 + EOpComplete=0, // No error
1.82 + /** Operation cancelled. */
1.83 + EOpCanceled, // User canceled last operation
1.84 +
1.85 + //Connection errors
1.86 + /** Connection error: Connect address invalid. */
1.87 + EHostNotExist, // Connect address invalid
1.88 + /** Connection error: Sockets level error. */
1.89 + ESocketError, // Problem with socket operation
1.90 + /** Connection error: Connection failed. */
1.91 + EConnectionFailed, // Can't connect to FTP port
1.92 + /** Connection error: Password needed. */
1.93 + EPasswordNeeded,
1.94 + /** Connection error: Anonymous login not permitted. */
1.95 + EAccountNeeded, // i.e. anonymous login disallowed
1.96 + /** Connection error: UserName, Password combination invalid. */
1.97 + ELoginFailed, // UserName,Password combination invalid
1.98 + /** Connection error: Not connected to a server. */
1.99 + ENotConnected, // Not connected to a server
1.100 + /** Connection error: Already connected to a server. */
1.101 + EAlreadyConnected, // Already connected to a server
1.102 + /** Connection error: Operation timed out. */
1.103 + ETimedOut, // Inactive for too long
1.104 +
1.105 + //Local filesystem errors
1.106 + /** Local filesystem error: General file system error. */
1.107 + EFileSystemError,
1.108 + /** Local filesystem error: File opening failure. */
1.109 + EFileOpenFailure,
1.110 + /** Local filesystem error: File reading failure. */
1.111 + EFileReadError,
1.112 + /** Local filesystem error: File writing failure. */
1.113 + EFileWriteError,
1.114 + /** Local filesystem error: File already exists. */
1.115 + EFileAlreadyExist,
1.116 + /** Local filesystem error: File does not exist. */
1.117 + EFileNotExist,
1.118 + /** Local filesystem error: Directory already exists. */
1.119 + EDirAlreadyExist,
1.120 + /** Local filesystem error: Directory does not exist. */
1.121 + EDirNotExist,
1.122 +
1.123 + // Permission error
1.124 + /** Permission error: Permission denied. */
1.125 + EPermissionDenied,
1.126 +
1.127 + //Remote filesystem errors
1.128 + /** Remote filesystem error: General remote file system error. */
1.129 + ERemoteFileSystemError,
1.130 + /** Remote filesystem error: Remote file opening failure. */
1.131 + ERemoteFileOpenFailure,
1.132 + /** Remote filesystem error: Remote file reading failure. */
1.133 + ERemoteFileReadError,
1.134 + /** Remote filesystem error: Remote file writing failure. */
1.135 + ERemoteFileWriteError,
1.136 + /** Remote filesystem error: Remote file already exists. */
1.137 + ERemoteFileAlreadyExist,
1.138 + /** Remote filesystem error: Remote file does not exist. */
1.139 + ERemoteFileNotExist,
1.140 + /** Remote filesystem error: Remote directory already exists. */
1.141 + ERemoteDirAlreadyExist,
1.142 + /** Remote filesystem error: Remote directory does not exist. */
1.143 + ERemoteDirNotExist,
1.144 + /** Remote filesystem error: Restart is not supported. */
1.145 + ERestartNotSupported
1.146 + };
1.147 +
1.148 + /** Normal operation completion. */
1.149 + virtual void Complete(void)=0;
1.150 +
1.151 + // Operation completed, more data to follow
1.152 + /** Operation partially completed, with more data to follow. */
1.153 + virtual void MoreData(void)=0;
1.154 +
1.155 + /** Reports the amount of data already transferred in bytes.
1.156 + *
1.157 + * @param aProgress Amount of data already transferred */
1.158 + virtual void TransferProgress(TUint aProgress)=0;
1.159 +
1.160 + /** User cancelled an on-going operation. */
1.161 + virtual void Cancel(void)=0;
1.162 +
1.163 + /** Peer reset the connection. */
1.164 + virtual void ConnReset(void)=0;
1.165 +
1.166 + /** Error in establishing the connection with the FTP server.
1.167 + *
1.168 + * @param aTConnectionError Operation completion code */
1.169 + virtual void ConnectionError(TOpComp aTConnectionError)=0;
1.170 +
1.171 + // FTP server does not implement the operation requested
1.172 + /** Restart operation not supported. */
1.173 + virtual void OperationNotSupported(void)=0;
1.174 +
1.175 + // Local File system error
1.176 + /** Error with the local file system.
1.177 + *
1.178 + * @param aTLocalFileSystemError Operation completion code */
1.179 + virtual void LocalFileSystemError(TOpComp aTLocalFileSystemError)=0;
1.180 +
1.181 + // Remote File system error
1.182 + /** Error with the remote file system.
1.183 + *
1.184 + * @param aTRemoteFileSystemError Operation completion code */
1.185 + virtual void RemoteFileSystemError(TOpComp aTRemoteFileSystemError)=0;
1.186 +
1.187 + // Not specified yet
1.188 + /** Unspecified error. */
1.189 + virtual void EUnknownError()=0;
1.190 +
1.191 + // Message reported by server
1.192 +/** Message sent by the FTP server.
1.193 +*
1.194 +* As specified by the RFC, the server answers all requests from the
1.195 +* client with a plain text message beginning with a 3 digit code.
1.196 +* The error/completion notifications sent back by the FTP session API
1.197 +* are derived from these codes. Additionally, this function can be
1.198 +* used to get the full string reporting the result of the request.
1.199 +* It is recommended that the user interface displays this string to
1.200 +* the user, as this gives a more precise idea of the result of the
1.201 +* requested operation, especially in case of error.
1.202 +*
1.203 +* @param TDesC8 The message sent by the server */
1.204 + virtual void ServerMessage(const TDesC8&)=0;
1.205 + };
1.206 +//
1.207 +// The CFTPSession class
1.208 +//
1.209 +class CFTPSession : public CBase
1.210 +
1.211 +/** Abstracts the complexity of the full FTP protocol and exports only
1.212 +* a few simplified APIs.
1.213 +* @internalComponent */
1.214 + {
1.215 +public:
1.216 +/** FTP connection mode (passive or active see RFC959). */
1.217 + enum TConnectionMode
1.218 + {
1.219 + /** Active mode. Server initiates DTP connection to client. */
1.220 + EActive=0, //(see RFC959)
1.221 + /** Passive mode. Client initiates DTP connection to server.*/
1.222 + Epassive //(see RFC959)
1.223 + };
1.224 +/** Representation type of a transferred file. */
1.225 + enum RepresentationType
1.226 + {
1.227 + /** Uninitialised. */
1.228 + EUninitialised=0,
1.229 + /** File transfered in Binary mode, no translation. */
1.230 + EBinary,
1.231 + /** File transfered in ASCII mode, translation. */
1.232 + EASCII
1.233 + };
1.234 +/** FTP file transfer mode. */
1.235 + enum TransferMode
1.236 + {
1.237 + /** Stream mode; file transfered as a stream of bytes. */
1.238 + EStream=0,
1.239 + /** Block mode; file transfered as blocks, with header needed to restart aborted transfer. */
1.240 + Eblock
1.241 + };
1.242 +/** FTP file open mode. */
1.243 + enum TOpenMode
1.244 + {
1.245 + /** Overwrite existing file. */
1.246 + EOverwrite,
1.247 + /** Do not overwrite existing file. */
1.248 + ENoOverwrite,
1.249 + /** Expand existing file. */
1.250 + EExpand
1.251 + };
1.252 +
1.253 +/** Construction */
1.254 +public:
1.255 +
1.256 +//
1.257 +// Connection APIs
1.258 +//
1.259 +// Establish a connection with a server:
1.260 + /** Connects to a remote FTP server, specifying the FTP server by a numeric IP
1.261 + * address.
1.262 + *
1.263 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.264 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(),
1.265 + * or MFtpSessionNotifier::EUnknownError().
1.266 + *
1.267 + * @param aNetAddr FTP server's IP address
1.268 + * @param aUserName User name to log on the FTP server
1.269 + * @param aPassword Password to identify to the FTP server
1.270 + * @param aConnectionMode Connection mode (passive or active, see RFC959).
1.271 + * You must use passive mode if the client is behind a firewall. */
1.272 + virtual void Connect( const TSockAddr& aNetAddr, //IP address
1.273 + const TDesC8& aUserName,
1.274 + const TDesC8& aPassword,
1.275 + const TConnectionMode aConnectionMode=EActive)=0;
1.276 +
1.277 +
1.278 + /** Connects to a remote FTP server, specifying the FTP server by a DNS name.
1.279 + *
1.280 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.281 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(),
1.282 + * or MFtpSessionNotifier::EUnknownError().
1.283 + *
1.284 + * @param aServerName FTP server's DNS name
1.285 + * @param aUserName User name to log on the FTP server
1.286 + * @param aPassword Password to identify to the FTP server
1.287 + * @param aConnectionMode Connection mode (passive or active, see RFC959). You
1.288 + * must use passive mode if the client is behind a firewall.
1.289 + * @param aPort Port to connect to initiate the PI connection (see RFC959) */
1.290 + virtual void Connect( const THostName& aServerName, //DNS name
1.291 + const TDesC8& aUserName,
1.292 + const TDesC8& aPassword,
1.293 + const TConnectionMode aConnectionMode=EActive,
1.294 + const TUint aPort=KDefaultServerPiPort)=0;
1.295 +
1.296 +
1.297 +// Close connection with a server
1.298 + /** Closes the current connection with the FTP server.
1.299 + *
1.300 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.301 + * MFtpSessionNotifier::ConnReset(), or MFtpSessionNotifier::EUnknownError().
1.302 + *
1.303 + * This cannot be called when an operation is in progress. */
1.304 + virtual void Close()=0;
1.305 +
1.306 +
1.307 +// Cancel last FTP operation
1.308 + /** Cancels the last FTP operation.
1.309 + *
1.310 + * Cancel is only implemented for lengthy operations, that is: Connect(), Store(),
1.311 + * Retrieve(), and ListDirectory(). For these operations, once cancel has been
1.312 + * called, the MFtpSessionNotifier::Cancel() callback is called.
1.313 + *
1.314 + * For other operations, calling Cancel() has no effect (it would take longer to
1.315 + * wait for an acknowledgement to the Cancel(), than waiting for the result of
1.316 + * the current operation). However, a completion callback will be called, as
1.317 + * well as MFtpSessionNotifier::Cancel(). */
1.318 + virtual void Cancel()=0;
1.319 +
1.320 +
1.321 +// Restart an aborted transfer operation
1.322 + /** After a connection is re-established, restarts the last aborted transfer operation
1.323 + * (i.e. Store/Retrieve).
1.324 + *
1.325 + * It is the responsibility of the client to remember and reset the state of
1.326 + * the connection before attempting to resume the transfer: i.e. the client should
1.327 + * re-establish the connection to the server and return to the relevant directory,
1.328 + * then it should issue the Restart() command with the offset it has saved, and
1.329 + * then issue the Store() or Retrieve() command.
1.330 + *
1.331 + * The Restart() command should be avoided if the transfer was done in ASCII mode,
1.332 + * as, because the server peforms a conversion on the bytestream format that
1.333 + * it gets from the file before sending, the file size on the receiving end will
1.334 + * be different than the size on the sending end. This means it is not possible
1.335 + * to compute an offset for the sending end.
1.336 + *
1.337 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.338 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::OperationNotSupported(),
1.339 + * or MFtpSessionNotifier::EUnknownError().
1.340 + *
1.341 + * @param aTFTPRestartOffset An offset in bytes in the file from where transfer
1.342 + * is to be resumed */
1.343 + virtual void Restart(const TUint aTFTPRestartOffset)=0;
1.344 +
1.345 +//
1.346 +// Transfer APIs
1.347 +//
1.348 +// Store a file on the server
1.349 + /** Transfers a file to the FTP server.
1.350 + *
1.351 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.352 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(),
1.353 + * MFtpSessionNotifier::LocalFileSystemError(), MFtpSessionNotifier::RemoteFileSystemError()
1.354 + * or MFtpSessionNotifier::EUnknownError().
1.355 + *
1.356 + * @param aLocalFileName Name of the local file to be transferred
1.357 + * @param aNewRemoteFileName Name of the remote file to be created
1.358 + * @param aOverwrite If ETrue, overwrite a remote file with the same name if it
1.359 + * exists; if EFalse, fail if a remote file with the same name exists
1.360 + * @param aRepresentationType The representation type of the transferred file, ASCII or Binary
1.361 + * @param aTransferMode The transfer mode, stream mode or block mode. This is
1.362 + * ignored and assumed to be stream, as block mode seems to be obsolete. */
1.363 + virtual void Store( const TDesC& aLocalFileName,
1.364 + const TDesC8& aNewRemoteFileName,
1.365 + const TBool aOverwrite = EFalse,
1.366 + const RepresentationType aRepresentationType = EBinary,
1.367 + const TransferMode aTransferMode = EStream)=0;
1.368 +
1.369 +
1.370 +// Get a file from the server
1.371 + /** Transfers a file from the FTP server.
1.372 + *
1.373 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.374 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::LocalFileSystemError(),
1.375 + * MFtpSessionNotifier::RemoteFileSystemError() or MFtpSessionNotifier::EUnknownError().
1.376 + *
1.377 + * @param aRemoteFileName The remote file Name
1.378 + * @param aNewLocalFileName Name of the local file to be created
1.379 + * @param aOpenMode Specifies whether to overwrite a local file with the same
1.380 + * name if it already exists
1.381 + * @param aRepresentationType The representation type of the transferred file,
1.382 + * ASCII or Binary
1.383 + * @param aTransferMode The transfer mode, stream mode or block mode. This is
1.384 + * ignored and assumed to be stream, as block mode seems to be obsolete. */
1.385 + virtual void Retrieve( const TDesC8& aRemoteFileName,
1.386 + const TDesC& aNewLocalFileName,
1.387 + const TOpenMode aOpenMode = EOverwrite,
1.388 + const RepresentationType aRepresentationType = EBinary,
1.389 + const TransferMode aTransferMode = EStream)=0;
1.390 +
1.391 +
1.392 +//
1.393 +// File system management functions
1.394 +//
1.395 + /** Sets the current directory on the remote file system.
1.396 + *
1.397 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.398 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.399 + * or MFtpSessionNotifier::EUnknownError().
1.400 + *
1.401 + * @param aDirectoryName Directory name */
1.402 + virtual void ChangeDirectory(const TDesC8& aDirectoryName)=0;
1.403 +
1.404 +
1.405 + /** Creates a directory on the remote file system.
1.406 + *
1.407 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.408 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.409 + * or MFtpSessionNotifier::EUnknownError().
1.410 + *
1.411 + * @param aDirectoryName A directory name. This can be absolute or relative. */
1.412 + virtual void CreateDirectory(const TDesC8& aDirectoryName)=0;
1.413 +
1.414 +
1.415 + /** Deletes a directory on the remote file system.
1.416 + *
1.417 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.418 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.419 + * or MFtpSessionNotifier::EUnknownError().
1.420 + *
1.421 + * @param aDirectoryName A directory name. This can be absolute or relative. */
1.422 + virtual void DeleteDirectory(const TDesC8& aDirectoryName)=0;
1.423 +
1.424 +
1.425 + /** Gets the client's current directory on the remote file system.
1.426 + *
1.427 + * The result is returned to the MFtpSessionNotifier::ServerMessage() callback.
1.428 + * The directory name is defined by the RFC as being enclosed between double
1.429 + * quotes: for example, an answer will look like:
1.430 + *
1.431 + * @code
1.432 + * 257 "/developr/rfc" is current directory.
1.433 + * @endcode
1.434 + * The client must implement a parser to find the text between quotes.
1.435 + *
1.436 + * The result can be passed in two or more consecutive calls of MFtpSessionNotifier::ServerMessage().
1.437 + * For example:
1.438 + *
1.439 + * First call of MFtpSessionNotifier::ServerMessage(): @code 257 "/developr @endcode
1.440 + *
1.441 + * Second call of MFtpSessionNotifier::ServerMessage(): @code /rfc" is current directory. @endcode
1.442 + *
1.443 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.444 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.445 + * or MFtpSessionNotifier::EUnknownError(). */
1.446 + virtual void GetCurrentDirectory(void)=0;
1.447 +
1.448 +
1.449 + /** Lists the files in a directory on the remote file system.
1.450 + *
1.451 + * On successful completion, the aFileList buffer contains the list of files
1.452 + * as transmitted by the server. It is the responsibility of the client to parse
1.453 + * this buffer to extract relevant information. aFileList is always appended
1.454 + * to, so the client should set its current length to a meaningful value (i.e.
1.455 + * 0, to fill the buffer from scratch).
1.456 + *
1.457 + * If the list of files is larger than the aFileList buffer, MFtpSessionNotifier::MoreData()
1.458 + * is called. At this point, the client must reissue the ListDirectory() request
1.459 + * until the MFtpSessionNotifier::Complete() is called.
1.460 + *
1.461 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.462 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.463 + * or MFtpSessionNotifier::EUnknownError().
1.464 + *
1.465 + * @param aDirectoryName A directory name. This can be absolute or relative.
1.466 + * @param aFileList On completion, the file list. The buffer is allocated by the client. */
1.467 + virtual void ListDirectory(const TDesC8& aDirectoryName,
1.468 + TDes8& aFileList)=0;
1.469 +
1.470 +
1.471 + /** Deletes a file on the remote file system.
1.472 + *
1.473 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.474 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.475 + * or MFtpSessionNotifier::EUnknownError().
1.476 + *
1.477 + * @param aFileName A file name */
1.478 + virtual void DeleteFile(const TDesC8& aFileName)=0;
1.479 +
1.480 + /** Renames a file on the remote file system.
1.481 + *
1.482 + * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
1.483 + * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
1.484 + * or MFtpSessionNotifier::EUnknownError().
1.485 + *
1.486 + * @param aRemoteFileName An existing file name
1.487 + * @param aNewRemoteFileName A new file name */
1.488 + virtual void RenameFile(const TDesC8& aRemoteFileName,
1.489 + const TDesC8& aNewRemoteFileName)=0;
1.490 +
1.491 +
1.492 + /**
1.493 + Returns 32-bit, with
1.494 + ftpsess dll MAJOR_VERSION in msb of the msw
1.495 + ftpsess dll MINOR_VERSION in lsb of the msw
1.496 + ftpprot dll MAJOR_VERSION in msb of the lsw
1.497 + ftpprot dll MINOR_VERSION in lsb of the lsw
1.498 + */
1.499 + IMPORT_C static TUint32 GetVersion(void);
1.500 +
1.501 + /** Allocates and constructs a new FTP session object.
1.502 + *
1.503 + * @param aNotifier Callback interface to notify the client of the completion of
1.504 + * operations or to report errors. For each FTP session, the FTP
1.505 + * client should instantiate an object of this type.
1.506 + * @return New FTP session object
1.507 + */
1.508 + IMPORT_C static CFTPSession* NewL(MFtpSessionNotifier* aNotifier);
1.509 +
1.510 + /**Destructor.*/
1.511 + virtual ~CFTPSession();
1.512 +};
1.513 +#endif