Class TFindFile

TFindFile

Support

Supported from 5.0

Description

Searches for files. Each function has a variant which searches for multiple files, using one or more wildcard characters in the filename. If an initial search is successful, further searches can be carried out using Find() or FindWild(). You can also retrieve the fully qualified file specification, and manipulate and interrogate it using the TParse class (or related classes).

Note that when specifying the path of a directory to search, the path should always end with a backslash character.

Defined in TFindFile:
File(), Find(), FindByDir(), FindByPath(), FindWild(), FindWildByDir(), FindWildByPath(), TFindFile()

See also:

• Using TFindFile

TFindFile(RFs& aFs);

Description

Constructs the object with a file server session.

Parameters

RFs& aFs File server session

TInt FindByPath(const TDesC& aFileName,const TDesC* aPathList);

Description

Searches for a file in one or more directories. The search ends when the file is found, or when every directory specified in the path list has been unsuccessfully searched.

Notes:

• For the equivalent search using wildcards, use FindWildByPath().

• After a file has been found, use TFindFile::File() to get the fully qualified path of the file. To search for the next occurrence, use TFindFile::Find().

Parameters

const TDesC& aFileName The filename to search for. If aFileName specifies a directory as well as a filename, that directory is searched first. const TDesC* aPathList List of directories to search. Paths in this list must be separated by a semicolon character, but a semicolon is not required after the final path. The directories are searched in the order in which they occur in the list. If a path in the list contains a drive letter, that drive alone is searched. If a path contains no drive letter, the function searches for the file in that directory on every available drive in turn, beginning with drive Y:, in descending alphabetical order and ending with drive Z:.

Return value

TInt KErrNone if the filename was found. KErrNotFound if the filename could not be found.

TInt FindByDir(const TDesC& aFileName,const TDesC& aDirPath);

Description

Searches for a file in a directory on all available drives. The search ends when the file is found, or when every available drive has been unsuccessfully searched.

Notes:

• A drive letter may be specified in aDirPath. If a drive is specified, that drive is searched first. If no drive is specified, the drive specified in the session path is searched first. The remaining available drives are then searched in descending alphabetical order, from y: to a:, and ending with the z: drive.

• For the corresponding search using wildcards, use FindWildByDir().

• After a file has been found, use TFindFile::File() to get the fully qualified path and filename. To search for the next occurrence, use TFindFile::Find().

Parameters

const TDesC& aFileName Filename to search for. If a path is specified, it overrides the path specified in aDirPath. If no path is specified, the path contained in aDirPath is used. const TDesC& aDirPath Single path indicating a directory to search on each drive.

Return value

TInt KErrNone if the file was found, KErrNotFound if not.

TInt Find();

Description

Searches for a file again. For use after a successful FindByPath() or FindByDir(), to find the next occurrence of the filename in the path or drive list.

Note:

• After a file has been found, use TFindFile::File() to get the fully qualified path and filename.

Return value

TInt KErrNone if another occurrence of the file was found or KErrNotFound if no more occurrences were found.

TInt FindWildByPath(const TDesC& aFileName,const TDesC* aPathList,CDir*& aDirList);

Description

Searches for one or more files in the directories contained in a path list. Wildcard characters can be specified. The search ends when one or more filenames matching aFileName is found, or when every directory in the path list has been unsuccessfully searched. To begin searching again after a successful match has been made, use FindWild().

Notes:

• The caller of the function is responsible for deleting aDirList after the function has returned.

• Calling TFindFile::File() after a successful search gets the drive letter and directory containing the file(s). The filenames can be retrieved via the array of TEntry::iNames contained in aDirList. If you want to retrieve the fully qualified path of a file, you need to parse the path and the filename.

Parameters

const TDesC& aFileName Filename to search for. May contain wildcards. If aFileName specifies a directory as well as a filename, that directory is searched first. const TDesC* aPathList List of directories to search. Paths in this list must be separated by a semicolon character, but a semicolon is not required after the final path. The directories are searched in the order in which they occur in the list. Directories must be fully qualified, including a drive letter and the name must end with a backslash. CDir*& aDirList On return, contains the entries for all files matching aFileName in the first directory in which a match occurred.

Return value

TInt KErrNotFound if no matching file was found in any of the directories, or KErrNone if one or more matching files was found.

See also:

• Using TFindFile

TInt FindWildByDir(const TDesC& aFileName,const TDesC& aDirPath,CDir*& aDir);

Description

Searches using wildcards for one or more files in a specified directory. If no matching file is found in that directory, all available drives are searched in descending alphabetical order, from y: to a:, and ending with the z: drive.

The search ends when one or more matching filenames are found, or when every available drive has been unsuccessfully searched. To begin searching again after a successful match has been made, use FindWild(). Wildcards may be specified in the filename.

Notes:

• A drive letter may be specified in aDirPath (or in aFileName). If a drive is specified, that drive is searched first, followed by the other available drives, in descending alphabetical order. If no drive is specified, the drive contained in the session path is searched first.

• The function sets aDir to NULL, then allocates memory for it before appending entries to the list. Therefore, aDir should have no memory allocated to it before this function is called, otherwise this memory will become orphaned.

• The caller of this function is responsible for deleting aDir after the function has returned.

• Calling TFindFile::File() after a successful search returns the drive letter and directory containing the file(s). Filenames may be retrieved via the array of TEntry::iNames contained in aDirList. If you want to retrieve the fully qualified path of a file, you will need to parse the path and the filename.

Parameters

const TDesC& aFileName Filename to search for. May contain wildcards. If a path is specified, it overrides the path specified in aDirPath. If no path is specified, the path contained in aDirPath is used in the search. const TDesC& aDirPath Path indicating a directory to search on each drive. CDir*& aDir On return, contains the entries for all files matching aFileName.

Return value

Tint KErrNotFound if no matching file was found in the directory on any of the drives, or KErrNone one or more matching files was found.

See also:

• Using TFindFile

TInt FindWild(CDir*& aDirList);

Description

Searches again after a successful FindWildByPath() orFindWildByDir(), for the next occurrences of the filename in the path or drive list.

Notes:

• The caller of this function is responsible for deleting aDirList after the function has returned.

• Calling TFindFile::File() after a successful search, will return the drive letter and directory containing the file(s). The filenames may be retrieved via the array of TEntry::iNames contained in aDirList. If you want to retrieve the fully qualified path of a file, you will need to parse the path and the filename using class TParse (or derived classes).

Parameters

CDir*& aDirList On return, contains the entries for all matching files found in the next directory.

Return value

TInt KErrNotFound if no more matching files were found, or KErrNone if further occurrences were found.

See also:

• Using TFindFile

const TDesC& File() const;

Description

Gets the full file specification of a file which was found by a successful call to one of the search variants which do not accept wildcards. The file specification includes drive, path and filename.

Notes:

• When called after a successful search using one of the variants which do accept wildcards, this function will only retrieve the drive letter and directory components of the path, not the filename. In this case, see the code contained in the link below for an example of how to get the fully qualified path.

Return value

TDesC& On return contains the full path and filename.

See also:

• Using TFindFile