--- /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