diff -r 000000000000 -r b16258d2340f applayerprotocols/ftpengine/inc/FTPSESS.H
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/applayerprotocols/ftpengine/inc/FTPSESS.H	Tue Feb 02 01:09:52 2010 +0200
@@ -0,0 +1,508 @@
+/**
+* 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