2 * Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * EPOC32 FTP Engine header file
16 * Author: Philippe Gabriel
17 * Exports set of APIs simplyfying access to the FTP protocol
31 #if !defined(__FTPSESS_H__)
38 The very first release
41 /** FTPSESS.DLL major version number. */
42 #define FTPSESS_VERSION_MAJOR 0x01 // The very first release
43 /** FTPSESS.DLL minor version number. */
44 #define FTPSESS_VERSION_MINOR 0x03
45 /** FTPSESS.DLL version number. */
46 #define FTPSESS_VERSION_NUMBER (FTPSESS_VERSION_MAJOR<<8)|FTPSESS_VERSION_MINOR
48 // Following Def as per RFC 959
49 /** Default server port.
51 const TUint KDefaultServerPiPort = 21;
53 // MInterface definition to provide callback functions to the client
56 class MFtpSessionNotifier
57 /** FTP session callback interface.
59 * An FTP session client implements this interface to receive status and results
60 * from asynchronous FTP operations.
62 * Note that, as defined in RFC959, FTP does not allow concurrent execution of
63 * several requests. Hence, even though calling an FTP function and getting the
64 * result through this interface are asynchronous operations, these events happen
65 * in a sequential manner. Each notification that the client receives corresponds
66 * to only one currently outstanding operation.
72 // Operation completion return codes.
74 /** FTP engine/session operation completeness codes. */
77 /** Operation completed normally. */
78 EOpComplete=0, // No error
79 /** Operation cancelled. */
80 EOpCanceled, // User canceled last operation
83 /** Connection error: Connect address invalid. */
84 EHostNotExist, // Connect address invalid
85 /** Connection error: Sockets level error. */
86 ESocketError, // Problem with socket operation
87 /** Connection error: Connection failed. */
88 EConnectionFailed, // Can't connect to FTP port
89 /** Connection error: Password needed. */
91 /** Connection error: Anonymous login not permitted. */
92 EAccountNeeded, // i.e. anonymous login disallowed
93 /** Connection error: UserName, Password combination invalid. */
94 ELoginFailed, // UserName,Password combination invalid
95 /** Connection error: Not connected to a server. */
96 ENotConnected, // Not connected to a server
97 /** Connection error: Already connected to a server. */
98 EAlreadyConnected, // Already connected to a server
99 /** Connection error: Operation timed out. */
100 ETimedOut, // Inactive for too long
102 //Local filesystem errors
103 /** Local filesystem error: General file system error. */
105 /** Local filesystem error: File opening failure. */
107 /** Local filesystem error: File reading failure. */
109 /** Local filesystem error: File writing failure. */
111 /** Local filesystem error: File already exists. */
113 /** Local filesystem error: File does not exist. */
115 /** Local filesystem error: Directory already exists. */
117 /** Local filesystem error: Directory does not exist. */
121 /** Permission error: Permission denied. */
124 //Remote filesystem errors
125 /** Remote filesystem error: General remote file system error. */
126 ERemoteFileSystemError,
127 /** Remote filesystem error: Remote file opening failure. */
128 ERemoteFileOpenFailure,
129 /** Remote filesystem error: Remote file reading failure. */
130 ERemoteFileReadError,
131 /** Remote filesystem error: Remote file writing failure. */
132 ERemoteFileWriteError,
133 /** Remote filesystem error: Remote file already exists. */
134 ERemoteFileAlreadyExist,
135 /** Remote filesystem error: Remote file does not exist. */
137 /** Remote filesystem error: Remote directory already exists. */
138 ERemoteDirAlreadyExist,
139 /** Remote filesystem error: Remote directory does not exist. */
141 /** Remote filesystem error: Restart is not supported. */
145 /** Normal operation completion. */
146 virtual void Complete(void)=0;
148 // Operation completed, more data to follow
149 /** Operation partially completed, with more data to follow. */
150 virtual void MoreData(void)=0;
152 /** Reports the amount of data already transferred in bytes.
154 * @param aProgress Amount of data already transferred */
155 virtual void TransferProgress(TUint aProgress)=0;
157 /** User cancelled an on-going operation. */
158 virtual void Cancel(void)=0;
160 /** Peer reset the connection. */
161 virtual void ConnReset(void)=0;
163 /** Error in establishing the connection with the FTP server.
165 * @param aTConnectionError Operation completion code */
166 virtual void ConnectionError(TOpComp aTConnectionError)=0;
168 // FTP server does not implement the operation requested
169 /** Restart operation not supported. */
170 virtual void OperationNotSupported(void)=0;
172 // Local File system error
173 /** Error with the local file system.
175 * @param aTLocalFileSystemError Operation completion code */
176 virtual void LocalFileSystemError(TOpComp aTLocalFileSystemError)=0;
178 // Remote File system error
179 /** Error with the remote file system.
181 * @param aTRemoteFileSystemError Operation completion code */
182 virtual void RemoteFileSystemError(TOpComp aTRemoteFileSystemError)=0;
185 /** Unspecified error. */
186 virtual void EUnknownError()=0;
188 // Message reported by server
189 /** Message sent by the FTP server.
191 * As specified by the RFC, the server answers all requests from the
192 * client with a plain text message beginning with a 3 digit code.
193 * The error/completion notifications sent back by the FTP session API
194 * are derived from these codes. Additionally, this function can be
195 * used to get the full string reporting the result of the request.
196 * It is recommended that the user interface displays this string to
197 * the user, as this gives a more precise idea of the result of the
198 * requested operation, especially in case of error.
200 * @param TDesC8 The message sent by the server */
201 virtual void ServerMessage(const TDesC8&)=0;
204 // The CFTPSession class
206 class CFTPSession : public CBase
208 /** Abstracts the complexity of the full FTP protocol and exports only
209 * a few simplified APIs.
210 * @internalComponent */
213 /** FTP connection mode (passive or active see RFC959). */
216 /** Active mode. Server initiates DTP connection to client. */
217 EActive=0, //(see RFC959)
218 /** Passive mode. Client initiates DTP connection to server.*/
219 Epassive //(see RFC959)
221 /** Representation type of a transferred file. */
222 enum RepresentationType
224 /** Uninitialised. */
226 /** File transfered in Binary mode, no translation. */
228 /** File transfered in ASCII mode, translation. */
231 /** FTP file transfer mode. */
234 /** Stream mode; file transfered as a stream of bytes. */
236 /** Block mode; file transfered as blocks, with header needed to restart aborted transfer. */
239 /** FTP file open mode. */
242 /** Overwrite existing file. */
244 /** Do not overwrite existing file. */
246 /** Expand existing file. */
256 // Establish a connection with a server:
257 /** Connects to a remote FTP server, specifying the FTP server by a numeric IP
260 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
261 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(),
262 * or MFtpSessionNotifier::EUnknownError().
264 * @param aNetAddr FTP server's IP address
265 * @param aUserName User name to log on the FTP server
266 * @param aPassword Password to identify to the FTP server
267 * @param aConnectionMode Connection mode (passive or active, see RFC959).
268 * You must use passive mode if the client is behind a firewall. */
269 virtual void Connect( const TSockAddr& aNetAddr, //IP address
270 const TDesC8& aUserName,
271 const TDesC8& aPassword,
272 const TConnectionMode aConnectionMode=EActive)=0;
275 /** Connects to a remote FTP server, specifying the FTP server by a DNS name.
277 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
278 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(),
279 * or MFtpSessionNotifier::EUnknownError().
281 * @param aServerName FTP server's DNS name
282 * @param aUserName User name to log on the FTP server
283 * @param aPassword Password to identify to the FTP server
284 * @param aConnectionMode Connection mode (passive or active, see RFC959). You
285 * must use passive mode if the client is behind a firewall.
286 * @param aPort Port to connect to initiate the PI connection (see RFC959) */
287 virtual void Connect( const THostName& aServerName, //DNS name
288 const TDesC8& aUserName,
289 const TDesC8& aPassword,
290 const TConnectionMode aConnectionMode=EActive,
291 const TUint aPort=KDefaultServerPiPort)=0;
294 // Close connection with a server
295 /** Closes the current connection with the FTP server.
297 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
298 * MFtpSessionNotifier::ConnReset(), or MFtpSessionNotifier::EUnknownError().
300 * This cannot be called when an operation is in progress. */
301 virtual void Close()=0;
304 // Cancel last FTP operation
305 /** Cancels the last FTP operation.
307 * Cancel is only implemented for lengthy operations, that is: Connect(), Store(),
308 * Retrieve(), and ListDirectory(). For these operations, once cancel has been
309 * called, the MFtpSessionNotifier::Cancel() callback is called.
311 * For other operations, calling Cancel() has no effect (it would take longer to
312 * wait for an acknowledgement to the Cancel(), than waiting for the result of
313 * the current operation). However, a completion callback will be called, as
314 * well as MFtpSessionNotifier::Cancel(). */
315 virtual void Cancel()=0;
318 // Restart an aborted transfer operation
319 /** After a connection is re-established, restarts the last aborted transfer operation
320 * (i.e. Store/Retrieve).
322 * It is the responsibility of the client to remember and reset the state of
323 * the connection before attempting to resume the transfer: i.e. the client should
324 * re-establish the connection to the server and return to the relevant directory,
325 * then it should issue the Restart() command with the offset it has saved, and
326 * then issue the Store() or Retrieve() command.
328 * The Restart() command should be avoided if the transfer was done in ASCII mode,
329 * as, because the server peforms a conversion on the bytestream format that
330 * it gets from the file before sending, the file size on the receiving end will
331 * be different than the size on the sending end. This means it is not possible
332 * to compute an offset for the sending end.
334 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
335 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::OperationNotSupported(),
336 * or MFtpSessionNotifier::EUnknownError().
338 * @param aTFTPRestartOffset An offset in bytes in the file from where transfer
339 * is to be resumed */
340 virtual void Restart(const TUint aTFTPRestartOffset)=0;
345 // Store a file on the server
346 /** Transfers a file to the FTP server.
348 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
349 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::ConnectionError(),
350 * MFtpSessionNotifier::LocalFileSystemError(), MFtpSessionNotifier::RemoteFileSystemError()
351 * or MFtpSessionNotifier::EUnknownError().
353 * @param aLocalFileName Name of the local file to be transferred
354 * @param aNewRemoteFileName Name of the remote file to be created
355 * @param aOverwrite If ETrue, overwrite a remote file with the same name if it
356 * exists; if EFalse, fail if a remote file with the same name exists
357 * @param aRepresentationType The representation type of the transferred file, ASCII or Binary
358 * @param aTransferMode The transfer mode, stream mode or block mode. This is
359 * ignored and assumed to be stream, as block mode seems to be obsolete. */
360 virtual void Store( const TDesC& aLocalFileName,
361 const TDesC8& aNewRemoteFileName,
362 const TBool aOverwrite = EFalse,
363 const RepresentationType aRepresentationType = EBinary,
364 const TransferMode aTransferMode = EStream)=0;
367 // Get a file from the server
368 /** Transfers a file from the FTP server.
370 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
371 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::LocalFileSystemError(),
372 * MFtpSessionNotifier::RemoteFileSystemError() or MFtpSessionNotifier::EUnknownError().
374 * @param aRemoteFileName The remote file Name
375 * @param aNewLocalFileName Name of the local file to be created
376 * @param aOpenMode Specifies whether to overwrite a local file with the same
377 * name if it already exists
378 * @param aRepresentationType The representation type of the transferred file,
380 * @param aTransferMode The transfer mode, stream mode or block mode. This is
381 * ignored and assumed to be stream, as block mode seems to be obsolete. */
382 virtual void Retrieve( const TDesC8& aRemoteFileName,
383 const TDesC& aNewLocalFileName,
384 const TOpenMode aOpenMode = EOverwrite,
385 const RepresentationType aRepresentationType = EBinary,
386 const TransferMode aTransferMode = EStream)=0;
390 // File system management functions
392 /** Sets the current directory on the remote file system.
394 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
395 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
396 * or MFtpSessionNotifier::EUnknownError().
398 * @param aDirectoryName Directory name */
399 virtual void ChangeDirectory(const TDesC8& aDirectoryName)=0;
402 /** Creates a directory on the remote file system.
404 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
405 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
406 * or MFtpSessionNotifier::EUnknownError().
408 * @param aDirectoryName A directory name. This can be absolute or relative. */
409 virtual void CreateDirectory(const TDesC8& aDirectoryName)=0;
412 /** Deletes a directory on the remote file system.
414 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
415 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
416 * or MFtpSessionNotifier::EUnknownError().
418 * @param aDirectoryName A directory name. This can be absolute or relative. */
419 virtual void DeleteDirectory(const TDesC8& aDirectoryName)=0;
422 /** Gets the client's current directory on the remote file system.
424 * The result is returned to the MFtpSessionNotifier::ServerMessage() callback.
425 * The directory name is defined by the RFC as being enclosed between double
426 * quotes: for example, an answer will look like:
429 * 257 "/developr/rfc" is current directory.
431 * The client must implement a parser to find the text between quotes.
433 * The result can be passed in two or more consecutive calls of MFtpSessionNotifier::ServerMessage().
436 * First call of MFtpSessionNotifier::ServerMessage(): @code 257 "/developr @endcode
438 * Second call of MFtpSessionNotifier::ServerMessage(): @code /rfc" is current directory. @endcode
440 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
441 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
442 * or MFtpSessionNotifier::EUnknownError(). */
443 virtual void GetCurrentDirectory(void)=0;
446 /** Lists the files in a directory on the remote file system.
448 * On successful completion, the aFileList buffer contains the list of files
449 * as transmitted by the server. It is the responsibility of the client to parse
450 * this buffer to extract relevant information. aFileList is always appended
451 * to, so the client should set its current length to a meaningful value (i.e.
452 * 0, to fill the buffer from scratch).
454 * If the list of files is larger than the aFileList buffer, MFtpSessionNotifier::MoreData()
455 * is called. At this point, the client must reissue the ListDirectory() request
456 * until the MFtpSessionNotifier::Complete() is called.
458 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
459 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
460 * or MFtpSessionNotifier::EUnknownError().
462 * @param aDirectoryName A directory name. This can be absolute or relative.
463 * @param aFileList On completion, the file list. The buffer is allocated by the client. */
464 virtual void ListDirectory(const TDesC8& aDirectoryName,
468 /** Deletes a file on the remote file system.
470 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
471 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
472 * or MFtpSessionNotifier::EUnknownError().
474 * @param aFileName A file name */
475 virtual void DeleteFile(const TDesC8& aFileName)=0;
477 /** Renames a file on the remote file system.
479 * Completion is indicated by a callback to one of MFtpSessionNotifier::Complete(),
480 * MFtpSessionNotifier::ConnReset(), MFtpSessionNotifier::RemoteFileSystemError()
481 * or MFtpSessionNotifier::EUnknownError().
483 * @param aRemoteFileName An existing file name
484 * @param aNewRemoteFileName A new file name */
485 virtual void RenameFile(const TDesC8& aRemoteFileName,
486 const TDesC8& aNewRemoteFileName)=0;
491 ftpsess dll MAJOR_VERSION in msb of the msw
492 ftpsess dll MINOR_VERSION in lsb of the msw
493 ftpprot dll MAJOR_VERSION in msb of the lsw
494 ftpprot dll MINOR_VERSION in lsb of the lsw
496 IMPORT_C static TUint32 GetVersion(void);
498 /** Allocates and constructs a new FTP session object.
500 * @param aNotifier Callback interface to notify the client of the completion of
501 * operations or to report errors. For each FTP session, the FTP
502 * client should instantiate an object of this type.
503 * @return New FTP session object
505 IMPORT_C static CFTPSession* NewL(MFtpSessionNotifier* aNotifier);
508 virtual ~CFTPSession();