Symbian^3 Application Developer Library >

CFileMan Class Reference

class CFileMan : public CFileBase

Offers file management services which accept the use of wildcards; synchronous and asynchronous.

It also provides enquiry functions, which, like those provided by the base class CFileBase , may be used by an observer class object to provide the user with information about the progress of the operation.

All of the file management functions provided by this class accept the use of wildcards, and may operate either synchronously or asynchronously. When CFileMan is operating asynchronously, the operation takes place in a separate thread from the calling code.

A file notification observer (an instance of a class deriving from MFileManObserver ) may optionally be used by CFileMan when operating synchronously or asynchronously. If provided, the appropriate notification function is called before or after each entry has been processed, or during a file copy or move. This notification can be used to provide information about the state of the operation, such as the number of bytes transferred during a large-scale file copy. It can also be used to allow the user to cancel, retry or continue processing an entry, or to abort the whole operation. If such notification is required, specify an object deriving from MFileManObserver class in the constructor, or call SetObserver() , defined in the base class, CFileBase .

All of the file manipulation functions except Rename() may operate recursively, and all can operate non-recursively. When operating recursively, these functions will act on all matching files located throughout the source directory s hierarchy. When operating non-recursively, these functions act upon files contained in the single top level source directory only. Recursion is set or unset using the switch parameter to these functions.

This class is not intended for user derivation.

Note:

