Class EikFileUtils

class EikFileUtils;

Description

Provides a set of drive, path and file utility functions.

This class is essentially a thin layer over the BaflUtils class.

Members

Defined in EikFileUtils:

• AbbreviateFileName(const TFileName &,TDes &)Abbreviates a file name.
• AbbreviatePath(TDesC &,const CFont &,TInt)Gets an abbreviated path.
• CheckFolder(const TDesC &)Tests whether the specified folder exists and can be opened.
• CheckWhetherFullNameRefersToFolder(const TDesC &,TBool &)Tests whether a file specification is a valid folder name.
• CopyFile(const TDesC &,const TDesC &,TUint)Copies the specified file.
• DeleteFile(const TDesC &,TUint)Deletes one or more files.
• DiskIsReadOnly(const TDesC &,TBool &)Tests whether the specified drive is read-only.
• DriveAndPathFromFullName(const TDesC &)Parses the specified full path and file name to obtain the drive and path.
• FolderExists(const TDesC &)Tests whether a specified folder exists.
• FolderNameFromFullName(const TDesC &)Gets a folder name from a path and file name.
• IsFirstDriveForSocket(TDriveUnit)Tests whether the specified drive corresponds to the primary partition in a remo...
• IsFolder(const TDesC &,TBool &)Tests whether aFullName is a folder.
• MostSignificantPartOfFullName(const TDesC &,TFileName &)Gets the folder name if the specified item is a valid folder name, otherwise get...
• Parse(const TDesC &)Tests whether a specified file name can be parsed.
• PathExists(const TDesC &)Tests whether a path exists.
• RemoveSystemDirectory(CDir &)Removes the System directory from a list of directory entries.
• RenameFile(const TDesC &,const TDesC &,TUint)Renames one or more files or directories.
• RootFolderPath(const TBuf< 1 >)Gets the root folder for the specified drive.
• SortByTable(CDir &,CBaflFileSortTable *)Sorts files by UID.
• UidTypeMatches(const TUidType &,const TUidType &)Tests whether two UID types match.
• UpdateDiskListL(const RFs &,CDesCArray &,TBool,TDriveNumber)Gets a list of all drives present on the system.
• ValidateFolderNameTypedByUserL(const TDesC &,const TDesC &)Checks if a folder name (without drive or path) is valid and if it is, returns t...

static inline TBool PathExists(const TDesC &aPath);

Description

Tests whether a path exists.

Parameters

const TDesC16 &aPath The path to check.

Return value

TBool ETrue if the path exists, EFalse otherwise.

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

Description

Tests whether aFullName is a folder.

Parameters

const TDesC16 &aFullName The drive and path to test. TBool &aIsFolder On return, indicates whether aFullName is a folder.

Return value

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

static inline TBool FolderExists(const TDesC &aFolderName);

Description

Tests whether a specified folder exists.

This returns a boolean value indicating whether the folder exists: see also EikFileUtils::CheckFolder(const TDesC &) which returns an error code instead.

Parameters

const TDesC16 &aFolderName The folder's path.

Return value

TBool ETrue if the folder exists, EFalse if not.

static inline TFileName FolderNameFromFullName(const TDesC &aFullName);

Description

Gets a folder name from a path and file name.

Parameters

const TDesC16 &aFullName The full path and file name from which the folder will be obtained.

Return value

TBuf Folder name

static inline TFileName DriveAndPathFromFullName(const TDesC &aFullName);

Description

Parses the specified full path and file name to obtain the drive and path.

Parameters

const TDesC16 &aFullName The full path and file name from which the drive and path will be obtained.

Return value

TBuf The drive and path.

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

Description

Gets the root folder for the specified drive.

Parameters

const TBuf< 1 > aDriveLetter The drive letter, C for example.

Return value

TBuf The root folder for the drive, C:\ for example.

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

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 the case, then the left-most characters of aOriginalFileName are copied to aAbbreviatedFileName, up to aAbbreviatedFileName's maximum length-1 and aAbbreviatedFileName's first character is set to be an ellipsis.

For example, if c:\home\letters\abcdef is the original file name and aAbbreviatedFileName allows only 7 characters, the abbreviated file name will be ...abcdef. This can be used to display a file or folder name in an error or progress dialog.

Parameters

const TBuf &aOriginalFileName Original file name. TDes16 &aAbbreviatedFileName On return, the abbreviated file name.

IMPORT_C static TFileName AbbreviatePath(TDesC &aPathName, const CFont &aFont, TInt aMaxWidthInPixels);

Description

Gets an abbreviated path.

Calculates the space that is available to display aPathName according to the font size and the display width. If there is sufficient space then aPathName is returned. If there is not sufficient space, aPathName is abbreviated to fit the available space, prefixed with an ellipsis and the abbreviation is returned.

