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 * FTP Protocol header file

    16 * Author:	Philippe Gabriel

    17 * 

    18 *

    19 */

    20 

    21 

    22 

    23 /**

    24  @file ftprot.h

    25  @internalComponent

    26 */

    27 

    28 #if !defined(__FTPPROT_H__)

    29 #define __FTPPROT_H__

    30 

    31 #include <e32base.h>

    32 #include <es_sock.h>

    33 

    34 /** FTPPROT.DLL major version number.

    35 @internalComponent */

    36 #define FTPPROTDLL_VERSION_MAJOR 0x01 // The very first release

    37 /** FTPPROT.DLL minor version number. */

    38 #define FTPPROTDLL_VERSION_MINOR 0x03

    39 /** FTPPROT.DLL version number. */

    40 #define FTPPROTDLL_VERSION_NUMBER (FTPPROTDLL_VERSION_MAJOR<<8)|FTPPROTDLL_VERSION_MINOR

    41 

    42 class MFtpProtocolNotifier

    43 /** FTP engine callback interface.

    44 *

    45 * An FTP engine client implements this interface to receive status and results 

    46 * from asynchronous FTP commands.

    47 * @internalComponent */

    48 	{

    49 // Operation completion return codes.

    50 	

    51 public:

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

    53 	enum TOpComp 

    54 	{

    55 	/** Operation completed normally. */

    56 	EOpComplete=0,

    57 	/** Operation cancelled. */

    58 	EOpCanceled,	// User canceled last operation

    59 	/** Operation failed. */

    60 	EOpFailed, 

    61 	/** Sockets level error. */

    62 	ESocketError, 

    63 

    64 	// Connection errors

    65 	/** Connection error: Connection reset. */

    66 	EOpConnectionReset,

    67 	/** Connection error: Connection failed. */

    68 	EOpConnectionFailed,	

    69 	/** Connection error: Server not found. */

    70 	EHostNotFound,

    71 

    72 	// Transfer error 

    73 	/** Transfer error: Transfer was reset. */

    74 	EXferReset,

    75 	/** Transfer error: Transfer is not initialised. */	

    76 	EXferNotInitialised,

    77 

    78 	//Transfer notification

    79 	/** Transfer notification: Data packet was received. */

    80 	EPacketReceived,

    81 	/** Transfer notification: Data packet was sent. */	

    82 	EPacketSent

    83 	};

    84 public:

    85 	/** Destructor. */

    86 	virtual ~MFtpProtocolNotifier(){};

    87 

    88 	/** Positive reply received from server.

    89 	*

    90 	* @param aStatus	Operation completion code */

    91 	virtual void ServerPositiveAnswerNotification(const TOpComp aStatus)=0;

    92 

    93 

    94 	/** Message sent by the FTP server.

    95 	*

    96 	* This returns the full server reply in plain text format.

    97 	* 

    98 	* @param aMessage	The message sent by the server */

    99 	virtual void ServerMessage(const TDesC8& aMessage)=0;

   100 

   101 	/** Data transfer notification received from the server.

   102 	*

   103 	* @param aStatus	Operation completion code */

   104 	virtual void ServerXFerNotification(const TOpComp aStatus)=0;

   105 

   106 	/** Negative reply received from server.

   107 	* 

   108 	* @param aStatus	Operation completion code */

   109 	virtual void ServerNegativeAnswerNotification(const TOpComp aStatus)=0;

   110 

   111 	/** Error condition notification.

   112 	* 

   113 	* @param aStatus	Operation completion code */

   114 	virtual void ErrorNotification(const TOpComp aStatus)=0;

   115 	};

   116 

   117 

   118 class CFtpProtocol : public CBase

   119 /** Implements an FTP engine, and allows the client to access the individual FTP 

   120 * commands as defined in RFC959.

   121 * 

   122 * Note that before commands that cause data to transit on the DTP channel (e.g. NLST, 

   123 * LIST, RETR, STOR) a data buffer must be provided using SendBuffer()/RecvBuffer(). 

   124 * Also, when the client is notified of a MoreData() event, it must re-issue RecvBuffer() 

   125 * to get the rest of the data.

   126 * @internalComponent

   127 */

   128 	{

   129 public:

   130 

   131 // Establish a connection:

   132 	/** Connect to an FTP server, specifying an IP address.	

   133 	* 

   134 	* @param aNetAddr	FTP server's IP address */

   135 	virtual void Connect(TSockAddr& aNetAddr)=0;	// IP address

   136 

   137 	/** Connect to an FTP server, specifying a DNS name.

   138 	* 

   139 	* @param aServerName	FTP server's DNS name */

   140 	virtual void Connect(const THostName& aServerName)=0;  // URL name

   141 

   142 	/** Connect to an FTP server, specifying a DNS name and port number.

   143 	* 

   144 	* @param aServerName	FTP server's DNS name

   145 	* @param aPort			FTP server's port */

   146 	virtual void Connect(const THostName& aServerName, const TUint aPort)=0; // URL name + port

   147 

   148 // FTP commands, presented in the same order as RFC959:

   149 	/** Issues the USER command.

   150 	* 

   151 	* @param aParam	Telnet string identifying the user */

   152 	virtual void User(const TDesC8& aParam)=0;

   153 

   154 	/** Issues the PASS command.

   155 	* 

   156 	* @param aParam	Telnet string specifying the user's password */

   157 	virtual void Pass(const TDesC8& aParam)=0;

   158 

   159 	/** Issues the ACCT command.

   160 	* 

   161 	* @param aParam	Telnet string identifying the user's account */

   162 	virtual void Acct(const TDesC8& aParam)=0;

   163 

   164 	/** Issues the CWD command.

   165 	* 

   166 	* @param aParam	Directory or other system dependent file group designator */

   167 	virtual void Cwd(const TDesC8& aParam)=0;

   168 

   169 	/** Issues the CDUP command. */

   170 	virtual void Cdup(void)=0;

   171 

   172 	/** Issues the SMNT command.

   173 	* 

   174 	* @param aParam	Pathname specifying a directory or other system dependent file 

   175 	* 				group designator */

   176 	virtual void Smnt(const TDesC8& aParam)=0;

   177 

   178 	/** Issues the QUIT command. */

   179 	virtual void Quit(void)=0;

   180 

   181 	/** Issues the REIN command. */

   182 	virtual void Rein(void)=0;

   183 

   184 	/** Issues the PORT command, setting the Data Transfer Process port to a value 

   185 	* allocated by the Sockets Server. */

   186 	virtual void Port(void)=0;			// Sets the DTP port to one allocated by ESOCK

   187 

   188 	/** Issues the PORT command, specifying a port number.

   189 	* 

   190 	* @param aPort	Port number */

   191 	virtual void Port(TUint aPort)=0;	// Sets the DTP port to a specific one

   192 

   193 	/** Issues the PASV command. */

   194 	virtual void Pasv(void)=0;

   195 

   196 	/** Issues the TYPE command (single parameter).

   197 	* 

   198 	* @param aParam	First representation type parameter */

   199 	virtual void Type(const TDesC8& aParam)=0;

   200 

   201 	/** Issues the TYPE command (two parameters).

   202 	* 

   203 	* @param aParam1	First representation type parameter

   204 	* @param aParam2	Second representation type parameter */

   205 	virtual void Type(const TDesC8& aParam1, const TDesC8& aParam2)=0;

   206 

   207 	/** Issues the STRU command.

   208 	* 

   209 	* @param aParam	Telnet character code specifying the file structure */

   210 	virtual void Stru(const TDesC8& aParam)=0;

   211 

   212 	/** Issues the MODE command.

   213 	* 

   214 	* @param aParam	Telnet character code specifying the data transfer mode */

   215 	virtual void Mode(const TDesC8& aParam)=0;

   216 

   217 	/** Issues the RETR command.

   218 	* 

   219 	* @param aFileName	File name */

   220 	virtual void Retr(const TDesC8& aFileName)=0;

   221 

   222 	/** Issues the STOR command.

   223 	* 

   224 	* @param aFileName	File name */

   225 	virtual void Stor(const TDesC8& aFileName)=0;

   226 

   227 	/** Issues the STOU command. */

   228 	virtual void Stou(void)=0;

   229 

   230 	/** Issues the APPE command.

   231 	* 

   232 	* @param aFileName	File name */

   233 	virtual void Appe(const TDesC8& aFileName)=0;

   234 

   235 	/** Issues the ALLO command (single parameter).

   236 	* 

   237 	* @param aParam	Number of bytes (using the logical byte size) of storage to 

   238 	* 				be reserved for the file */

   239 	virtual void Allo(const TDesC8& aParam)=0;

   240 

   241 	/** Issues the ALLO command (two parameters).

   242 	* 

   243 	* @param aParam1	Number of bytes (using the logical byte size) of storage to 

   244 	* 					be reserved for the file

   245 	* @param aParam2	Maximum record or page size (in logical bytes) */

   246 	virtual void Allo(const TDesC8& aParam1, const TDesC8& aParam2)=0;

   247 

   248 	/** Issues the REST command.

   249 	* 

   250 	* @param aParam	The server marker at which file transfer is to be restarted */

   251 	virtual void Rest(const TDesC8& aParam)=0;

   252 

   253 	/** Issues the RNFR command.

   254 	* 

   255 	* @param aFileName	File name */

   256 	virtual void Rnfr(const TDesC8& aFileName)=0;

   257 

   258 	/** Issues the RNTO command.

   259 	* 

   260 	* @param aFileName	File name */

   261 	virtual void Rnto(const TDesC8& aFileName)=0;

   262 

   263 	/** Issues the ABOR command. */

   264 	virtual void Abor(void)=0;

   265 

   266 	/** Issues the DELE command.

   267 	* 

   268 	* @param aFileName	File name */

   269 	virtual void Dele(const TDesC8& aFileName)=0;

   270 

   271 	/** Issues the RMD command.

   272 	* 

   273 	* @param aParam	Directory name */

   274 	virtual void Rmd(const TDesC8& aParam)=0;

   275 

   276 	/** Issues the MKD command.

   277 	* 

   278 	* @param aParam	Directory name */

   279 	virtual void Mkd(const TDesC8& aParam)=0;

   280 

   281 	/** Issues the PWD command. */

   282 	virtual void Pwd(void)=0;

   283 

   284 	/** Issues the LIST command, giving a null argument. */

   285 	virtual void List(void)=0;

   286 

   287 	/** Issues the LIST command, specifying a file/directory name.

   288 	* 

   289 	* @param aParam	File/directory name */

   290 	virtual void List(const TDesC8& aParam)=0;

   291 

   292 	/** Issues the NLST command, giving a null argument. */

   293 	virtual void Nlst(void)=0;

   294 

   295 	/** Issues the NLST command, specifying a directory name.

   296 	* 

   297 	* @param aParam	Directory name */

   298 	virtual void Nlst(const TDesC8& aParam)=0;

   299 

   300 	/** Issues the SITE command.

   301 	* 

   302 	* @param aParam	SITE command argument */

   303 	virtual void Site(const TDesC8& aParam)=0;

   304 

   305 	/** Issues the SYST command. */

   306 	virtual void Syst(void)=0;

   307 

   308 	/** Issues the STAT command, specifying an argument.

   309 	* 

   310 	* @param aParam	STAT command argument */

   311 	virtual void Stat(const TDesC8& aParam)=0;

   312 

   313 	/** Issues the STAT command (no argument). */

   314 	virtual void Stat(void)=0;

   315 

   316 	/** Issues the HELP command.

   317 	* 

   318 	* @param aParam	HELP command argument */

   319 	virtual void Help(const TDesC8& aParam)=0;

   320 

   321 	/** Issues the HELP command (no argument). */

   322 	virtual void Help(void)=0;

   323 

   324 	/** Issues the NOOP command. */

   325 	virtual void Noop(void)=0;

   326 

   327 // Buffer management for transfer

   328 	// Following functions pass a pointer to a buffer

   329 	// to transfer data to/from the Dtp channel

   330 	// Before an operation which cause data to transit on the 

   331 	// DTP channel to occur (Nlst, List, Retr, Stor)

   332 	// a Buffer must be provided with the following api

   333 	// Also when the client is notified of a MoreData event

   334 	// It must reissue the following operation to get the rest of

   335 	// the data

   336 	/** Specifies a buffer to transfer data to the DTP channel.	

   337 	* 

   338 	* @param aBuffer	Send receive */

   339 	virtual void SendBuffer(TDes8* aBuffer)=0;

   340 

   341 	/** Specifies a buffer to receive data from the DTP channel.

   342 	* 

   343 	* @param aBuffer	Receive buffer */

   344 	virtual void RecvBuffer(TDes8* aBuffer)=0;

   345 

   346 	/** Finishes the transfer initiated by a STOR command. */

   347 	virtual void SendEOF(void)=0; //Finishes the transfer initiated by a stor command

   348 

   349 	/** Cancels current operation. */

   350 	virtual void UserCancel(void)=0;

   351 

   352 // Copies the 3 digits answer received from the FTP server

   353 	/** Gets the 3 digits answer received from the FTP server.

   354 	* 

   355 	* @param aServerAnswer	3 digit answer */

   356 	virtual void FTPServerAnswer(TDes& aServerAnswer)=0;

   357 

   358 	/**

   359 	Returns 32-bit, with MAJOR_VERSION in the highest byte

   360 	MINOR_VERSION in the next byte

   361 	i.e. MAJOR 2, MINOR 0x34, BUILD 0x278 would be "ver 2.52

   362 	*/

   363 	IMPORT_C static TUint32 GetVersion(void);

   364 

   365 	/** Allocates and constructs a new FTP engine object.

   366 	* 

   367 	* @return	New FTP engine object

   368 	*/

   369 	// @param aNotifier Client callback interface. 

   370 	// The FTP engine calls this interface to pass 

   371 	//server responses and status messages to the client.

   372 	IMPORT_C static CFtpProtocol *NewL(MFtpProtocolNotifier*);

   373 

   374 	/**Destructor.*/

   375 	virtual ~CFtpProtocol();

   376 	};

   377 #endif //__FTPPROT_H__