To support wildcard, CFileMan needs to store the entire directory entry information. Therefore, in a extreme condition, if a directory contains a huge number of files (e.g. more than 15000 files with 10 characters' long file names), user may encounter KErrNoMemory errors. Developers who have a need to handle this rare case should increase the heap size limitation of their applications.

For more information about heap size configuration, please refer following section in Symbian Developer Library: Symbian OS build guide >> Build Tools Reference >> MMP file syntax >> epocheapsize

MFileManObserver

Inherits from

Public Member Functions
~CFileMan ()
IMPORT_C TInt Attribs (const TDesC &, TUint , TUint , const TTime &, TUint )
IMPORT_C TInt Attribs (const TDesC &, TUint , TUint , const TTime &, TUint , TRequestStatus &)
IMPORT_C TInt BytesTransferredByCopyStep ()
IMPORT_C TInt Copy (const TDesC &, const TDesC &, TUint )
IMPORT_C TInt Copy (const TDesC &, const TDesC &, TUint , TRequestStatus &)
IMPORT_C TInt Copy (const RFile &, const TDesC &, TUint )
IMPORT_C TInt Copy (const RFile &, const TDesC &, TUint , TRequestStatus &)
IMPORT_C TAction CurrentAction ()
IMPORT_C TInt Delete (const TDesC &, TUint )
IMPORT_C TInt Delete (const TDesC &, TUint , TRequestStatus &)
IMPORT_C void GetCurrentSource ( TFileName &)
IMPORT_C void GetCurrentTarget ( TFileName &)
IMPORT_C TInt Move (const TDesC &, const TDesC &, TUint )
IMPORT_C TInt Move (const TDesC &, const TDesC &, TUint , TRequestStatus &)
IMPORT_C CFileMan * NewL ( RFs &)
IMPORT_C CFileMan * NewL ( RFs &, MFileManObserver *)
IMPORT_C TInt Rename (const TDesC &, const TDesC &, TUint )
IMPORT_C TInt Rename (const TDesC &, const TDesC &, TUint , TRequestStatus &)
IMPORT_C TInt RmDir (const TDesC &)
IMPORT_C TInt RmDir (const TDesC &, TRequestStatus &)
Protected Member Functions
CFileMan ( RFs &)
TInt RenameInvalidEntry (const TDesC &, const TDesC &, TUint )
Private Member Functions
void CheckForDirectory ()
TInt CheckRenameAllowed (const TDesC &, const TDesC &)
void CompleteOperationL ()
void DoAttribsL ()
TInt DoCopy (const RFile &, RFile &, TInt &)
void DoCopyFromHandleL ()
void DoCopyOrMoveL ()
void DoDeleteL ()
void DoOperationL ()
void DoRenameL ()
void DoRmDirL ()
void DoSynchronize ( TInt )
void GetSrcAndTrg ( TParse &, TFileName &)
void SetFlags ( TBool , TBool , TBool , TBool )
TInt SetupDirectoryForMove ( TBool &)
TInt SetupMoveAcrossDrives ( TUint )
TInt SetupMoveOnSameDrive ( TUint , TBool &)
TInt SetupTargetDirectory ( TBool , TBool &)
TBool SrcTrgDrivesIdentical ()
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()
CFileBase::AbbreviatedPath()
CFileBase::CFileBase(RFs &)
CFileBase::ConstructL()
CFileBase::CurrentEntry()
CFileBase::FullPath()
CFileBase::GetLastError()
CFileBase::GetMoreInfoAboutError()
CFileBase::RunInSeparateThreadL(TThreadFunction)
CFileBase::RunL()
CFileBase::SetObserver(MFileManObserver *)
CFileBase::~CFileBase()
Public Member Enumerations
enum TAction {
ENone , EAttribs , ECopy , EDelete , EMove , ERename , ERmDir , ERenameInvalidEntry , ECopyFromHandle
}
enum TSwitch { EOverWrite  = 1, ERecurse  = 2 }
Private Member Enumerations
enum TInternalAction {
EInternalNone , EInternalAttribs , EInternalCopy , EInternalDelete , EInternalCopyForMove , EInternalRenameForMove , EInternalRename , EInternalRmDir , EInternalRenameInvalidEntry , EInternalCopyFromHandle
}
Private Attributes
TInternalAction iAction
TInt iBytesTransferred
TUint iClearMask
TBool iMovingContents
TUint iSetMask
RFile iSrcFileHandle
TTime iTime
TEntry iTmpEntry
TFileName iTmpName1
TFileName iTmpName2
TParse iTmpParse
TParse iTrgFile
Inherited Attributes
CFileBase::iCurrentEntry
CFileBase::iDirList
CFileBase::iErrorInfo
CFileBase::iFManThread
CFileBase::iFs
CFileBase::iFsOld
CFileBase::iLastError
CFileBase::iMatchEntry
CFileBase::iNumberOfFilesProcessed
CFileBase::iObserver
CFileBase::iScanner
CFileBase::iSessionPath
CFileBase::iSrcFile
CFileBase::iStatus
CFileBase::iSwitches
CFileBase::iSynchronizer

Constructor & Destructor Documentation

CFileMan(RFs &)

CFileMan ( RFs & aFs ) [protected]

Parameters

RFs & aFs

~CFileMan()

~CFileMan ( )

Member Functions Documentation

Attribs(const TDesC &, TUint, TUint, const TTime &, TUint)

IMPORT_C TInt Attribs ( const TDesC & aName,
TUint aSetMask,
TUint aClearMask,
const TTime & aTime,
TUint aSwitch = 0
)

Sets or clears attributes for one or more files using two bitmasks

This is a synchronous function.

The first bitmask specifies the attributes to be set. The second specifies the attributes to be cleared. The date and time of the files' last modification can also be changed.

The function can operate recursively or non-recursively. When operating non-recursively, only the matching files located in the directory specified in aName are affected. When operating recursively, all matching files in the directory hierarchy below the directory specified in aName will be affected.

Notes:

1. A panic is raised if any attribute is specified in both bitmasks.

2. Attempting to change the attributes for an open file results in an error for that file, as retrieved by CFileBase::GetLastError() .

3. An attempt to set or clear the KEntryAttDir or KEntryAttVolume attribute for a file or directory will have no effect.

capability
Dependent If aName is /Sys then Tcb capability is required.
capability
Dependent If aName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If aName is /Resource then Tcb capability is required.

Parameters

const TDesC & aName Path indicating the file(s) whose attributes are to be changed. Any path components which are not specified here will be taken from the session path. Use wildcards to specify more than one file.
TUint aSetMask Bitmask indicating the attributes to be set.
TUint aClearMask Bitmask indicating the attributes to be cleared. For more information, see KEntryAttNormal and the other file/directory attributes.
const TTime & aTime Contains the new modification date and time for the files, in UTC. To preserve the file's timestamps, specify a TTime value of 0.
TUint aSwitch = 0 Specify zero for no recursion; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively.

Attribs(const TDesC &, TUint, TUint, const TTime &, TUint, TRequestStatus &)

IMPORT_C TInt Attribs ( const TDesC & aName,
TUint aSetMask,
TUint aClearMask,
const TTime & aTime,
TUint aSwitch,
TRequestStatus & aStatus
)

Sets or clears attributes for one or more files using two bitmasks.

This is an asynchronous function. Its behaviour is the same as the synchronous overload.

capability
Dependent If aName is /Sys then Tcb capability is required.
capability
Dependent If aName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If aName is /Resource then Tcb capability is required.

Parameters

const TDesC & aName Path indicating the file(s) whose attributes are to be changed. Any path components which are not specified here will be taken from the session path. Use wildcards to specify more than one file.
TUint aSetMask Bitmask indicating the attributes to be set.
TUint aClearMask Bitmask indicating the attributes to be cleared. For more information, see KEntryAttNormal and the other file/directory attributes.
const TTime & aTime Contains the new modification date and time for the files, in UTC. To preserve the file's timestamps, specify a TTime value of 0.
TUint aSwitch Specify zero for no recursion; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone, if successful, otherwise one of the other system-wide error codes.

BytesTransferredByCopyStep()

IMPORT_C TInt BytesTransferredByCopyStep ( )

Gets the number of bytes transferred during a copy or move operation.

Large files are copied and moved in stages. After each portion of the source file has been copied to the target, the number of bytes transferred is updated. This function may be called from MFileManObserver::NotifyFileManOperation() and may be used to support the increment of progress bars.

CheckForDirectory()

void CheckForDirectory ( ) [private]

CheckRenameAllowed(const TDesC &, const TDesC &)

TInt CheckRenameAllowed ( const TDesC & aSrcName,
const TDesC & aTrgName
) [private]

Parameters

const TDesC & aSrcName
const TDesC & aTrgName

CompleteOperationL()

void CompleteOperationL ( ) [private, virtual]

Called from RunL to perform tidy up after an operation.

CFileMan CFileBase::RunL

Copy(const TDesC &, const TDesC &, TUint)

IMPORT_C TInt Copy ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch = EOverWrite
)