Parameters

TDesC16 &aPathName The full path name. const CFont &aFont The font used to display the path. TInt aMaxWidthInPixels The available display width in pixels.

Return value

TBuf The abbreviated path.

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

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 ETrue if the UIDs match, EFalse if not.

static inline TInt Parse(const TDesC &aName);

Description

Tests whether a specified file name can be parsed.

Parameters

const TDesC16 &aName The file name to parse.

Return value

TInt KErrNone if the filename can be parsed, otherwise one of the system-wide error codes.

IMPORT_C static TFileName ValidateFolderNameTypedByUserL(const TDesC &aFolderNameTypedByUser, const TDesC &aCurrentPath);

Description

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

Leaves with an appropriate info message if the folder name is invalid.

Parameters

const TDesC16 &aFolderNameTypedByUser Folder name to check. const TDesC16 &aCurrentPath Path to which to add the folder.

Return value

TBuf aFolderNameTypedByUser appended to aCurrentPath.

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

Description

Copies the specified file.

Notes:

• files can be copied across drives

• open files can be copied only if they have been opened using the EFileShareReadersOnly file share mode

• the source file's attributes are preserved in the target file

Parameters

const TDesC16 &aSourceFullName Path indicating the file(s) to be copied. Any path components which are not specified here will be taken from the session path. const TDesC16 &aTargetFullName Path indicating the directory into which the file(s) are to be copied. TUint aSwitch Optional switch to allow overwriting files with the same name in the target directory, or recursion. By default, this function operates with overwriting and non-recursively. Switch options are defined using the enum TSwitch. If recursive operation is set, any intermediate directories are created. If no overwriting is set, any files with the same name are not overwritten, and an error is returned for that file.

Return value

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

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

Description

Renames one or more files or directories.

This can also be used to move files by specifying different destination and source directories, but note that the destination and source directories must be on the same drive.

If moving files, you can set aSwitch so that any files with the same name that exist in the target directory are overwritten. If aSwitch is set for no overwriting, any files with the same name are not overwritten, and an error (KErrAlreadyExists) is returned for that file.

This function can only operate non-recursively, so that only the matching files located in the single directory specified by aOldFullName may be renamed.

Read-only, system and hidden files may be renamed or moved, and the source file's attributes are preserved in the target file, but attempting to rename or move an open file will return an error for that file.

Parameters

const TDesC16 &aOldFullName Path specifying the file or directory to be renamed. const TDesC16 &aNewFullName Path specifying the new name for the file or directory. Any directories specified in this path which do not exist will be created. TUint aSwitch Optional, sets whether files are overwritten on the target.

Return value

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

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

Description

Deletes one or more files.

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

Attempting to delete read-only or open files returns an error.

Parameters

const TDesC16 &aSourceFullName Path indicating the file(s) to be deleted. This can either be a full path, or a path relative to the session path. Use wildcards to specify more than one file. TUint aSwitch Determines whether this function operates recursively. By default, this function operates non-recursively.

Return value

TInt KErrNone if aSourceFullName is successfully deleted, otherwise another of the system-wide error codes.

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

Description

Tests whether a file specification is a valid folder name.

Parameters

const TDesC16 &aFullName The 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 inline TInt MostSignificantPartOfFullName(const TDesC &aFullName, TFileName &aMostSignificantPart);

Description

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

Parameters

const TDesC16 &aFullName Item to parse. TBuf &aMostSignificantPart On return, the folder or file name.

Return value

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

static inline TInt CheckFolder(const TDesC &aFolderName);

Description

Tests whether the specified folder exists and can be opened.

This returns an error code if the folder does not exist: see also EikFileUtils::FolderExists(const TDesC &) which returns a boolean value.

Parameters

const TDesC16 &aFolderName The folder's name and path.

Return value

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

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

Description

Tests whether the specified drive is read-only.

Parameters

const TDesC16 &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 inline void UpdateDiskListL(const RFs &aFs, CDesCArray &aArray, TBool aIncludeRom, TDriveNumber aDriveNumber);

Description

Gets 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. CDesC16Array &aArray On return, contains the drive letters that correspond to the available drives. The drive letters are uppercase and are in alphabetical order. TBool aIncludeRom ETrue if the ROM is included as a drive, EFalse otherwise. TDriveNumber aDriveNumber The drive to force into the list, e.g. the drive in the default path.

static inline void RemoveSystemDirectory(CDir &aDir);

Description

Removes the System directory from a list of directory entries.

Parameters

CDir &aDir Array of directory entries.

static inline TBool IsFirstDriveForSocket(TDriveUnit aDriveUnit);

Description

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

Note that 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 Symbian OS.

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.

static inline 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 another of the system-wide error codes.