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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 

    25 /**

    26  @file ftprot.h

    27  @internalComponent

    28 */

    29 

    30 #if !defined(__FTPPROT_H__)

    31 #define __FTPPROT_H__

    32 

    33 #include <e32base.h>

    34 #include <es_sock.h>

    35 

    36 /** FTPPROT.DLL major version number.

    37 @internalComponent */

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

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

    40 #define FTPPROTDLL_VERSION_MINOR 0x03

    41 /** FTPPROT.DLL version number. */

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

    43 

    44 class MFtpProtocolNotifier

    45 /** FTP engine callback interface.

    46 *

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

    48 * from asynchronous FTP commands.

    49 * @internalComponent */

    50 	{

    51 // Operation completion return codes.

    52 	

    53 public:

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

    55 	enum TOpComp 

    56 	{

    57 	/** Operation completed normally. */

    58 	EOpComplete=0,

    59 	/** Operation cancelled. */

    60 	EOpCanceled,	// User canceled last operation

    61 	/** Operation failed. */

    62 	EOpFailed, 

    63 	/** Sockets level error. */

    64 	ESocketError, 

    65 

    66 	// Connection errors

    67 	/** Connection error: Connection reset. */

    68 	EOpConnectionReset,

    69 	/** Connection error: Connection failed. */

    70 	EOpConnectionFailed,	

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

    72 	EHostNotFound,

    73 

    74 	// Transfer error 

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

    76 	EXferReset,

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

    78 	EXferNotInitialised,

    79 

    80 	//Transfer notification

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

    82 	EPacketReceived,

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

    84 	EPacketSent

    85 	};

    86 public:

    87 	/** Destructor. */

    88 	virtual ~MFtpProtocolNotifier(){};

    89 

    90 	/** Positive reply received from server.

    91 	*

    92 	* @param aStatus	Operation completion code */

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

    94 

    95 

    96 	/** Message sent by the FTP server.

    97 	*

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

    99 	* 

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

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

   102 

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

   104 	*

   105 	* @param aStatus	Operation completion code */

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

   107 

   108 	/** Negative reply received from server.

   109 	* 

   110 	* @param aStatus	Operation completion code */

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

   112 

   113 	/** Error condition notification.

   114 	* 

   115 	* @param aStatus	Operation completion code */

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

   117 	};

   118 

   119 

   120 class CFtpProtocol : public CBase

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

   122 * commands as defined in RFC959.

   123 * 

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

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

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

   127 * to get the rest of the data.

   128 * @internalComponent

   129 */

   130 	{

   131 public:

   132 

   133 // Establish a connection:

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

   135 	* 

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

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

   138 

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

   140 	* 

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

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

   143 

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

   145 	* 

   146 	* @param aServerName	FTP server's DNS name

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

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

   149 

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

   151 	/** Issues the USER command.

   152 	* 

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

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

   155 

   156 	/** Issues the PASS command.

   157 	* 

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

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

   160 

   161 	/** Issues the ACCT command.

   162 	* 

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

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

   165 

   166 	/** Issues the CWD command.

   167 	* 

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

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

   170 

   171 	/** Issues the CDUP command. */

   172 	virtual void Cdup(void)=0;

   173 

   174 	/** Issues the SMNT command.

   175 	* 

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

   177 	* 				group designator */

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

   179 

   180 	/** Issues the QUIT command. */

   181 	virtual void Quit(void)=0;

   182 

   183 	/** Issues the REIN command. */

   184 	virtual void Rein(void)=0;

   185 

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

   187 	* allocated by the Sockets Server. */

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

   189 

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

   191 	* 

   192 	* @param aPort	Port number */

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

   194 

   195 	/** Issues the PASV command. */

   196 	virtual void Pasv(void)=0;

   197 

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

   199 	* 

   200 	* @param aParam	First representation type parameter */

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

   202 

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

   204 	* 

   205 	* @param aParam1	First representation type parameter

   206 	* @param aParam2	Second representation type parameter */

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

   208 

   209 	/** Issues the STRU command.

   210 	* 

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

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

   213 

   214 	/** Issues the MODE command.

   215 	* 

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

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

   218 

   219 	/** Issues the RETR command.

   220 	* 

   221 	* @param aFileName	File name */

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

   223 

   224 	/** Issues the STOR command.

   225 	* 

   226 	* @param aFileName	File name */

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

   228 

   229 	/** Issues the STOU command. */

   230 	virtual void Stou(void)=0;

   231 

   232 	/** Issues the APPE command.

   233 	* 

   234 	* @param aFileName	File name */

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

   236 

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

   238 	* 

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

   240 	* 				be reserved for the file */

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

   242 

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

   244 	* 

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

   246 	* 					be reserved for the file

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

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

   249 

   250 	/** Issues the REST command.

   251 	* 

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

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

   254 

   255 	/** Issues the RNFR command.

   256 	* 

   257 	* @param aFileName	File name */

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

   259 

   260 	/** Issues the RNTO command.

   261 	* 

   262 	* @param aFileName	File name */

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

   264 

   265 	/** Issues the ABOR command. */

   266 	virtual void Abor(void)=0;

   267 

   268 	/** Issues the DELE command.

   269 	* 

   270 	* @param aFileName	File name */

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

   272 

   273 	/** Issues the RMD command.

   274 	* 

   275 	* @param aParam	Directory name */

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

   277 

   278 	/** Issues the MKD command.

   279 	* 

   280 	* @param aParam	Directory name */

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

   282 

   283 	/** Issues the PWD command. */

   284 	virtual void Pwd(void)=0;

   285 

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

   287 	virtual void List(void)=0;

   288 

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

   290 	* 

   291 	* @param aParam	File/directory name */

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

   293 

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

   295 	virtual void Nlst(void)=0;

   296 

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

   298 	* 

   299 	* @param aParam	Directory name */

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

   301 

   302 	/** Issues the SITE command.

   303 	* 

   304 	* @param aParam	SITE command argument */

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

   306 

   307 	/** Issues the SYST command. */

   308 	virtual void Syst(void)=0;

   309 

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

   311 	* 

   312 	* @param aParam	STAT command argument */

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

   314 

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

   316 	virtual void Stat(void)=0;

   317 

   318 	/** Issues the HELP command.

   319 	* 

   320 	* @param aParam	HELP command argument */

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

   322 

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

   324 	virtual void Help(void)=0;

   325 

   326 	/** Issues the NOOP command. */

   327 	virtual void Noop(void)=0;

   328 

   329 // Buffer management for transfer

   330 	// Following functions pass a pointer to a buffer

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

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

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

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

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

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

   337 	// the data

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

   339 	* 

   340 	* @param aBuffer	Send receive */

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

   342 

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

   344 	* 

   345 	* @param aBuffer	Receive buffer */

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

   347 

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

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

   350 

   351 	/** Cancels current operation. */

   352 	virtual void UserCancel(void)=0;

   353 

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

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

   356 	* 

   357 	* @param aServerAnswer	3 digit answer */

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

   359 

   360 	/**

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

   362 	MINOR_VERSION in the next byte

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

   364 	*/

   365 	IMPORT_C static TUint32 GetVersion(void);

   366 

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

   368 	* 

   369 	* @return	New FTP engine object

   370 	*/

   371 	// @param aNotifier Client callback interface. 

   372 	// The FTP engine calls this interface to pass 

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

   374 	IMPORT_C static CFtpProtocol *NewL(MFtpProtocolNotifier*);

   375 

   376 	/**Destructor.*/

   377 	virtual ~CFtpProtocol();

   378 	};

   379 #endif //__FTPPROT_H__