Parameters

const TDesC & anOld
const TDesC & aNew
TUint aSwitch = EOverWrite

Copy(const TDesC &, const TDesC &, TUint, TRequestStatus &)

IMPORT_C TInt Copy ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch,
TRequestStatus & aStatus
)

Copies one or more files.

This is an asynchronous function. Its behaviour is the same as the synchronous overload.

capability
AllFiles
capability
Dependent If the path for aNew begins with /Sys then Tcb capability is required.
capability
Dependent If the path for aNew begins with /Resource then Tcb capability is required

Parameters

const TDesC & anOld Path indicating the file(s) to be copied. Any path components which are not specified here will be taken from the session path.
const TDesC & aNew Path indicating the directory into which the file(s) are to be copied. Any path components which are not specified here will be taken from the session path
TUint aSwitch Specify zero for no overwriting and no recursion; CFileMan::EOverWrite to overwrite files with the same name; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively and with overwriting.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone, if successful, otherwise one of the other system-wide error codes.

Copy(const RFile &, const TDesC &, TUint)

IMPORT_C TInt Copy ( const RFile & anOld,
const TDesC & aNew,
TUint aSwitches = EOverWrite
)

Copies from an open file handle to a destination file name.

This is a synchronous function.

Optionally, this function can be set to overwrite the target file. If the flag is set for no overwriting and the target file already exists, then the target file will not be overwritten, and an error (KErrAlreadyExists) will be returned. Error codes may be retrieved using CFileBase::GetLastError() .

Notes:

  1. The file can be copied across drives.

  2. Read-only, hidden and system files can be copied and the source file's attributes are preserved in the target file.

CFileBase::GetLastError() CFileMan::Move()
capability
Dependent If the path for aNew begins with /Sys then Tcb capability is required.
capability
Dependent If the path for aNew begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If the path for aNew begins with /Resource then Tcb capability is required.

Parameters

const RFile & anOld Open file handle indicating the file to be copied.
const TDesC & aNew Path indicating the directory (and optionally the filename) into which the file is to be copied. Any path components which are not specified here will be taken from the session path
TUint aSwitches = EOverWrite Specify zero for no overwriting; CFileMan::EOverWrite to overwrite files with the same name; Any other flags are illegal By default, the synchronous variant of this function operates with overwriting.

Copy(const RFile &, const TDesC &, TUint, TRequestStatus &)

IMPORT_C TInt Copy ( const RFile & anOld,
const TDesC & aNew,
TUint aSwitches,
TRequestStatus & aStatus
)

Copies from an open file handle to a destination file name.

This is an asynchronous function. Its behaviour is the same as the synchronous overload.

