/**
* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
* EPOC32 FTP Engine header file
* Author:	Philippe Gabriel
* Exports set of APIs simplyfying access to the FTP protocol
* 
*
*/



/**
 @file FTPSESS.H
 @internalComponent
*/

#if !defined(__FTPSESS_H__)
#define __FTPSESS_H__
#include <e32base.h>
#include <es_sock.h>
#include <f32file.h>

/**
The very first release
*/

/** FTPSESS.DLL major version number. */
#define FTPSESS_VERSION_MAJOR 0x01 // The very first release
/** FTPSESS.DLL minor version number. */
#define FTPSESS_VERSION_MINOR 0x03
/** FTPSESS.DLL version number. */
#define FTPSESS_VERSION_NUMBER (FTPSESS_VERSION_MAJOR<<8)|FTPSESS_VERSION_MINOR

// Following Def as per RFC 959
/** Default server port.
@internalComponent */
const TUint KDefaultServerPiPort = 21;
//
// MInterface definition to provide callback functions to the client
//

class MFtpSessionNotifier
/** FTP session callback interface.
*
* An FTP session client implements this interface to receive status and results 
* from asynchronous FTP operations.
* 
* Note that, as defined in RFC959, FTP does not allow concurrent execution of 
* several requests. Hence, even though calling an FTP function and getting the 
* result through this interface are asynchronous operations, these events happen 
* in a sequential manner. Each notification that the client receives corresponds 
* to only one currently outstanding operation.
* @internalComponent
*/
	{
public:
//
// Operation completion return codes.
// 
/** FTP engine/session operation completeness codes. */
	enum TOpComp 
		{
	/** Operation completed normally. */
		EOpComplete=0,	// No error
	/** Operation cancelled. */
		EOpCanceled,	// User canceled last operation

		//Connection errors
	/** Connection error: Connect address invalid. */
		EHostNotExist,	// Connect address invalid
	/** Connection error: Sockets level error. */
		ESocketError,	// Problem with socket operation
	/** Connection error: Connection failed. */
		EConnectionFailed,	// Can't connect to FTP port
	/** Connection error: Password needed. */
		EPasswordNeeded,
	/** Connection error: Anonymous login not permitted. */
		EAccountNeeded,	// i.e. anonymous login disallowed
	/** Connection error: UserName, Password combination invalid. */
		ELoginFailed,	// UserName,Password combination invalid
	/** Connection error: Not connected to a server. */
		ENotConnected,	// Not connected to a server
	/** Connection error: Already connected to a server. */
		EAlreadyConnected,	// Already connected to a server
	/** Connection error: Operation timed out. */
		ETimedOut,	// Inactive for too long

		//Local filesystem errors
	/** Local filesystem error: General file system error. */
		EFileSystemError, 
	/** Local filesystem error: File opening failure. */
		EFileOpenFailure, 
	/** Local filesystem error: File reading failure. */
		EFileReadError, 
	/** Local filesystem error: File writing failure. */
		EFileWriteError,
	/** Local filesystem error: File already exists. */
		EFileAlreadyExist,
	/** Local filesystem error: File does not exist. */
		EFileNotExist,
	/** Local filesystem error: Directory already exists. */
		EDirAlreadyExist,
	/** Local filesystem error: Directory does not exist. */
		EDirNotExist,

		// Permission error
	/** Permission error: Permission denied. */
		EPermissionDenied,

		//Remote filesystem errors
	/** Remote filesystem error: General remote file system error. */
		ERemoteFileSystemError, 
	/** Remote filesystem error: Remote file opening failure. */
		ERemoteFileOpenFailure, 
	/** Remote filesystem error: Remote file reading failure. */
		ERemoteFileReadError, 
	/** Remote filesystem error: Remote file writing failure. */
		ERemoteFileWriteError,
	/** Remote filesystem error: Remote file already exists. */
		ERemoteFileAlreadyExist,
	/** Remote filesystem error: Remote file does not exist. */
		ERemoteFileNotExist,
	/** Remote filesystem error: Remote directory already exists. */
		ERemoteDirAlreadyExist,
	/** Remote filesystem error: Remote directory does not exist. */
		ERemoteDirNotExist,
	/** Remote filesystem error: Restart is not supported. */
		ERestartNotSupported
		};

	/** Normal operation completion. */
	virtual void Complete(void)=0;

	// Operation completed, more data to follow
	/** Operation partially completed, with more data to follow. */
	virtual void MoreData(void)=0;

	/** Reports the amount of data already transferred in bytes.
	* 
	* @param aProgress	Amount of data already transferred */
	virtual void TransferProgress(TUint aProgress)=0;

	/** User cancelled an on-going operation. */
	virtual void Cancel(void)=0;

	/** Peer reset the connection. */
	virtual void ConnReset(void)=0;

	/** Error in establishing the connection with the FTP server.
	* 
	* @param aTConnectionError	Operation completion code */
	virtual void ConnectionError(TOpComp aTConnectionError)=0;

	// FTP server does not implement the operation requested
	/** Restart operation not supported. */
	virtual void OperationNotSupported(void)=0;

	// Local File system error
	/** Error with the local file system.
	* 
	* @param aTLocalFileSystemError	Operation completion code */
	virtual void LocalFileSystemError(TOpComp aTLocalFileSystemError)=0;

	// Remote File system error
	/** Error with the remote file system.
	* 
	* @param aTRemoteFileSystemError	Operation completion code */
	virtual void RemoteFileSystemError(TOpComp aTRemoteFileSystemError)=0;

	// Not specified yet
	/** Unspecified error. */
	virtual void EUnknownError()=0;

	// Message reported by server
/** Message sent by the FTP server.
* 
* As specified by the RFC, the server answers all requests from the 
* client with a plain text message beginning with a 3 digit code.
* The error/completion notifications sent back by the FTP session API 
* are derived from these codes. Additionally, this function can be 
* used to get the full string reporting the result of the request. 
* It is recommended that the user interface displays this string to 
* the user, as this gives a more precise idea of the result of the 
* requested operation, especially in case of error.
* 
* @param TDesC8	The message sent by the server */
	virtual void ServerMessage(const TDesC8&)=0;
    	};		
