Class BaflUtils

BaflUtils

Support

Supported from 5.0

Description

Provides simple-to-use file system utilities.

The functions listed in "Copying, renaming, and deleting files" create and use a CFileMan object. They are useful for one-off calls, but for repeated use it is more efficient to use CFileMan directly.

Note that there is a very similiar group of functions available in EikFileUtils, which may be easier to use in GUI applications, as they do not require a file server session to be passed.

Defined in BaflUtils:
AbbreviateFileName(), CheckFolder(), CheckWhetherFullNameRefersToFolder(), CopyFile(), CopyWithTruncation(), DeleteFile(), DiskIsReadOnly(), DriveAndPathFromFullName(), EnsurePathExistsL(), ExtractAppNameFromFullName(), FileExists(), FolderExists(), FolderNameFromFullName(), GetSystemDrive(), IsFirstDriveForSocket(), IsFolder(), MostSignificantPartOfFullName(), NearestLanguageFile(), Parse(), PathExists(), RemoveSystemDirectory(), RenameFile(), RootFolderPath(), SortByTable(), UidTypeMatches(), UpdateDiskListL(), ValidateFolderNameTypedByUserL()

See also:

• CFileMan
• EikFileUtils

static void EnsurePathExistsL(RFs& aFs,const TDesC& aFileName);

Description

Makes one or more directories, if they do not already exist.

Any valid path component in the specified path that does not already exist is created as a directory.

Parameters

RFs& aFs File server session const TDesC& aFileName Path to ensure exists

Leave codes

KErrAlreadyExists The path already exists

See also:

• RFs::MkDirAll()

static TBool FileExists(const RFs& aFs,const TDesC& aFileName);

Description

Checks if the specified file exists.

Parameters

RFs& aFs File server session const TDesC& aFileName File to check

Return value

TBool True if the file exists, otherwise false

static TBool FolderExists(RFs& aFs, const TDesC& aFolderName);

Support

Supported from 5.1

Description

Tests whether a folder exists.

The folder is specified in a path. The path can omit the drive letter, in which case the drive letter is taken from the session path.

If the path is badly formed, for instance if it contains illegal characters, or any directory name consists of a single or double dot, or any directory name includes wildcard characters, the function returns false.

A filename may be specified in the path, and is ignored, but note that if a filename is included in the path, its name must not contain any illegal characters — this is considered a badly formed path and causes the function to return false. If no filename is specified, the path should end in a backslash.

Parameters

RFs& aFs A connected session with the file server. const TDesC& aFolderName A path specifying the folder to test for.

Return value

TBool True if the folder specified in aFolderName exists, false if not. False is also returned if the specified path is badly formed.

static TBool PathExists(RFs& aFs,const TDesC& aFileName);

Support

Supported from 5.1

Description

Tests whether a path exists.

The path should contain a drive letter and a directory, or false is returned. False is also returned if it contains a filename or filename extension.

If the path is badly formed, for instance if it contains illegal characters, or any directory name consists of a single or double dot, or any directory name includes wildcard characters, the function returns false.

Parameters

RFs& aFs A connected session with the file server. const TDesC& aFileName The path to test for. It should end in a backslash.

Return value

TBool True if the path exists, false if not. False is also returned if the specified path is badly formed.

static TInt CopyFile(RFs& aFs, const TDesC& aSourceFullName, const TDesC& aTargetFullName, TUint aSwitch = CFileMan::EOverWrite);

Support

Supported from 5.1

Description

Copies one or more files.

For more details, see CFileMan::Copy().

Parameters

RFs& aFs File server session const TDesC& aSourceFullName Path indicating the file(s) to be copied. Any path components that are not specified here will be taken from the session path. const TDesC& aTargetFullName Path indicating the directory into which the file(s) are to be copied TUint aSwitch = CFileMan::EOverWrite Set this to zero for no overwriting and no recursion; CFileMan::EOverWrite to overwrite files with the same name; or CFileMan::ERecurse for recursion.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• CFileMan::Copy()

static TInt DeleteFile(RFs& aFs, const TDesC& aSourceFullName, TUint aSwitch = 0);

Support

Supported from 5.1

Description

Deletes one or more files.

For more details, see CFileMan::Delete().

Parameters

RFs& aFs File server session const TDesC& aSourceFullName 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. TUint aSwitch = 0 Specify CFileMan::ERecurse for recursion, zero for no recursion.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• CFileMan::Delete()

static TInt RenameFile(RFs& aFs, const TDesC& aOldFullName, const TDesC& aNewFullName, TUint aSwitch = CFileMan::EOverWrite);

Support

Supported from 5.1

Description

Renames or moves one or more files or directories.

It can be used to move one or more files by specifying different destination and source directories.

