1.1 --- a/epoc32/include/eikfutil.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/eikfutil.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,315 @@
1.4 -eikfutil.h
1.5 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +#ifndef __EIKFUTIL_H__
1.21 +#define __EIKFUTIL_H__
1.22 +
1.23 +#include <e32std.h>
1.24 +#include <f32file.h>
1.25 +#include <badesca.h>
1.26 +#include <bautils.h>
1.27 +#include <eikenv.h>
1.28 +
1.29 +class CFont;
1.30 +class CBaflFileSortTable;
1.31 +class TResourceReader;
1.32 +
1.33 +
1.34 +/** Provides a set of drive, path and file utility functions.
1.35 +
1.36 +This class is essentially a thin layer over the BaflUtils class.
1.37 +
1.38 +@publishedAll
1.39 +@released */
1.40 +NONSHARABLE_CLASS(EikFileUtils)
1.41 + {
1.42 +public:
1.43 + inline static TBool PathExists(const TDesC& aPath);
1.44 + inline static TInt IsFolder(const TDesC& aFullName, TBool& aIsFolder);
1.45 + inline static TBool FolderExists(const TDesC& aFolderName);
1.46 + inline static TFileName FolderNameFromFullName(const TDesC& aFullName);
1.47 + inline static TFileName DriveAndPathFromFullName(const TDesC& aFullName);
1.48 + inline static TFileName RootFolderPath(const TBuf<1> aDriveLetter);
1.49 + inline static void AbbreviateFileName(const TFileName& aOriginalFileName, TDes& aAbbreviatedFileName);
1.50 + IMPORT_C static TFileName AbbreviatePath(TDesC& aPathName, const CFont& aFont, TInt aMaxWidthInPixels);
1.51 + inline static TBool UidTypeMatches(const TUidType& aFileUid, const TUidType& aMatchUid);
1.52 + inline static TInt Parse(const TDesC& aName);
1.53 + IMPORT_C static TFileName ValidateFolderNameTypedByUserL(const TDesC& aFolderNameTypedByUser, const TDesC& aCurrentPath);
1.54 + inline static TInt CopyFile(const TDesC& aSourceFullName, const TDesC& aTargetFullName, TUint aSwitch = CFileMan::EOverWrite);
1.55 + inline static TInt RenameFile(const TDesC& aOldFullName, const TDesC& aNewFullName, TUint aSwitch = CFileMan::EOverWrite);
1.56 + inline static TInt DeleteFile(const TDesC& aSourceFullName, TUint aSwitch=0);
1.57 + inline static TInt CheckWhetherFullNameRefersToFolder(const TDesC& aFullName, TBool& aIsFolder);
1.58 + inline static TInt MostSignificantPartOfFullName(const TDesC& aFullName, TFileName& aMostSignificantPart);
1.59 + inline static TInt CheckFolder(const TDesC& aFolderName);
1.60 + inline static TInt DiskIsReadOnly(const TDesC& aFullName, TBool& aIsReadOnly);
1.61 + inline static void UpdateDiskListL(const RFs& aFs,CDesCArray& aArray,TBool aIncludeRom,TDriveNumber aDriveNumber);
1.62 + inline static void RemoveSystemDirectory(CDir& aDir);
1.63 + inline static TBool IsFirstDriveForSocket(TDriveUnit aDriveUnit);
1.64 + inline static TInt SortByTable(CDir& aDir,CBaflFileSortTable* aTable);
1.65 +private:
1.66 + EikFileUtils();
1.67 + };
1.68 +
1.69 +
1.70 +/** Tests whether a path exists.
1.71 +
1.72 +@param aPath The path to check.
1.73 +@return ETrue if the path exists, EFalse otherwise. */
1.74 +inline TBool EikFileUtils::PathExists(const TDesC& aPath)
1.75 + { return BaflUtils::PathExists(CEikonEnv::Static()->FsSession(),aPath); }
1.76 +
1.77 +/** Tests whether aFullName is a folder.
1.78 +
1.79 +@param aFullName The drive and path to test.
1.80 +@param aIsFolder On return, indicates whether aFullName is a folder.
1.81 +@return KErrNone if successful otherwise another of the system-wide error codes. */
1.82 +inline TInt EikFileUtils::IsFolder(const TDesC& aFullName, TBool& aIsFolder)
1.83 + { return BaflUtils::IsFolder(CEikonEnv::Static()->FsSession(), aFullName,aIsFolder); }
1.84 +
1.85 +/** Tests whether a specified folder exists.
1.86 +
1.87 +This returns a boolean value indicating whether the folder exists: see also
1.88 +CheckFolder() which returns an error code instead.
1.89 +
1.90 +@param aFolderName The folder's path.
1.91 +@return ETrue if the folder exists, EFalse if not. */
1.92 +inline TBool EikFileUtils::FolderExists(const TDesC& aFolderName)
1.93 + { return BaflUtils::FolderExists(CEikonEnv::Static()->FsSession(), aFolderName); }
1.94 +
1.95 +/** Gets a folder name from a path and file name.
1.96 +
1.97 +@param aFullName The full path and file name from which the folder will be
1.98 +obtained.
1.99 +@return Folder name */
1.100 +inline TFileName EikFileUtils::FolderNameFromFullName(const TDesC& aFullName)
1.101 + { return BaflUtils::FolderNameFromFullName(aFullName); }
1.102 +
1.103 +/** Parses the specified full path and file name to obtain the drive and path.
1.104 +
1.105 +@param aFullName The full path and file name from which the drive and path
1.106 +will be obtained.
1.107 +@return The drive and path. */
1.108 +inline TFileName EikFileUtils::DriveAndPathFromFullName(const TDesC& aFullName)
1.109 + { return BaflUtils::DriveAndPathFromFullName(aFullName); }
1.110 +
1.111 +/** Gets the root folder for the specified drive.
1.112 +
1.113 +@param aDriveLetter The drive letter, C for example.
1.114 +@return The root folder for the drive, C:\ for example. */
1.115 +inline TFileName EikFileUtils::RootFolderPath(const TBuf<1> aDriveLetter)
1.116 + { return BaflUtils::RootFolderPath(aDriveLetter); }
1.117 +
1.118 +/** Abbreviates a file name.
1.119 +
1.120 +If aOriginalFileName is less than the maximum length of aAbbreviatedFileName,
1.121 +then the name is simply copied to aAbbreviatedFileName.
1.122 +
1.123 +If this is not the case, then the left-most characters of aOriginalFileName are
1.124 +copied to aAbbreviatedFileName, up to aAbbreviatedFileName's maximum length-1 and
1.125 +aAbbreviatedFileName's first character is set to be an ellipsis.
1.126 +
1.127 +For example, if c:\\home\\letters\\abcdef is the original file name and aAbbreviatedFileName
1.128 +allows only 7 characters, the abbreviated file name will be ...abcdef.
1.129 +This can be used to display a file or folder name in an error or progress
1.130 +dialog.
1.131 +
1.132 +@param aOriginalFileName Original file name.
1.133 +@param aAbbreviatedFileName On return, the abbreviated file name. */
1.134 +inline void EikFileUtils::AbbreviateFileName(const TFileName& aOriginalFileName, TDes& aAbbreviatedFileName)
1.135 + { BaflUtils::AbbreviateFileName(aOriginalFileName,aAbbreviatedFileName); }
1.136 +
1.137 +/** Tests whether two UID types match.
1.138 +
1.139 +A match is made if each UID in aMatchUid is either identical to the corresponding
1.140 +one in aFileUid, or is KNullUid.
1.141 +
1.142 +@param aFileUid The UID type to match.
1.143 +@param aMatchUid The UID type to match against.
1.144 +@return ETrue if the UIDs match, EFalse if not. */
1.145 +inline TBool EikFileUtils::UidTypeMatches(const TUidType& aFileUid, const TUidType& aMatchUid)
1.146 + { return BaflUtils::UidTypeMatches(aFileUid,aMatchUid); }
1.147 +
1.148 +/** Tests whether a specified file name can be parsed.
1.149 +
1.150 +@param aName The file name to parse.
1.151 +@return KErrNone if the filename can be parsed, otherwise one
1.152 +of the system-wide error codes.
1.153 +@see TParse */
1.154 +inline TInt EikFileUtils::Parse(const TDesC& aName)
1.155 + { return BaflUtils::Parse(aName); }
1.156 +
1.157 +/** Copies the specified file.
1.158 +
1.159 +Notes:
1.160 +
1.161 +- files can be copied across drives
1.162 +
1.163 +- open files can be copied only if they have been opened using the EFileShareReadersOnly
1.164 +file share mode
1.165 +
1.166 +- the source file's attributes are preserved in the target file
1.167 +
1.168 +@param aSourceFullName Path indicating the file(s) to be copied. Any path
1.169 +components which are not specified here will be taken from the session path.
1.170 +@param aTargetFullName Path indicating the directory into which the file(s)
1.171 +are to be copied.
1.172 +@param aSwitch Optional switch to allow overwriting files with the same name
1.173 +in the target directory, or recursion. By default, this function operates with
1.174 +overwriting and non-recursively. Switch options are defined using the enum TSwitch.
1.175 +If recursive operation is set, any intermediate directories are created. If no overwriting
1.176 +is set, any files with the same name are not overwritten, and an error is returned
1.177 +for that file.
1.178 +@return KErrNone if the copy is successful, otherwise another of the system-wide
1.179 +error codes. */
1.180 +inline TInt EikFileUtils::CopyFile(const TDesC& aSourceFullName, const TDesC& aTargetFullName, TUint aSwitch)
1.181 + { return BaflUtils::CopyFile(CEikonEnv::Static()->FsSession(),aSourceFullName,aTargetFullName,aSwitch); }
1.182 +
1.183 +/** Renames one or more files or directories.
1.184 +
1.185 +This can also be used to move files by specifying different destination and
1.186 +source directories, but note that the destination and source directories must be
1.187 +on the same drive.
1.188 +
1.189 +If moving files, you can set aSwitch so that any files with the same name
1.190 +that exist in the target directory are overwritten. If aSwitch is set for
1.191 +no overwriting, any files with the same name are not overwritten, and an error
1.192 +(KErrAlreadyExists) is returned for that file.
1.193 +
1.194 +This function can only operate non-recursively, so that only the matching
1.195 +files located in the single directory specified by aOldFullName may be renamed.
1.196 +
1.197 +Read-only, system and hidden files may be renamed or moved, and the source
1.198 +file's attributes are preserved in the target file, but attempting to rename
1.199 +or move an open file will return an error for that file.
1.200 +
1.201 +@param aOldFullName Path specifying the file or directory to be renamed.
1.202 +@param aNewFullName Path specifying the new name for the file or directory.
1.203 +Any directories specified in this path which do not exist will be created.
1.204 +@param aSwitch Optional, sets whether files are overwritten on the target.
1.205 +@return KErrNone if successful otherwise another of the system-wide error codes. */
1.206 +inline TInt EikFileUtils::RenameFile(const TDesC& aOldFullName, const TDesC& aNewFullName, TUint aSwitch)
1.207 + { return BaflUtils::RenameFile(CEikonEnv::Static()->FsSession(),aOldFullName,aNewFullName,aSwitch); }
1.208 +
1.209 +/** Deletes one or more files.
1.210 +
1.211 +This function may operate recursively or non-recursively. When operating non-recursively,
1.212 +only the matching files located in the directory specified in aSourceFullName
1.213 +are affected. When operating recursively, all matching files in the directory
1.214 +hierarchy below the directory specified in aSourceFullName are deleted.
1.215 +
1.216 +Attempting to delete read-only or open files returns an error.
1.217 +
1.218 +@param aSourceFullName Path indicating the file(s) to be deleted. This can
1.219 +either be a full path, or a path relative to the session path. Use wildcards
1.220 +to specify more than one file.
1.221 +@param aSwitch Determines whether this function operates recursively. By default,
1.222 +this function operates non-recursively.
1.223 +@return KErrNone if aSourceFullName is successfully deleted, otherwise another
1.224 +of the system-wide error codes. */
1.225 +inline TInt EikFileUtils::DeleteFile(const TDesC& aSourceFullName, TUint aSwitch)
1.226 + { return BaflUtils::DeleteFile(CEikonEnv::Static()->FsSession(), aSourceFullName,aSwitch); }
1.227 +
1.228 +/** Tests whether a file specification is a valid folder name.
1.229 +
1.230 +@param aFullName The string to check.
1.231 +@param aIsFolder True if aFullName is a valid folder name, otherwise false.
1.232 +@return KErrNone if successful, otherwise another of the system-wide error codes
1.233 +(probably because aFullName cannot be parsed). */
1.234 +inline TInt EikFileUtils::CheckWhetherFullNameRefersToFolder(const TDesC& aFullName, TBool& aIsFolder)
1.235 + { return BaflUtils::CheckWhetherFullNameRefersToFolder(aFullName,aIsFolder); }
1.236 +
1.237 +/** Gets the folder name if the specified item is a valid folder name, otherwise gets the file name.
1.238 +
1.239 +@param aFullName Item to parse.
1.240 +@param aMostSignificantPart On return, the folder or file name.
1.241 +@return KErrNone if successful otherwise another of the system-wide error codes. */
1.242 +inline TInt EikFileUtils::MostSignificantPartOfFullName(const TDesC& aFullName, TFileName& aMostSignificantPart)
1.243 + { return BaflUtils::MostSignificantPartOfFullName(aFullName,aMostSignificantPart); }
1.244 +
1.245 +/** Tests whether the specified folder exists and can be opened.
1.246 +
1.247 +This returns an error code if the folder does not exist: see also FolderExists()
1.248 +which returns a boolean value.
1.249 +
1.250 +@param aFolderName The folder's name and path.
1.251 +@return KErrNone if aFolderName exists, otherwise another of the system-wide
1.252 +error codes. */
1.253 +inline TInt EikFileUtils::CheckFolder(const TDesC& aFolderName)
1.254 + { return BaflUtils::CheckFolder(CEikonEnv::Static()->FsSession(),aFolderName); }
1.255 +
1.256 +/** Tests whether the specified drive is read-only.
1.257 +
1.258 +@param aFullName File name, including drive.
1.259 +@param aIsReadOnly On return, true if the drive is read-only, otherwise false.
1.260 +@return KErrNone if successful otherwise another of the system-wide error codes. */
1.261 +inline TInt EikFileUtils::DiskIsReadOnly(const TDesC& aFullName, TBool& aIsReadOnly)
1.262 + { return BaflUtils::DiskIsReadOnly(CEikonEnv::Static()->FsSession(),aFullName,aIsReadOnly); }
1.263 +
1.264 +/** Gets a list of all drives present on the system.
1.265 +
1.266 +The file server is interrogated for a list of the drive letters for all available
1.267 +drives. The drive letter that corresponds to aDriveNumber is added to the list
1.268 +regardless of whether it is present, or is corrupt. Also, the C: drive and the
1.269 +primary partitions on removable media slots are forced onto the list, even if
1.270 +corrupt or not present.
1.271 +
1.272 +@param aFs A connected session with the file server.
1.273 +@param aArray On return, contains the drive letters that correspond to the available
1.274 +drives. The drive letters are uppercase and are in alphabetical order.
1.275 +@param aIncludeRom ETrue if the ROM is included as a drive, EFalse otherwise.
1.276 +@param aDriveNumber The drive to force into the list, e.g. the drive in the default
1.277 +path. */
1.278 +inline void EikFileUtils::UpdateDiskListL(const RFs& aFs,CDesCArray& aArray,TBool aIncludeRom,TDriveNumber aDriveNumber)
1.279 + { BaflUtils::UpdateDiskListL(aFs,aArray,aIncludeRom,aDriveNumber); }
1.280 +
1.281 +/** Removes the System directory from a list of directory entries.
1.282 +
1.283 +@param aDir Array of directory entries. */
1.284 +inline void EikFileUtils::RemoveSystemDirectory(CDir& aDir)
1.285 + { BaflUtils::RemoveSystemDirectory(aDir); }
1.286 +
1.287 +/** Tests whether the specified drive corresponds to the primary partition
1.288 +in a removable media slot.
1.289 +
1.290 +Note that the function assumes that the D: drive corresponds to the primary
1.291 +partition on socket 0, and that the E: drive corresponds to the primary
1.292 +partition on socket 1 (a socket is a slot for removable media). This mapping
1.293 +may not always be the case because it is set up in the variant layer of Symbian
1.294 +OS.
1.295 +
1.296 +@param aDriveUnit The drive to check.
1.297 +@return True if the drive is the primary partition in a removable media
1.298 +slot. True is also returned if the drive is C:. False is returned otherwise. */
1.299 +inline TBool EikFileUtils::IsFirstDriveForSocket(TDriveUnit aDriveUnit)
1.300 + { return BaflUtils::IsFirstDriveForSocket(aDriveUnit); }
1.301 +
1.302 +/** Sorts files by UID.
1.303 +
1.304 +The caller supplies a table which specifies the order in which files are to be sorted.
1.305 +The files whose UID3 is the first UID in the table appear first. The files whose UID3
1.306 +is the UID specified second appear next, and so on. Files whose UID3 is not specified
1.307 +in the table, and directories, appear at the end of the list, with directories preceding
1.308 +the files, and with files sorted in ascending order of UID3.
1.309 +
1.310 +This function is used for customising how lists of application files are sorted.
1.311 +
1.312 +@param aDir The array of files and directories to sort.
1.313 +@param aTable A sort order table containing the UIDs to use in the sort.
1.314 +@return KErrNone if successful otherwise another of the system-wide error codes. */
1.315 +inline TInt EikFileUtils::SortByTable(CDir& aDir,CBaflFileSortTable* aTable)
1.316 + { return BaflUtils::SortByTable(aDir,aTable); }
1.317 +
1.318 +
1.319 +#endif // __EIKFUTIL_H__