Symbian^3 Application Developer Library >

CFTPSession Class Reference

class CFTPSession : public CBase

Abstracts the complexity of the full FTP protocol and exports only a few simplified APIs.

Inherits from

Public Member Functions
~CFTPSession ()
void Cancel ()
void ChangeDirectory (const TDesC8 &)
void Close ()
void Connect (const TSockAddr &, const TDesC8 &, const TDesC8 &, const TConnectionMode )
void Connect (const THostName &, const TDesC8 &, const TDesC8 &, const TConnectionMode , const TUint )
void CreateDirectory (const TDesC8 &)
void DeleteDirectory (const TDesC8 &)
void DeleteFile (const TDesC8 &)
void GetCurrentDirectory (void)
IMPORT_C TUint32 GetVersion (void)
void ListDirectory (const TDesC8 &, TDes8 &)
IMPORT_C CFTPSession * NewL ( MFtpSessionNotifier *)
void RenameFile (const TDesC8 &, const TDesC8 &)
void Restart (const TUint )
void Retrieve (const TDesC8 &, const TDesC &, const TOpenMode , const RepresentationType , const TransferMode )
void Store (const TDesC &, const TDesC8 &, const TBool , const RepresentationType , const TransferMode )
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Public Member Enumerations
enum RepresentationType { EUninitialised  = 0, EBinary , EASCII }
enum TConnectionMode { EActive  = 0, Epassive }
enum TOpenMode { EOverwrite , ENoOverwrite , EExpand }
enum TransferMode { EStream  = 0, Eblock }

Constructor & Destructor Documentation

~CFTPSession()

~CFTPSession ( ) [virtual]

Destructor.

Member Functions Documentation

Cancel()

void Cancel ( ) [pure virtual]

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() .

ChangeDirectory(const TDesC8 &)

void ChangeDirectory ( const TDesC8 & aDirectoryName ) [pure virtual]

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() .

Parameters

const TDesC8 & aDirectoryName Directory name

Close()

void Close ( ) [pure virtual]

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.

Connect(const TSockAddr &, const TDesC8 &, const TDesC8 &, const TConnectionMode)

void Connect ( const TSockAddr & aNetAddr,
const TDesC8 & aUserName,
const TDesC8 & aPassword,
const TConnectionMode aConnectionMode = EActive
) [pure virtual]

Construction 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() .

Parameters

const TSockAddr & aNetAddr FTP server's IP address
const TDesC8 & aUserName User name to log on the FTP server
const TDesC8 & aPassword Password to identify to the FTP server
const TConnectionMode aConnectionMode = EActive Connection mode (passive or active, see RFC959). You must use passive mode if the client is behind a firewall.

Connect(const THostName &, const TDesC8 &, const TDesC8 &, const TConnectionMode, const TUint)

void Connect ( const THostName & aServerName,
const TDesC8 & aUserName,
const TDesC8 & aPassword,
const TConnectionMode aConnectionMode = EActive,
const TUint aPort =  KDefaultServerPiPort
) [pure virtual]

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() .

Parameters

const THostName & aServerName FTP server's DNS name
const TDesC8 & aUserName User name to log on the FTP server
const TDesC8 & aPassword Password to identify to the FTP server
const TConnectionMode aConnectionMode = EActive Connection mode (passive or active, see RFC959). You must use passive mode if the client is behind a firewall.
const TUint aPort =  KDefaultServerPiPort Port to connect to initiate the PI connection (see RFC959)

CreateDirectory(const TDesC8 &)

void CreateDirectory ( const TDesC8 & aDirectoryName ) [pure virtual]

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() .

Parameters

const TDesC8 & aDirectoryName A directory name. This can be absolute or relative.

DeleteDirectory(const TDesC8 &)

void DeleteDirectory ( const TDesC8 & aDirectoryName ) [pure virtual]

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() .

Parameters

const TDesC8 & aDirectoryName A directory name. This can be absolute or relative.

DeleteFile(const TDesC8 &)

void DeleteFile ( const TDesC8 & aFileName ) [pure virtual]

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() .

Parameters

const TDesC8 & aFileName A file name

GetCurrentDirectory(void)

void GetCurrentDirectory ( void ) [pure virtual]

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: 

         257 "/developr/rfc" is current directory.
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() : 
         257 "/developr