For more details, see CFileMan::Rename().

Parameters

RFs& aFs File server session const TDesC& aOldFullName Path specifying the file(s) to be renamed. const TDesC& aNewFullName 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. TUint aSwitch = CFileMan::EOverWrite Specify zero for no overwriting, or CFileMan::EOverWrite to overwrite files with the same name. This function cannot operate recursively.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• CFileMan::Rename()

static void AbbreviateFileName(const TFileName& aOriginalFileName, TDes& aAbbreviatedFileName);

Support

Supported from 5.1

Description

Abbreviates a file name.

If aOriginalFileName is less than the maximum length of aAbbreviatedFileName, then the name is simply copied to aAbbreviatedFileName.

If this is not so, then the left-most characters of aOriginalFileName are copied to aAbbreviatedFileName, up to aAbbreviatedFileName's maximum length-1. aAbbreviatedFileName's first character is set to be an ellipsis.

Parameters

const TFileName& aOriginalFileName Original file name TDes& aAbbreviatedFileName On return, abbreviated file name

static TInt CheckWhetherFullNameRefersToFolder(const TDesC& aFullName, TBool& aIsFolder);

Support

Supported from 5.1

Description

Checks if a string is a valid folder name.

Parameters

const TDesC& aFullName String to check TBool& aIsFolder True if aFullName is a valid folder name, otherwise false

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes (probably because aFullName cannot be parsed).

static void CopyWithTruncation(TDes& aDest,const TDesC& aSrc,TChar aTruncationSymbol=KBaflCharTruncation);

Description

Copies a descriptor, abbreviating it to fit the destination descriptor.

If aSrc is less than the maximum length of aDest, then the string is simply copied to aDest.

If this is not so, then the left-most characters of aSrc are copied to aDest, up to aDest's maximum length-1. aDest's final character is set to be aTruncationSymbol.

Parameters

TDes& aDest On return, the truncated string const TDesC& aSrc The string to truncate TChar aTruncationSymbol=KBaflCharTruncation The truncation character to add

static TFileName DriveAndPathFromFullName(const TDesC& aFullName);

Support

Supported from 5.1

Description

Gets the drive letter and path from a file name.

This is in the form: drive-letter:\path\. The drive letter is folded using class TCharF.

Parameters

const TDesC& aFullName File name

Return value

TFileName The drive and path

static TFileName FolderNameFromFullName(const TDesC& aFullName);

Support

Supported from 5.1

Description

Gets the folder name from a path.

For example, if the path is "c:\documents\word\mydoc1", then "word" is returned.

Parameters

const TDesC& aFullName A path.

Return value

TFileName The folder name.

static TInt MostSignificantPartOfFullName(const TDesC& aFullName, TFileName& aMostSignificantPart);

Support

Supported from 5.1

Description

Gets the folder name if the specified item is a valid folder name, otherwise gets the file name.

Parameters

const TDesC& aFullName Item to parse TFileName& aMostSignificantPart Folder or file name

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes

static TInt Parse(const TDesC& aName);

Support

Supported from 5.1

Description

Checks if a specified file name can be parsed.

Parameters

const TDesC& aName Name to parse

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes

static TFileName RootFolderPath(const TBuf<1> aDriveLetter);

Support

Supported from 5.1

Description

Gets the root folder for the specified drive.

This is simply the drive letter plus ":\".

Parameters

const TBuf<1> aDriveLetter Drive letter

Return value

TFileName Root folder

static TInt ValidateFolderNameTypedByUserL(const RFs& aFs, const TDesC& aFolderNameTypedByUser, const TDesC& aCurrentPath, TFileName& aNewFolderFullName);

Support

Supported from 5.1

Description

Checks if a folder name (without drive or path) is valid and returns the full name of the folder.

Parameters

const RFs& aFs File server session const TDesC& aFolderNameTypedByUser Folder name to check const TDesC& aCurrentPath Path to which to add the folder TFileName& aNewFolderFullName aFolderNameTypedByUser appended to aCurrentPath

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes

static void RemoveSystemDirectory(CDir& aDir);

Support

Supported from 5.1

Description

Removes "System" from a list of directory entries.

Parameters

CDir& aDir Array of directory entries

static TInt CheckFolder(RFs& aFs, const TDesC& aFolderName);

Support

Supported from 5.1

Description

Checks that the specified folder can be opened.

Parameters

RFs& aFs File server session const TDesC& aFolderName Folder to check

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes

static TInt DiskIsReadOnly(RFs& aFs, const TDesC& aFullName, TBool& aIsReadOnly);

Support

Supported from 5.1

Description

Checks if the specified drive is read-only.

Parameters

RFs& aFs File server session const TDesC& aFullName File name, including drive TBool& aIsReadOnly On return, true if the drive is read-only, otherwise false

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes

