CFileMan Class Reference

Copies one or more files.

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

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:

See also: 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.

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.

See also: 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.

Gets the action which CFileMan is currently carrying out.

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

See also: 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.

See also: KNullDesC

Deletes one or more files.

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

See also: KNullDesC

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.

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.

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.

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.

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.

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:

See also: CFileBase::GetLastError()

Moves one or more files.

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

Constructs and allocates memory for a new CFileMan object.

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

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 "\*.*";

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);

CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC"), _L("C:\\TRG\"));

CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC"), _L("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"));

CFileMan* fm(CFileMan::NewL(iFs)); // Where iFs is an RFs handle
...
fm->Rename(_L("C:\\SRC\\*.567"), _L("C:\\TRG\\*.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;

C:\SRC\ITEM01
C:\SRC\ITEM02
C:\TRG\ITEM01\
C:\TRG\ITEM02\

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.

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;

C:\SRC\FILE.TXT
C:\TRG\
C:\TRG\SRC\

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

See also: 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.

Renames one or more files.

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