Second call of MFtpSessionNotifier::ServerMessage() : 
         /rfc" is current directory.

Completion is indicated by a callback to one of MFtpSessionNotifier::Complete() , MFtpSessionNotifier::ConnReset() , MFtpSessionNotifier::RemoteFileSystemError() or MFtpSessionNotifier::EUnknownError() .

Parameters

void

GetVersion(void)

IMPORT_C TUint32 GetVersion ( void ) [static]

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

Gets API version information.

The vesion information format is:

  • byte 3: ftpsess dll major version

  • byte 2: ftpsess dll minor version

  • byte 1: ftpprot dll major version

  • byte 0: ftpprot dll minor version

Parameters

void

ListDirectory(const TDesC8 &, TDes8 &)

void ListDirectory ( const TDesC8 & aDirectoryName,
TDes8 & aFileList
) [pure virtual]

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() .

Parameters

const TDesC8 & aDirectoryName A directory name. This can be absolute or relative.
TDes8 & aFileList On completion, the file list. The buffer is allocated by the client.

NewL(MFtpSessionNotifier *)

IMPORT_C CFTPSession * NewL ( MFtpSessionNotifier * aNotifier ) [static]

Allocates and constructs a new FTP session object.

Parameters

MFtpSessionNotifier * 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.

RenameFile(const TDesC8 &, const TDesC8 &)

void RenameFile ( const TDesC8 & aRemoteFileName,
const TDesC8 & aNewRemoteFileName
) [pure virtual]

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() .

Parameters

const TDesC8 & aRemoteFileName An existing file name
const TDesC8 & aNewRemoteFileName A new file name

Restart(const TUint)

void Restart ( const TUint aTFTPRestartOffset ) [pure virtual]

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() .

Parameters

const TUint aTFTPRestartOffset An offset in bytes in the file from where transfer is to be resumed

Retrieve(const TDesC8 &, const TDesC &, const TOpenMode, const RepresentationType, const TransferMode)

void Retrieve ( const TDesC8 & aRemoteFileName,
const TDesC & aNewLocalFileName,
const TOpenMode aOpenMode = EOverwrite,
const RepresentationType aRepresentationType = EBinary,
const TransferMode aTransferMode = EStream
) [pure virtual]

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() .

Parameters

const TDesC8 & aRemoteFileName The remote file Name
const TDesC & aNewLocalFileName Name of the local file to be created
const TOpenMode aOpenMode = EOverwrite Specifies whether to overwrite a local file with the same name if it already exists
const RepresentationType aRepresentationType = EBinary The representation type of the transferred file, ASCII or Binary
const TransferMode aTransferMode = EStream The transfer mode, stream mode or block mode. This is ignored and assumed to be stream, as block mode seems to be obsolete.

Store(const TDesC &, const TDesC8 &, const TBool, const RepresentationType, const TransferMode)

void Store ( const TDesC & aLocalFileName,
const TDesC8 & aNewRemoteFileName,
const TBool aOverwrite = EFalse,
const RepresentationType aRepresentationType = EBinary,
const TransferMode aTransferMode = EStream
) [pure virtual]

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() .

Parameters

const TDesC & aLocalFileName Name of the local file to be transferred
const TDesC8 & aNewRemoteFileName Name of the remote file to be created
const TBool aOverwrite = EFalse 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
const RepresentationType aRepresentationType = EBinary The representation type of the transferred file, ASCII or Binary
const TransferMode aTransferMode = EStream The transfer mode, stream mode or block mode. This is ignored and assumed to be stream, as block mode seems to be obsolete.

Member Enumerations Documentation

Enum RepresentationType

Representation type of a transferred file.

Enumerators

EUninitialised = 0

Uninitialised.

EBinary

File transfered in Binary mode, no translation.

EASCII

File transfered in ASCII mode, translation.

Enum TConnectionMode

FTP connection mode (passive or active see RFC959).

Enumerators

EActive = 0

Active mode. Server initiates DTP connection to client.

Epassive

Passive mode. Client initiates DTP connection to server.

Enum TOpenMode

FTP file open mode.

Enumerators

EOverwrite

Overwrite existing file.

ENoOverwrite

Do not overwrite existing file.

EExpand

Expand existing file.

Enum TransferMode

FTP file transfer mode.

Enumerators

EStream = 0

Stream mode; file transfered as a stream of bytes.

Eblock

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

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.