1 /**

     2 * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * EPOC32 FTP Engine header file

    16 * Author:	Philippe Gabriel

    17 * Exports set of APIs simplyfying access to the FTP protocol

    18 * 

    19 *

    20 */

    21 

    22 

    23 

    24 /**

    25  @file FTPSESS.H

    26  @internalComponent

    27 */

    28 

    29 #if !defined(__FTPSESS_H__)

    30 #define __FTPSESS_H__

    31 #include <e32base.h>

    32 #include <es_sock.h>

    33 #include <f32file.h>

    34 

    35 /**

    36 The very first release

    37 */

    38 

    39 /** FTPSESS.DLL major version number. */

    40 #define FTPSESS_VERSION_MAJOR 0x01 // The very first release

    41 /** FTPSESS.DLL minor version number. */

    42 #define FTPSESS_VERSION_MINOR 0x03

    43 /** FTPSESS.DLL version number. */

    44 #define FTPSESS_VERSION_NUMBER (FTPSESS_VERSION_MAJOR<<8)|FTPSESS_VERSION_MINOR

    45 

    46 // Following Def as per RFC 959

    47 /** Default server port.

    48 @internalComponent */

    49 const TUint KDefaultServerPiPort = 21;

    50 //

    51 // MInterface definition to provide callback functions to the client

    52 //

    53 

    54 class MFtpSessionNotifier

    55 /** FTP session callback interface.

    56 *

    57 * An FTP session client implements this interface to receive status and results 

    58 * from asynchronous FTP operations.

    59 * 

    60 * Note that, as defined in RFC959, FTP does not allow concurrent execution of 

    61 * several requests. Hence, even though calling an FTP function and getting the 

    62 * result through this interface are asynchronous operations, these events happen 

    63 * in a sequential manner. Each notification that the client receives corresponds 

    64 * to only one currently outstanding operation.

    65 * @internalComponent

    66 */

    67 	{

    68 public:

    69 //

    70 // Operation completion return codes.

    71 // 

    72 /** FTP engine/session operation completeness codes. */

    73 	enum TOpComp 

    74 		{

    75 	/** Operation completed normally. */

    76 		EOpComplete=0,	// No error

    77 	/** Operation cancelled. */

    78 		EOpCanceled,	// User canceled last operation

    79 

    80 		//Connection errors

    81 	/** Connection error: Connect address invalid. */

    82 		EHostNotExist,	// Connect address invalid

    83 	/** Connection error: Sockets level error. */

    84 		ESocketError,	// Problem with socket operation

    85 	/** Connection error: Connection failed. */

    86 		EConnectionFailed,	// Can't connect to FTP port

    87 	/** Connection error: Password needed. */

    88 		EPasswordNeeded,

    89 	/** Connection error: Anonymous login not permitted. */

    90 		EAccountNeeded,	// i.e. anonymous login disallowed

    91 	/** Connection error: UserName, Password combination invalid. */

    92 		ELoginFailed,	// UserName,Password combination invalid

    93 	/** Connection error: Not connected to a server. */

    94 		ENotConnected,	// Not connected to a server

    95 	/** Connection error: Already connected to a server. */

    96 		EAlreadyConnected,	// Already connected to a server

    97 	/** Connection error: Operation timed out. */

    98 		ETimedOut,	// Inactive for too long

    99 

   100 		//Local filesystem errors

   101 	/** Local filesystem error: General file system error. */

   102 		EFileSystemError, 

   103 	/** Local filesystem error: File opening failure. */

   104 		EFileOpenFailure, 

   105 	/** Local filesystem error: File reading failure. */

   106 		EFileReadError, 

   107 	/** Local filesystem error: File writing failure. */

   108 		EFileWriteError,

   109 	/** Local filesystem error: File already exists. */

   110 		EFileAlreadyExist,

   111 	/** Local filesystem error: File does not exist. */

   112 		EFileNotExist,

   113 	/** Local filesystem error: Directory already exists. */

   114 		EDirAlreadyExist,

   115 	/** Local filesystem error: Directory does not exist. */

   116 		EDirNotExist,

   117 

   118 		// Permission error

   119 	/** Permission error: Permission denied. */

   120 		EPermissionDenied,

   121 

   122 		//Remote filesystem errors

   123 	/** Remote filesystem error: General remote file system error. */

   124 		ERemoteFileSystemError, 

   125 	/** Remote filesystem error: Remote file opening failure. */

   126 		ERemoteFileOpenFailure, 

   127 	/** Remote filesystem error: Remote file reading failure. */

   128 		ERemoteFileReadError, 

   129 	/** Remote filesystem error: Remote file writing failure. */

   130 		ERemoteFileWriteError,

   131 	/** Remote filesystem error: Remote file already exists. */

   132 		ERemoteFileAlreadyExist,

   133 	/** Remote filesystem error: Remote file does not exist. */

   134 		ERemoteFileNotExist,

   135 	/** Remote filesystem error: Remote directory already exists. */

   136 		ERemoteDirAlreadyExist,

   137 	/** Remote filesystem error: Remote directory does not exist. */

   138 		ERemoteDirNotExist,

   139 	/** Remote filesystem error: Restart is not supported. */

   140 		ERestartNotSupported

   141 		};

   142 

   143 	/** Normal operation completion. */

   144 	virtual void Complete(void)=0;

   145 

   146 	// Operation completed, more data to follow

   147 	/** Operation partially completed, with more data to follow. */

   148 	virtual void MoreData(void)=0;

   149 

   150 	/** Reports the amount of data already transferred in bytes.

   151 	* 

   152 	* @param aProgress	Amount of data already transferred */

   153 	virtual void TransferProgress(TUint aProgress)=0;

   154 

   155 	/** User cancelled an on-going operation. */

   156 	virtual void Cancel(void)=0;

   157 

   158 	/** Peer reset the connection. */

   159 	virtual void ConnReset(void)=0;

   160 

   161 	/** Error in establishing the connection with the FTP server.

   162 	* 

   163 	* @param aTConnectionError	Operation completion code */

   164 	virtual void ConnectionError(TOpComp aTConnectionError)=0;

   165 

   166 	// FTP server does not implement the operation requested

   167 	/** Restart operation not supported. */

   168 	virtual void OperationNotSupported(void)=0;

   169 

   170 	// Local File system error

   171 	/** Error with the local file system.

   172 	* 

   173 	* @param aTLocalFileSystemError	Operation completion code */

   174 	virtual void LocalFileSystemError(TOpComp aTLocalFileSystemError)=0;

   175 

   176 	// Remote File system error

   177 	/** Error with the remote file system.

   178 	* 

   179 	* @param aTRemoteFileSystemError	Operation completion code */

   180 	virtual void RemoteFileSystemError(TOpComp aTRemoteFileSystemError)=0;

   181 

   182 	// Not specified yet

   183 	/** Unspecified error. */

   184 	virtual void EUnknownError()=0;

   185 

   186 	// Message reported by server

   187 /** Message sent by the FTP server.

   188 * 

   189 * As specified by the RFC, the server answers all requests from the 

   190 * client with a plain text message beginning with a 3 digit code.

   191 * The error/completion notifications sent back by the FTP session API 

   192 * are derived from these codes. Additionally, this function can be 

   193 * used to get the full string reporting the result of the request. 

   194 * It is recommended that the user interface displays this string to 

   195 * the user, as this gives a more precise idea of the result of the 

   196 * requested operation, especially in case of error.

   197 * 

   198 * @param TDesC8	The message sent by the server */

   199 	virtual void ServerMessage(const TDesC8&)=0;

   200     	};		

   201 //

   202 // The CFTPSession class

   203 //

   204 class CFTPSession : public CBase

   205 

   206 /** Abstracts the complexity of the full FTP protocol and exports only 

   207 * a few simplified APIs.

   208 * @internalComponent */

   209 	{

   210 public:

   211 /** FTP connection mode (passive or active see RFC959). */

   212 	enum TConnectionMode 

   213 		{

   214 	/** Active mode. Server initiates DTP connection to client. */

   215 		EActive=0, //(see RFC959)

   216 	/** Passive mode. Client initiates DTP connection to server.*/

   217 		Epassive   //(see RFC959)

   218 		};

   219 /** Representation type of a transferred file. */

   220 	enum RepresentationType

   221 		{

   222 	/** Uninitialised. */

   223 		EUninitialised=0,						   

   224 	/** File transfered in Binary mode, no translation. */

   225 		EBinary,

   226 	/** File transfered in ASCII mode, translation. */

   227 		EASCII

   228 		};

   229 /** FTP file transfer mode. */

   230 	enum TransferMode

   231 		{

   232 	/** Stream mode; file transfered as a stream of bytes. */

   233 		EStream=0,

   234 	/** Block mode; file transfered as blocks, with header needed to restart aborted transfer. */

   235 		Eblock 

   236 		};

   237 /** FTP file open mode. */

   238 	enum TOpenMode

   239 		{

   240 	/** Overwrite existing file. */

   241 		EOverwrite,

   242 	/** Do not overwrite existing file. */

   243 		ENoOverwrite,

   244 	/** Expand existing file. */

   245 		EExpand

   246 		};

   247 

   248 /** Construction */

   249 public:

   250 

   251 //

   252 // Connection APIs

   253 //

   254 // Establish a connection with a server:

   255 	/** Connects to a remote FTP server, specifying the FTP server by a numeric IP 

   256 	* address.

   257 	* 

   258 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   259 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(), 

   260 	* or MFtpSessionNotifier::EUnknownError().

   261 	* 

   262 	* @param aNetAddr			FTP server's IP address

   263 	* @param aUserName			User name to log on the FTP server

   264 	* @param aPassword			Password to identify to the FTP server

   265 	* @param aConnectionMode	Connection mode (passive or active, see RFC959). 

   266 	* 							You must use passive mode if the client is behind a firewall. */

   267 	virtual void Connect(	const TSockAddr& aNetAddr, //IP address

   268 							const TDesC8& aUserName, 

   269 							const TDesC8& aPassword,

   270 							const TConnectionMode aConnectionMode=EActive)=0;

   271 

   272 

   273 	/** Connects to a remote FTP server, specifying the FTP server by a DNS name.

   274 	* 

   275 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   276 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(), 

   277 	* or MFtpSessionNotifier::EUnknownError().

   278 	* 

   279 	* @param aServerName		FTP server's DNS name

   280 	* @param aUserName			User name to log on the FTP server

   281 	* @param aPassword			Password to identify to the FTP server

   282 	* @param aConnectionMode	Connection mode (passive or active, see RFC959). You 

   283 	* 							must use passive mode if the client is behind a firewall.

   284 	* @param aPort				Port to connect to initiate the PI connection (see RFC959) */

   285 	virtual void Connect(	const THostName& aServerName, //DNS name

   286 							const TDesC8& aUserName, 

   287 							const TDesC8& aPassword,

   288 							const TConnectionMode aConnectionMode=EActive, 

   289 							const TUint aPort=KDefaultServerPiPort)=0;

   290 

   291 

   292 // Close connection with a server

   293 	/** Closes the current connection with the FTP server.

   294 	* 

   295 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   296 	* MFtpSessionNotifier::ConnReset(), or MFtpSessionNotifier::EUnknownError().

   297 	* 

   298 	* This cannot be called when an operation is in progress. */

   299 	virtual void Close()=0;

   300 

   301 

   302 // Cancel last FTP operation

   303 	/** Cancels the last FTP operation.

   304 	* 

   305 	* Cancel is only implemented for lengthy operations, that is: Connect(), Store(), 

   306 	* Retrieve(), and ListDirectory(). For these operations, once cancel has been 

   307 	* called, the MFtpSessionNotifier::Cancel() callback is called.

   308 	* 

   309 	* For other operations, calling Cancel() has no effect (it would take longer to 

   310 	* wait for an acknowledgement to the Cancel(), than waiting for the result of 

   311 	* the current operation). However, a completion callback will be called, as 

   312 	* well as MFtpSessionNotifier::Cancel(). */

   313 	virtual void Cancel()=0;

   314 

   315 

   316 // Restart an aborted transfer operation

   317 	/** After a connection is re-established, restarts the last aborted transfer operation 

   318 	* (i.e. Store/Retrieve).

   319 	* 

   320 	* It is the responsibility of the client to remember and reset the state of 

   321 	* the connection before attempting to resume the transfer: i.e. the client should 

   322 	* re-establish the connection to the server and return to the relevant directory, 

   323 	* then it should issue the Restart() command with the offset it has saved, and 

   324 	* then issue the Store() or Retrieve() command.

   325 	* 

   326 	* The Restart() command should be avoided if the transfer was done in ASCII mode, 

   327 	* as, because the server peforms a conversion on the bytestream format that 

   328 	* it gets from the file before sending, the file size on the receiving end will 

   329 	* be different than the size on the sending end. This means it is not possible 

   330 	* to compute an offset for the sending end. 

   331 	* 

   332 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   333 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::OperationNotSupported(), 

   334 	* or MFtpSessionNotifier::EUnknownError().

   335 	* 

   336 	* @param aTFTPRestartOffset	An offset in bytes in the file from where transfer 

   337 	* 							is to be resumed */

   338 	virtual void Restart(const TUint aTFTPRestartOffset)=0;

   339 

   340 //

   341 // Transfer APIs

   342 //

   343 // Store a file on the server	

   344 	/** Transfers a file to the FTP server.

   345 	* 

   346 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   347 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(), 

   348 	* MFtpSessionNotifier::LocalFileSystemError(), MFtpSessionNotifier::RemoteFileSystemError() 

   349 	* or MFtpSessionNotifier::EUnknownError().

   350 	* 

   351 	* @param aLocalFileName			Name of the local file to be transferred

   352 	* @param aNewRemoteFileName		Name of the remote file to be created

   353 	* @param aOverwrite				If ETrue, overwrite a remote file with the same name if it 

   354 	* 								exists; if EFalse, fail if a remote file with the same name exists

   355 	* @param aRepresentationType	The representation type of the transferred file, ASCII or Binary

   356 	* @param aTransferMode			The transfer mode, stream mode or block mode. This is 

   357 	* 								ignored and assumed to be stream, as block mode seems to be obsolete. */

   358 	virtual void Store(	const TDesC& aLocalFileName,

   359 						const TDesC8& aNewRemoteFileName,

   360 						const TBool	aOverwrite = EFalse,

   361 						const RepresentationType aRepresentationType = EBinary,

   362 						const TransferMode aTransferMode = EStream)=0;

   363 	

   364 

   365 // Get a file from the server

   366 	/** Transfers a file from the FTP server.

   367 	* 

   368 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   369 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::LocalFileSystemError(), 

   370 	* MFtpSessionNotifier::RemoteFileSystemError() or MFtpSessionNotifier::EUnknownError().

   371 	* 

   372 	* @param aRemoteFileName		The remote file Name

   373 	* @param aNewLocalFileName		Name of the local file to be created

   374 	* @param aOpenMode				Specifies whether to overwrite a local file with the same 

   375 	* 								name if it already exists

   376 	* @param aRepresentationType	The representation type of the transferred file, 

   377 	* 								ASCII or Binary

   378 	* @param aTransferMode			The transfer mode, stream mode or block mode. This is 

   379 	* 								ignored and assumed to be stream, as block mode seems to be obsolete. */

   380 	virtual void Retrieve(	const TDesC8& aRemoteFileName,

   381 							const TDesC& aNewLocalFileName,

   382 							const TOpenMode	aOpenMode = EOverwrite,

   383 							const RepresentationType aRepresentationType = EBinary,

   384 							const TransferMode aTransferMode = EStream)=0;

   385 	

   386 

   387 //

   388 // File system management functions

   389 //

   390 	/** Sets the current directory on the remote file system.

   391 	* 

   392 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   393 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   394 	* or MFtpSessionNotifier::EUnknownError().

   395 	* 

   396 	* @param aDirectoryName	Directory name */

   397 	virtual void ChangeDirectory(const TDesC8& aDirectoryName)=0;

   398 

   399 

   400 	/** Creates a directory on the remote file system.

   401 	* 

   402 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   403 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   404 	* or MFtpSessionNotifier::EUnknownError().

   405 	* 

   406 	* @param aDirectoryName	A directory name. This can be absolute or relative. */

   407 	virtual void CreateDirectory(const TDesC8& aDirectoryName)=0;

   408 

   409 

   410 	/** Deletes a directory on the remote file system.

   411 	* 

   412 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   413 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   414 	* or MFtpSessionNotifier::EUnknownError().

   415 	* 

   416 	* @param aDirectoryName	A directory name. This can be absolute or relative. */

   417 	virtual void DeleteDirectory(const TDesC8& aDirectoryName)=0;

   418 

   419 

   420 	/** Gets the client's current directory on the remote file system.

   421 	* 

   422 	* The result is returned to the MFtpSessionNotifier::ServerMessage() callback. 

   423 	* The directory name is defined by the RFC as being enclosed between double 

   424 	* quotes: for example, an answer will look like:

   425 	* 

   426 	* @code

   427 	* 257 "/developr/rfc" is current directory.

   428 	* @endcode

   429 	* The client must implement a parser to find the text between quotes.

   430 	* 

   431 	* The result can be passed in two or more consecutive calls of MFtpSessionNotifier::ServerMessage(). 

   432 	* For example:

   433 	* 

   434 	* First call of MFtpSessionNotifier::ServerMessage(): @code 257 "/developr @endcode

   435 	* 

   436 	* Second call of MFtpSessionNotifier::ServerMessage(): @code /rfc" is current directory. @endcode

   437 	* 

   438 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   439 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   440 	* or MFtpSessionNotifier::EUnknownError(). */

   441 	virtual void GetCurrentDirectory(void)=0;

   442 

   443 

   444 	/** Lists the files in a directory on the remote file system.

   445 	* 

   446 	* On successful completion, the aFileList buffer contains the list of files 

   447 	* as transmitted by the server. It is the responsibility of the client to parse 

   448 	* this buffer to extract relevant information. aFileList is always appended 

   449 	* to, so the client should set its current length to a meaningful value (i.e. 

   450 	* 0, to fill the buffer from scratch).

   451 	* 

   452 	* If the list of files is larger than the aFileList buffer, MFtpSessionNotifier::MoreData() 

   453 	* is called. At this point, the client must reissue the ListDirectory() request 

   454 	* until the MFtpSessionNotifier::Complete() is called.

   455 	* 

   456 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   457 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   458 	* or MFtpSessionNotifier::EUnknownError().

   459 	* 

   460 	* @param aDirectoryName	A directory name. This can be absolute or relative.

   461 	* @param aFileList		On completion, the file list. The buffer is allocated by the client. */

   462 	virtual void ListDirectory(const	TDesC8& aDirectoryName,

   463 										TDes8& aFileList)=0;

   464 	

   465 

   466 	/** Deletes a file on the remote file system.

   467 	* 

   468 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   469 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   470 	* or MFtpSessionNotifier::EUnknownError().

   471 	* 

   472 	* @param aFileName	A file name */

   473 	virtual void DeleteFile(const TDesC8& aFileName)=0;

   474 	

   475 	/** Renames a file on the remote file system.

   476 	* 

   477 	* Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(), 

   478 	* MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError() 

   479 	* or MFtpSessionNotifier::EUnknownError().

   480 	* 

   481 	* @param aRemoteFileName	An existing file name

   482 	* @param aNewRemoteFileName	A new file name */

   483 	virtual void RenameFile(const TDesC8& aRemoteFileName,

   484 							const TDesC8& aNewRemoteFileName)=0;

   485 

   486 

   487 	/**

   488 	Returns 32-bit, with 

   489 	ftpsess dll MAJOR_VERSION in msb of the msw

   490 	ftpsess dll MINOR_VERSION in lsb of the msw

   491 	ftpprot dll MAJOR_VERSION in msb of the lsw

   492 	ftpprot dll MINOR_VERSION in lsb of the lsw

   493 	*/

   494 	IMPORT_C static TUint32 GetVersion(void);

   495 

   496 	/** Allocates and constructs a new FTP session object. 

   497 	* 

   498 	* @param aNotifier	Callback interface to notify the client of the completion of 

   499 	* 					operations or to report errors. For each FTP session, the FTP 

   500 	* 					client should instantiate an object of this type.

   501 	* @return			New FTP session object

   502 	*/

   503 	IMPORT_C static CFTPSession* NewL(MFtpSessionNotifier* aNotifier);

   504 

   505 	/**Destructor.*/

   506 	virtual ~CFTPSession();

   507 };

   508 #endif