Collapse all Symbian^3 Product 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

CFTPSession
- CBase

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

(

)

[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.

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.

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.

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.

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.

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.

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.