static TPtrC ExtractAppNameFromFullName(const TFullName& aName);

Description

Gets the application name from a full thread name.

Parameters

const TFullName& aName Thread name

Return value

TPtrC Application name

See also:

• RThread

static TBool IsFirstDriveForSocket(TDriveUnit aDriveUnit);

Support

Supported from 5.1

Description

Tests whether the specified drive corresponds to the primary partition in a removable media slot.

Parameters

TDriveUnit aDriveUnit The drive to check.

Return value

TBool True if the drive is the primary partition in a removable media slot. True is also returned if the drive is C:. False is returned otherwise.

Notes:

• The function assumes that the D: drive corresponds to the primary partition on socket 0, and that the E: drive corresponds to the primary partition on socket 1 (a socket is a slot for removable media). This mapping may not always be the case because it is set up in the variant layer of the Symbian OS.

static TInt IsFolder(const RFs& aFs, const TDesC& aFullName, TBool& aIsFolder);

Support

Supported from 5.1

Description

Checks if the specified item is a folder.

Parameters

const RFs& aFs File server session const TDesC& aFullName Name to check TBool& aIsFolder True if aFullName is a folder, otherwise false

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes

static void NearestLanguageFile(const RFs& aFs,TFileName& aName);

Description

Searches for the file with the correct language extension for the language of the current locale, or failing this, the best matching file.

Symbian defines two-digit language values that identify natural languages. These values are enumerated by the TLanguage enum. It is suggested that files that have language-specific variants, such as resource files, have extensions in which the last two digits are the language code. For example, somefile.r01 and somefile.r02 would be the English and French versions of the resource file somefile. In a system set to the English locale, this function would return somefile.r01; in a French locale, somefile.r02.

For each language, the search is conducted across all the drives available on the device. The first drive searched is the system drive (as returned by BaflUtils::GetSystemDrive()), followed by the ROM (z: drive), then all the other drives available on the device.

Parameters

const RFs& aFs File server session. TFileName& aName File name as it would be without a language-specific extension. On return, this is changed to the language-specific version. If no such file is found, the name is unchanged.

See also:

• TLanguage

static TBool UidTypeMatches(const TUidType& aFileUid, const TUidType& aMatchUid);

Support

Supported from 5.1

Description

Tests whether two UID types match.

A match is made if each UID in aMatchUid is either identical to the corresponding one in aFileUid, or is KNullUid.

Parameters

const TUidType& aFileUid The UID type to match const TUidType& aMatchUid The UID type to match against

Return value

TBool True if the UIDs match, otherwise false

static TInt GetSystemDrive(TDriveNumber& aDriveNumber);

Support

Supported from 6.1

Description

Gets the value of the system drive, if one has been set.

The system drive can be set to one of the built-in read/write drives. Which drive is used is hardware-dependent. On some hardware, there may not be a system drive. The system drive is used as the drive on which localisable files are searched for.

Parameters

TDriveNumber& aDriveNumber On return, contains the drive number of the system drive.

Return value

TInt KErrNone if successful, otherwise one of the system error codes. KErrNotFound is returned if no valid system drive is currently set. If anything other than KErrNone is returned, the value of aDriveNumber is undefined.

static void UpdateDiskListL(const RFs& aFs,CDesCArray& aArray,TBool aIncludeRom,TDriveNumber aDriveNumber);

Description

Retrieves a list of all drives present on the system.

The file server is interrogated for a list of the drive letters for all available drives. The drive letter that corresponds to aDriveNumber is added to the list regardless of whether it is present, or is corrupt. Also, the C: drive and the primary partitions on removable media slots are forced onto the list, even if corrupt or not present.

Parameters

const RFs& aFs A connected session with the file server. const CDesCArray& aArray On return, contains the drive letters that correspond to the available drives. The drive letters are uppercase and are in alphabetical order. const TBool aIncludeRom Specify ETrue if the ROM drive should be included in the list, EFalse if not. const TDriveNumber aDriveNumber The drive to force into the list, e.g. the drive in the default path.

static TInt SortByTable(CDir& aDir,CBaflFileSortTable* aTable);

Description

Sorts files by UID.

The caller supplies a table which specifies the order in which files are to be sorted. The files whose UID3 is the first UID in the table appear first. The files whose UID3 is the UID specified second appear next, and so on. Files whose UID3 is not specified in the table, and directories, appear at the end of the list, with directories preceding the files, and with files sorted in ascending order of UID3.

This function is used for customising how lists of application files are sorted.

Parameters

CDir& aDir The array of files and directories to sort. CBaflFileSortTable* aTable A sort order table containing the UIDs to use in the sort.

Return value

TInt KErrNone if successful, otherwise one of the standard error codes.