CFileBase::GetLastError()
capability
Dependent If the path for aNew begins with /Sys then Tcb capability is required.
capability
Dependent If the path for aNew begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If the path for aNew begins with /Resource then Tcb capability is required.

Parameters

const RFile & anOld Open file handle indicating the file to be copied.
const TDesC & aNew Path indicating the directory (and optionally the filename) into which the file is to be copied. Any path components which are not specified here will be taken from the session path
TUint aSwitches Specify zero for no overwriting; CFileMan::EOverWrite to overwrite files with the same name; Any other flags are illegal.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone, if successful, otherwise one of the other system-wide error codes.

CurrentAction()

IMPORT_C TAction CurrentAction ( )

Gets the action which CFileMan is currently carrying out.

Delete(const TDesC &, TUint)

IMPORT_C TInt Delete ( const TDesC & aName,
TUint aSwitch = 0
)

Deletes one or more files.

This is a synchronous function.

This function can operate recursively or non-recursively. When operating non-recursively, only the matching files located in the directory specified in aName are affected. When operating recursively, all matching files in the directory hierarchy below the directory specified in aName will be deleted.

Note that read-only and open files may not be deleted. Attempting to do so will return an error for that file. Error codes may be retrieved using CFileBase::GetLastError() .

CFileBase::GetLastError()
capability
Dependent If aName is /Sys then Tcb capability is required.
capability
Dependent If aName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If aName is /Resource then Tcb capability is required.
KNullDesC

Parameters

const TDesC & aName Path indicating the file(s) to be deleted. May either be a full path, or relative to the session path. Use wildcards to specify more than one file. NOTE: if you pass KNullDesC, the empty (or null) descriptor, then the function interprets this to mean \*.*
TUint aSwitch = 0 Specify: zero for no recursion; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively.

Delete(const TDesC &, TUint, TRequestStatus &)

IMPORT_C TInt Delete ( const TDesC & aName,
TUint aSwitch,
TRequestStatus & aStatus
)

Deletes one or more files.

This is an asynchronous function. Its behaviour is the same as the synchronous overload.

capability
Dependent If aName is /Sys then Tcb capability is required.
capability
Dependent If aName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If aName is /Resource then Tcb capability is required.
KNullDesC

Parameters

const TDesC & aName Path indicating the file(s) to be deleted. May either be a full path, or relative to the session path. Use wildcards to specify more than one file. NOTE: if you pass KNullDesC, the empty (or null) descriptor, then the function interprets this to mean \*.*
TUint aSwitch Specify: zero for no recursion; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone, if successful, otherwise one of the other system-wide error codes.

DoAttribsL()

void DoAttribsL ( ) [private]

DoCopy(const RFile &, RFile &, TInt &)

TInt DoCopy ( const RFile & aSrcFile,
RFile & aDstFile,
TInt & aRet
) [private]

Parameters

const RFile & aSrcFile
RFile & aDstFile
TInt & aRet

DoCopyFromHandleL()

void DoCopyFromHandleL ( ) [private]

DoCopyOrMoveL()

void DoCopyOrMoveL ( ) [private]

DoDeleteL()

void DoDeleteL ( ) [private]

DoOperationL()

void DoOperationL ( ) [private, virtual]

Called from RunL to perform the requested operation.

CFileMan CFileBase::RunL

DoRenameL()

void DoRenameL ( ) [private]

DoRmDirL()

void DoRmDirL ( ) [private]

DoSynchronize(TInt)

void DoSynchronize ( TInt aRetVal ) [private]

Parameters

TInt aRetVal

GetCurrentSource(TFileName &)

IMPORT_C void GetCurrentSource ( TFileName & aFile )

Gets the name of the source file or directory for the CFileMan operation currently being carried out.

The source is the file or directory which is being copied, moved or deleted.

Parameters

TFileName & aFile The full path and filename of the source file for the current CFileMan operation.

GetCurrentTarget(TFileName &)

IMPORT_C void GetCurrentTarget ( TFileName & aFile )

Gets the name of the target file for the CFileMan operation currently being carried out.

This function is relevant when copying, moving or renaming files.

Parameters

TFileName & aFile The full path and filename of the target file for the current CFileMan operation

GetSrcAndTrg(TParse &, TFileName &)

void GetSrcAndTrg ( TParse & aSrcName,
TFileName & aTrgName
) [private]