//
// The CFTPSession class
//
class CFTPSession : public CBase

/** Abstracts the complexity of the full FTP protocol and exports only 
* a few simplified APIs.
* @internalComponent */
	{
public:
/** FTP connection mode (passive or active see RFC959). */
	enum TConnectionMode 
		{
	/** Active mode. Server initiates DTP connection to client. */
		EActive=0, //(see RFC959)
	/** Passive mode. Client initiates DTP connection to server.*/
		Epassive   //(see RFC959)
		};
/** Representation type of a transferred file. */
	enum RepresentationType
		{
	/** Uninitialised. */
		EUninitialised=0,						   
	/** File transfered in Binary mode, no translation. */
		EBinary,
	/** File transfered in ASCII mode, translation. */
		EASCII
		};
/** FTP file transfer mode. */
	enum TransferMode
		{
	/** Stream mode; file transfered as a stream of bytes. */
		EStream=0,
	/** Block mode; file transfered as blocks, with header needed to restart aborted transfer. */
		Eblock 
		};
/** FTP file open mode. */
	enum TOpenMode
		{
	/** Overwrite existing file. */
		EOverwrite,
	/** Do not overwrite existing file. */
		ENoOverwrite,
	/** Expand existing file. */
		EExpand
		};

/** Construction */
public:

//
// Connection APIs
//
// Establish a connection with a server:
	/** Connects to a remote FTP server, specifying the FTP server by a numeric IP 
	* address.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(), 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aNetAddr			FTP server's IP address
	* @param aUserName			User name to log on the FTP server
	* @param aPassword			Password to identify to the FTP server
	* @param aConnectionMode	Connection mode (passive or active, see RFC959). 
	* 							You must use passive mode if the client is behind a firewall. */
	virtual void Connect(	const TSockAddr& aNetAddr, //IP address
							const TDesC8& aUserName, 
							const TDesC8& aPassword,
							const TConnectionMode aConnectionMode=EActive)=0;


	/** Connects to a remote FTP server, specifying the FTP server by a DNS name.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(), 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aServerName		FTP server's DNS name
	* @param aUserName			User name to log on the FTP server
	* @param aPassword			Password to identify to the FTP server
	* @param aConnectionMode	Connection mode (passive or active, see RFC959). You 
	* 							must use passive mode if the client is behind a firewall.
	* @param aPort				Port to connect to initiate the PI connection (see RFC959) */
	virtual void Connect(	const THostName& aServerName, //DNS name
							const TDesC8& aUserName, 
							const TDesC8& aPassword,
							const TConnectionMode aConnectionMode=EActive, 
							const TUint aPort=KDefaultServerPiPort)=0;


// Close connection with a server
	/** Closes the current connection with the FTP server.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), or MFtpSessionNotifier::EUnknownError().
	* 
	* This cannot be called when an operation is in progress. */
	virtual void Close()=0;


// Cancel last FTP operation
	/** Cancels the last FTP operation.
	* 
	* Cancel is only implemented for lengthy operations, that is: Connect(), Store(), 
	* Retrieve(), and ListDirectory(). For these operations, once cancel has been 
	* called, the MFtpSessionNotifier::Cancel() callback is called.
	* 
	* For other operations, calling Cancel() has no effect (it would take longer to 
	* wait for an acknowledgement to the Cancel(), than waiting for the result of 
	* the current operation). However, a completion callback will be called, as 
	* well as MFtpSessionNotifier::Cancel(). */
	virtual void Cancel()=0;


// Restart an aborted transfer operation
	/** After a connection is re-established, restarts the last aborted transfer operation 
	* (i.e. Store/Retrieve).
	* 
	* It is the responsibility of the client to remember and reset the state of 
	* the connection before attempting to resume the transfer: i.e. the client should 
	* re-establish the connection to the server and return to the relevant directory, 
	* then it should issue the Restart() command with the offset it has saved, and 
	* then issue the Store() or Retrieve() command.
	* 
	* The Restart() command should be avoided if the transfer was done in ASCII mode, 
	* as, because the server peforms a conversion on the bytestream format that 
	* it gets from the file before sending, the file size on the receiving end will 
	* be different than the size on the sending end. This means it is not possible 
	* to compute an offset for the sending end. 
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::OperationNotSupported(), 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aTFTPRestartOffset	An offset in bytes in the file from where transfer 
	* 							is to be resumed */
	virtual void Restart(const TUint aTFTPRestartOffset)=0;

//
// Transfer APIs
//
// Store a file on the server	
	/** Transfers a file to the FTP server.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(), 
	* MFtpSessionNotifier::LocalFileSystemError(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aLocalFileName			Name of the local file to be transferred
	* @param aNewRemoteFileName		Name of the remote file to be created
	* @param aOverwrite				If ETrue, overwrite a remote file with the same name if it 
	* 								exists; if EFalse, fail if a remote file with the same name exists
	* @param aRepresentationType	The representation type of the transferred file, ASCII or Binary
	* @param aTransferMode			The transfer mode, stream mode or block mode. This is 
	* 								ignored and assumed to be stream, as block mode seems to be obsolete. */
	virtual void Store(	const TDesC& aLocalFileName,
						const TDesC8& aNewRemoteFileName,
						const TBool	aOverwrite = EFalse,
						const RepresentationType aRepresentationType = EBinary,
						const TransferMode aTransferMode = EStream)=0;
	

// Get a file from the server
	/** Transfers a file from the FTP server.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::LocalFileSystemError(), 
	* MFtpSessionNotifier::RemoteFileSystemError() or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aRemoteFileName		The remote file Name
	* @param aNewLocalFileName		Name of the local file to be created
	* @param aOpenMode				Specifies whether to overwrite a local file with the same 
	* 								name if it already exists
	* @param aRepresentationType	The representation type of the transferred file, 
	* 								ASCII or Binary
	* @param aTransferMode			The transfer mode, stream mode or block mode. This is 
	* 								ignored and assumed to be stream, as block mode seems to be obsolete. */
	virtual void Retrieve(	const TDesC8& aRemoteFileName,
							const TDesC& aNewLocalFileName,
							const TOpenMode	aOpenMode = EOverwrite,
							const RepresentationType aRepresentationType = EBinary,
							const TransferMode aTransferMode = EStream)=0;
	

//
// File system management functions
//
	/** Sets the current directory on the remote file system.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aDirectoryName	Directory name */
	virtual void ChangeDirectory(const TDesC8& aDirectoryName)=0;


	/** Creates a directory on the remote file system.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aDirectoryName	A directory name. This can be absolute or relative. */
	virtual void CreateDirectory(const TDesC8& aDirectoryName)=0;


	/** Deletes a directory on the remote file system.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aDirectoryName	A directory name. This can be absolute or relative. */
	virtual void DeleteDirectory(const TDesC8& aDirectoryName)=0;


	/** Gets the client's current directory on the remote file system.
	* 
	* The result is returned to the MFtpSessionNotifier::ServerMessage() callback. 
	* The directory name is defined by the RFC as being enclosed between double 
	* quotes: for example, an answer will look like:
	* 
	* @code
	* 257 "/developr/rfc" is current directory.
	* @endcode
	* The client must implement a parser to find the text between quotes.
	* 
	* The result can be passed in two or more consecutive calls of MFtpSessionNotifier::ServerMessage(). 
	* For example:
	* 
	* First call of MFtpSessionNotifier::ServerMessage(): @code 257 "/developr @endcode
	* 
	* Second call of MFtpSessionNotifier::ServerMessage(): @code /rfc" is current directory. @endcode
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError(). */
	virtual void GetCurrentDirectory(void)=0;


	/** Lists the files in a directory on the remote file system.
	* 
	* On successful completion, the aFileList buffer contains the list of files 
	* as transmitted by the server. It is the responsibility of the client to parse 
	* this buffer to extract relevant information. aFileList is always appended 
	* to, so the client should set its current length to a meaningful value (i.e. 
	* 0, to fill the buffer from scratch).
	* 
	* If the list of files is larger than the aFileList buffer, MFtpSessionNotifier::MoreData() 
	* is called. At this point, the client must reissue the ListDirectory() request 
	* until the MFtpSessionNotifier::Complete() is called.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aDirectoryName	A directory name. This can be absolute or relative.
	* @param aFileList		On completion, the file list. The buffer is allocated by the client. */
	virtual void ListDirectory(const	TDesC8& aDirectoryName,
										TDes8& aFileList)=0;
	

	/** Deletes a file on the remote file system.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aFileName	A file name */
	virtual void DeleteFile(const TDesC8& aFileName)=0;
	
	/** Renames a file on the remote file system.
	* 
	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 
	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 
	* or MFtpSessionNotifier::EUnknownError().
	* 
	* @param aRemoteFileName	An existing file name
	* @param aNewRemoteFileName	A new file name */
	virtual void RenameFile(const TDesC8& aRemoteFileName,
							const TDesC8& aNewRemoteFileName)=0;


	/**
	Returns 32-bit, with 
	ftpsess dll MAJOR_VERSION in msb of the msw
	ftpsess dll MINOR_VERSION in lsb of the msw
	ftpprot dll MAJOR_VERSION in msb of the lsw
	ftpprot dll MINOR_VERSION in lsb of the lsw
	*/
	IMPORT_C static TUint32 GetVersion(void);

	/** Allocates and constructs a new FTP session object. 
	* 
	* @param aNotifier	Callback interface to notify the client of the completion of 
	* 					operations or to report errors. For each FTP session, the FTP 
	* 					client should instantiate an object of this type.
	* @return			New FTP session object
	*/
	IMPORT_C static CFTPSession* NewL(MFtpSessionNotifier* aNotifier);

	/**Destructor.*/
	virtual ~CFTPSession();
};
#endif