diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/ftpsess.h --- a/epoc32/include/ftpsess.h Wed Mar 31 12:27:01 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,510 +0,0 @@ -/** -* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members -* which accompanies this distribution, and is available -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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