Parameters

TParse & aSrcName
TFileName & aTrgName

Move(const TDesC &, const TDesC &, TUint)

IMPORT_C TInt Move ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch = EOverWrite
)

Moves one or more files.

This is a synchronous function.

Optionally, this function can be set to overwrite any files with the same name which exist in the target directory. If the flag is set for no overwriting, then any files with the same name will not be overwritten, and an error (KErrAlreadyExists) will be returned for that file. Error codes may be retrieved using CFileBase::GetLastError() . By default, when the function is operating synchronously, files are overwritten.

When this function is operating recursively, all intermediate directories will be created, including all directories in the destination path specified by aNew which do not already exist.

If recursive operation is not set, only the matching files located in the single directory specified in anOld are moved. No intermediate directories will be created; if any directories in the destination path do not exist, no files will be moved, and this function will return KErrPathNotFound.

The behaviour of the move operation is sensitive to the presence (or absence) of a trailing backslash ("\") character on the end of the source path:

  • if there is a trailing backslash ("\") character, then the operation moves the content of the last directory level only.

  • if there is no trailing backslash ("\") character, then the operation behaves recursively by default and moves both the last directory level and all of its content. Notice that no trailing backslash ("\") implies moving files recursively automatically.

For example, if the directory level "b" contains the files F1, F2 and F3, then: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Move(_L("C:\\a\\b\\"), _L("C:\\x\\y\\"), CFileMan::ERecurse);

results in files F1, F2 and F3 being moved from C:\a\b to C:\x\y, leaving the path C:\a\b unchanged, except that it no longer contains the files F1, F2 and F3.

If there is no trailing backslash character, for example: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Move(_L("C:\\a\\b"), _L("C:\\x\\y\\"), CFileMan::ERecurse);

then both the directory level "b" and its contents are moved. This means that there is no longer a directory "b" under C:\a. Instead there is a new directory structure C:\x\y\b and the files F1, F2, and F3 now exist under C:\x\y\b. Also if "b" contains subdirectories, then these are also moved along with "b".

If there is no trailing backslash character and the switch is not set, i.e. 0 is passed as an argument, the operation behaves the same way as by passing CFileMan::ERecurse flag.

For example: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Move(_L("C:\\a\\b"), _L("C:\\x\\y\\"), 0);

The example above produces the same output as: 

         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Move(_L("C:\\a\\b"), _L("C:\\x\\y\\"), CFileMan::ERecurse);

If the source (anOld) is a file and the recursive operation is set, then all the files with the same name as anOld in the source directory including those in subdirectories will be moved to the destination.

For example, the initial directory structure is as follows: C:.txt C:.txt C:.txt 

         CFileMan* fm(CFileMan::NewL(iFs));	// Where iFs is an RFs handle
fm->Move(_L("C:\\src\\file.txt"), _L("C:\\dest\\file.txt"), CFileMan::ERecurse);
// OR without specifying the filename in aNew:
fm->Move(_L("C:\\src\\file.txt"), _L("C:\\dest\\"), CFileMan::ERecurse);

Because of the recursive behaviour, the final directory structure after either one of the move operations above will be as follows: C:\ C:\ C:\ C:.txt C:.txt C:.txt

Notes:

  1. Read-only, hidden and system files can be moved and the source file's attributes are preserved in the target file, but open files cannot be moved. Attempting to move an open file will return an error for that file, as retrieved by CFileBase::GetLastError() .

capability
Dependent If the path in aNew starts with /Sys then capability Tcb is required
capability
Dependent If the path in aNew starts with /Resource then capability Tcb is required
capability
AllFiles
capability
Dependent If the path in anOld starts with /Sys then Tcb capability is required.
capability
Dependent If the path in anOld starts with /Resource then Tcb capability is required.
CFileBase::GetLastError()

Parameters

const TDesC & anOld Path indicating the directory/files to be moved. May be either a full path, or relative to the session path. Note that if you specify a directory level, then the behaviour of the move operation is sensitive to the presence (or absence) of a trailing backslash ("\") character. Any path components which are not specified here will be taken from the session path. See the main description for the detailed explanation.
const TDesC & aNew Path indicating the directory into which the file(s) are to be moved. Any path components which are not specified here will be taken from the session path.
TUint aSwitch = EOverWrite CFileMan::EOverWrite to overwrite files with the same name; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively and with overwriting. And no trailing backslash ("\") character at the end of source path always means CFileMan::ERecurse.

Move(const TDesC &, const TDesC &, TUint, TRequestStatus &)

IMPORT_C TInt Move ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch,
TRequestStatus & aStatus
)

Moves one or more files.

This is an asynchronous function. Its behaviour is the same as the synchronous overload.

capability
Dependent If the path in aNew starts with /Sys then capability Tcb is required
capability
Dependent If the path in aNew starts with /Resource then capability Tcb is required
capability
AllFiles
capability
Dependent If the path in anOld starts with /Sys then Tcb capability is required.
capability
Dependent If the path in anOld starts with /Resource then Tcb capability is required.

Parameters

const TDesC & anOld Path indicating the files to be moved. May be either a full path, or relative to the session path. Any path components which are not specified here will be taken from the session path.
const TDesC & aNew Path indicating the directory into which the file(s) are to be moved. Any path components which are not specified here will be taken from the session path.
TUint aSwitch Specify zero for no overwriting and no recursion; CFileMan::EOverWrite to overwrite files with the same name; CFileMan::ERecurse for recursion. By default, the synchronous variant of this function operates non-recursively and with overwriting.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone, if successful, otherwise one of the other system-wide error codes.

NewL(RFs &)

IMPORT_C CFileMan * NewL ( RFs & aFs ) [static]

Constructs and allocates memory for a new CFileMan object.

Parameters

RFs & aFs File server session.

NewL(RFs &, MFileManObserver *)

IMPORT_C CFileMan * NewL ( RFs & aFs,
MFileManObserver * anObserver
) [static]

Constructs and allocates memory for a new CFileMan object with an observer.

Parameters

RFs & aFs File server session.
MFileManObserver * anObserver File management observer.

Rename(const TDesC &, const TDesC &, TUint)

IMPORT_C TInt Rename ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch = EOverWrite
)

Renames one or more files, or a directory

This is a synchronous function.

The function can also be used to move files by specifying different destination and source directories.

Some rules for using CFileMan::Rename() :

1. General rules:

1.1. Trailing backslash ("\") in either source path (aName) or target path (aNewName) will be interpreted to "\*.*";

For example, following code should behave identically: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC\\"), _L("C:\\TRG\\"));
fm->Rename(_L("C:\\SRC\\*.*"), _L("C:\\TRG\\"));
fm->Rename(_L("C:\\SRC\\"), _L("C:\\TRG\\*.*"));
fm->Rename(_L("C:\\SRC\\*.*"), _L("C:\\TRG\\*.*"));

1.2 The behaviour of the rename operation is sensitive to the presence (or absence) of a trailing backslash ("\") character on the end of the target path (aNewName);

For example, under all other constraints (see rules 2. and 3.), 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG\"));
will result in renaming "C:\\SRC" to "C:\\TRG\\SRC", while 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG"));
will result in renaming "C:\\SRC" to "C:\\TRG".

2. Renaming file(s):

2.1 Wildcards:

A file's name and extension are interpreted separately, for example: 

         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC\\1234.567"), _L("C:\\TRG\\AB*CD.TXT"));
renames the source file to file "C:\\TRG\\AB34CD.TXT".
Wildcards can be used for renaming multiple files, for example; 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC\\*.567"), _L("C:\\TRG\\*.TXT"));
renames all the file under "C:\\SRC\\" having extension ".567" to the files under "C:\\TRG\\" having extension ".TXT".

2.2 An option is provided to allow the user to overwrite any files with the same name which may exist in the target directory; If the flag is set for no overwriting, any files with the same name will not be overwritten, and an error (KErrAlreadyExists) will be returned for that file, as retrieved by CFileBase::GetLastError() .

2.3 It can only operate non-recursively, so that only the matching files located in the single directory specified by anOld may be renamed.

2.4 Trying to rename file(s) to existing directory(ies) will fail;

For example, giving following directory structure: 
         C:\SRC\ITEM01
C:\SRC\ITEM02
C:\TRG\ITEM01\
C:\TRG\ITEM02\
Following code will fail: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC\\ITEM01"), _L("C:\\TRG\\ITEM01"));
fm->Rename(_L("C:\\SRC\\ITEM*"), _L("C:\\TRG\\ITEM*"));
fm->Rename(_L("C:\\SRC\\"), _L("C:\\TRG\\"));

3. When renamnig a directory:

3.1. Only when the trailing backslash ("\") is missing from the source path (aName), will the source directory be renamed, otherwise, see rule 1.1.

For example, following code will result in moving "C:\SRC" directory including all its contents: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG"));
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG\\"));
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG\\*.*"));

3.2. Wildcards can not be used for moving directories;

3.3. Overwriting is not permitted;

For example, giving directory structure as following: 
         C:\SRC\FILE.TXT
C:\TRG\
C:\TRG\SRC\
following code will fail: 
         CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG"));
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG\\"));
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG\\*.*"));

4. Notes:

4.1. The target and source directories must be on the same drive.

4.2. Read-only, hidden and system files can be moved and the source file's attributes are preserved in the target file, but open files cannot be moved. Attempting to move an open file will return an error for that file, as retrieved by CFileBase::GetLastError() .

CFileBase::GetLastError()
capability
Dependent If either aName or aNewName is /Sys then Tcb capability is required.
capability
Dependent If either aName or aNewName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If either aName or aNewName is /Resource then Tcb capability is required.

Parameters

const TDesC & anOld Path specifying the file(s) to be renamed. Any path components which are not specified here will be taken from the session path.
const TDesC & aNew Path specifying the new name for the files and/or the new directory. Any directories specified in this path that do not exist, will be created. Any path components which are not specified here will be taken from the session path.
TUint aSwitch = EOverWrite Specify zero for no overwriting; CFileMan::EOverWrite to overwrite files with the same name. This function cannot operate recursively.

Rename(const TDesC &, const TDesC &, TUint, TRequestStatus &)

IMPORT_C TInt Rename ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch,
TRequestStatus & aStatus
)

Renames one or more files.

This is an asynchronous function. Its behaviour is the same as the synchronous overload.

capability
Dependent If either aName or aNewName is /Sys then Tcb capability is required.
capability
Dependent If either aName or aNewName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If either aName or aNewName is /Resource then Tcb capability is required.

Parameters

const TDesC & anOld Path specifying the file(s) to be renamed. Any path components which are not specified here will be taken from the session path.
const TDesC & aNew Path specifying the new name for the files and/or the new directory. Any directories specified in this path that do not exist, will be created. Any path components which are not specified here will be taken from the session path.
TUint aSwitch Specify zero for no overwriting; CFileMan::EOverWrite to overwrite files with the same name. This function cannot operate recursively.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone, if successful, otherwise one of the other system-wide error codes.

RenameInvalidEntry(const TDesC &, const TDesC &, TUint)

TInt RenameInvalidEntry ( const TDesC & anOld,
const TDesC & aNew,
TUint aSwitch = EOverWrite
) [protected]

Parameters

const TDesC & anOld
const TDesC & aNew
TUint aSwitch = EOverWrite

RmDir(const TDesC &)

IMPORT_C TInt RmDir ( const TDesC & aDirName )

Deletes a directory and all files and directories contained in the directory structure below it.

This is a synchronous function.

The function cannot be used non-recursively. For a non-recursive directory deletion, use RFs::RmDir() .

Note:

1. All files in the directory hierarchy to be deleted must be closed and none may have the read-only attribute. Otherwise, not all of the hierarchy will be deleted, and this function will return KErrInUse.

capability
Dependent If aDirName starts with /Sys then Tcb capability is required.
capability
Dependent If aDirName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If aDirName starts with /Resource then Tcb capability is required.

Parameters

const TDesC & aDirName Path specifying the directory to be deleted. Any path components which are not specified here will be taken from the session path.

RmDir(const TDesC &, TRequestStatus &)

IMPORT_C TInt RmDir ( const TDesC & aDirName,
TRequestStatus & aStatus
)

Deletes a directory and all files and directories contained in the directory structure below it.

Other than being asynchronous, the behaviour of this function is the same as is documented in its synchronous overload.

capability
Dependent If aDirName starts with /Sys then Tcb capability is required.
capability
Dependent If aDirName begins with /Private and does not match this process' SID then AllFiles capability is required.
capability
Dependent If aDirName starts with /Resource then Tcb capability is required.

Parameters

const TDesC & aDirName Path specifying the directory to be deleted. Any path components which are not specified here will be taken from the session path.
TRequestStatus & aStatus The request status object. On request completion, indicates how the request completed: KErrNone if successful, otherwise one of the other system-wide error codes.

SetFlags(TBool, TBool, TBool, TBool)

void SetFlags ( TBool aOverWrite,
TBool aRecurse,
TBool aScanDirection,
TBool aMoveRename
) [private]

Parameters

TBool aOverWrite
TBool aRecurse
TBool aScanDirection
TBool aMoveRename

SetupDirectoryForMove(TBool &)

TInt SetupDirectoryForMove ( TBool & aSrcIsDir ) [private]

Sets up the target specification to include the new target directory if required.

Parameters

TBool & aSrcIsDir Set to ETrue if the source specifies that the directory is to be moved in its entirety, or EFalse if only the contents of the directory need to be moved.

SetupMoveAcrossDrives(TUint)

TInt SetupMoveAcrossDrives ( TUint aSwitches ) [private]

Parameters

TUint aSwitches

SetupMoveOnSameDrive(TUint, TBool &)

TInt SetupMoveOnSameDrive ( TUint aSwitches,
TBool & aComplete
) [private]

Parameters

TUint aSwitches
TBool & aComplete

SetupTargetDirectory(TBool, TBool &)

TInt SetupTargetDirectory ( TBool aOverWrite,
TBool & aComplete
) [private]

Parameters

TBool aOverWrite
TBool & aComplete

SrcTrgDrivesIdentical()

TBool SrcTrgDrivesIdentical ( ) [private]

Member Enumerations Documentation

Enum TAction

An enumeration that identifies CFileMan tasks. This enumeration is used by CurrentAction() to identify which task currently being carried out.

CFileMan::CurrentAction

Enumerators

ENone

Inactive

EAttribs

Setting attributes

ECopy

Copying files

EDelete

Deleting files

EMove

Moving files

ERename

Renaming files

ERmDir

Deleting a directory and all contents

ERenameInvalidEntry

Renaming component to VFAT short name (guaranteed to be unique)

ECopyFromHandle

Copying file from open file handle

Enum TInternalAction

This is an internal enumeration for CFileMan implementation. THis enumeration is mapped into TAction when user wants to identify the current task of CFileMan by CurrentAction() .

CFileMan::TAction CFileMan::CurrentAction

Enumerators

EInternalNone

Internal indicator for None operation. This is mapped to CFileMan::ENone .

EInternalAttribs

Internal indicator for Attribs() operation. This is mapped to CFileMan::EAttribs .

EInternalCopy

Internal indicator for Copy() operation. This is mapped to CFileMan::ECopy .

EInternalDelete

Internal indicator for Delete() operation. This is mapped to CFileMan::EDelete .

EInternalCopyForMove

Internal indicator for Move() operation on different drives. This is mapped to CFileMan::Move .

EInternalRenameForMove

Internal indicator for Move() operation on the same drive. This is mapped to CFileMan::Rename . Note for compatibility reasons, it is not mapped to CFileMan::Move .

EInternalRename

Internal indicator for Rename() operation. This is mapped to CFileMan::ERename .

EInternalRmDir

Internal indicator for RmDir() operation. This is mapped to CFileMan::ERmDir .

EInternalRenameInvalidEntry

Internal indicator for RenameInvalidEntry() operation. This is mapped to CFileMan::ERenameInvalidEntry .

EInternalCopyFromHandle

Internal indicator for CopyFromHandle() operation. This is mapped to CFileMan::ECopyFromHandle .

Enum TSwitch

Overwriting and recursion switch.

Used in CFileMan functions to set whether operations are applied to the specified directory and all directories below it, or the specified directory only.

Enumerators

EOverWrite = 1

Any files in the destination directory that have the same name as the source files in a rename, move or copy operation, will be overwritten.

ERecurse = 2

Recursive operation.

Member Data Documentation

TInternalAction iAction

TInternalAction iAction [private]

TInt iBytesTransferred

TInt iBytesTransferred [private]

TUint iClearMask

TUint iClearMask [private]

TBool iMovingContents

TBool iMovingContents [private]

TUint iSetMask

TUint iSetMask [private]

RFile iSrcFileHandle

RFile iSrcFileHandle [private]

TTime iTime

TTime iTime [private]

TEntry iTmpEntry

TEntry iTmpEntry [private]

TFileName iTmpName1

TFileName iTmpName1 [private]

TFileName iTmpName2

TFileName iTmpName2 [private]

TParse iTmpParse

TParse iTmpParse [private]

TParse iTrgFile

TParse iTrgFile [private]

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.