1.1 --- a/epoc32/include/ftpsess.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,510 +0,0 @@
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