TFindFile Class Reference

Searches for files and directories. More...

#include <f32file.h>

Public Member Functions
IMPORT_C	TFindFile (RFs &aFs)
	Constructor taking a file server session.
IMPORT_C TInt	FindByPath (const TDesC &aFileName, const TDesC *aPathList)
	Searches for a file/directory in one or more directories in the path.
IMPORT_C TInt	FindByDir (const TDesC &aFileName, const TDesC &aDirPath)
	Searches for a file/directory in a directory on all available drives.
IMPORT_C TInt	Find ()
	Searches for the next file/directory.
IMPORT_C TInt	FindWildByPath (const TDesC &aFileName, const TDesC *aPathList, CDir *&aDirList)
	Searches for one or more files/directories in the directories contained in a path list.
IMPORT_C TInt	FindWildByDir (const TDesC &aFileName, const TDesC &aDirPath, CDir *&aDir)
	Searches, using wildcards, for one or more files/directories in a specified directory.
IMPORT_C TInt	FindWild (CDir *&aDirList)
	Searches for the next file/directory.
IMPORT_C TInt	SetFindMask (TUint aMask)
	Can be used in order to specify a combination of drive attributes that the drives to be searched must match.
const TDesC &	File () const
	Gets the full file specification of a file which was found by a successful call to any of the search variants that do not accept wildcards.

Detailed Description

Searches for files and directories.

Each function has a variant which searches for multiple files/directories, 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.When trailing backslash is not present then it is considered as file. And path will be taken till last backslash. The client must have appropriate capabilities for the directory to be searched. For example without ALL FILES Capability, it is not possible to successfully find any files under \sys\bin directory.

By default if the file is not found in the current drive the rest of the drives, excluding the remote ones, will be searched. Using function SetFindMask it is possible to specify a combination of drive attributes(aMask) that the drives to be searched must match.

API status

Published to all clients. Released API.

Definition at line 3276 of file f32file.h.

Constructor & Destructor Documentation

TFindFile()

IMPORT_C TFindFile::TFindFile

(

RFs &

aFs

)

Constructor taking a file server session.

Parameters

aFs	File server session.

(generated from Symbian Developer Library)

Member Function Documentation

File()

const TDesC & TFindFile::File ( ) const

inline

Gets the full file specification of a file which was found by a successful call to any of the search variants that do not accept wildcards.

The file specification includes drive, path and filename.

Notes:

1. When called after a successful search using wildcards the only valid components of the retrieved file specification are drive letter and directory.

(generated from Symbian Developer Library)

Find()

IMPORT_C TInt TFindFile::Find

(

)

Searches for the next file/directory.

This should be used after a successful call to FindByPath() or FindByDir(), to find the next occurrence of the filename in the path or drive list.

Using function SetFindMask it is possible to specify a combination of attributes that the drives to be searched must match.

Note:

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

TFindFile::FindByPath TFindFile::FindByDir TFindFile::File TFindFile::SetFindMask()

(generated from Symbian Developer Library)

FindByDir()

IMPORT_C TInt TFindFile::FindByDir	(	const TDesC &	aFileName,
		const TDesC &	aDirPath
	)

Searches for a file/directory in a directory on all available drives.

The search ends when the file/directory is found, or when every available drive has been unsuccessfully searched.

Notes:

1. A drive letter may be specified in aDirPath. If a drive is specified, then that drive is searched first. If no drive is specified, then 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. Using function SetFindMask it is possible to specify a combination of attributes that the drives to be searched must match.
2. For the corresponding search using wildcards, use FindWildByDir().
3. 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().

TFindFile::FindWildByDir() TFindFile::File() TFindFile::Find() TFindFile::SetFindMask()

Parameters

aFileName	The filename to search for. If a path is specified, it overrides the path specified in aDir. If no path is specified, the path contained in aDir is used.
aDirPath	A single path indicating a directory to be searched on each drive.When path is empty then session path will be used for the search.

(generated from Symbian Developer Library)

FindByPath()

IMPORT_C TInt TFindFile::FindByPath	(	const TDesC &	aFileName,
		const TDesC *	aPathList
	)

Searches for a file/directory in one or more directories in the path.

The search ends when the file/directory is found, or when every directory specified in the path list has been unsuccessfully searched.

Notes:

1. For the equivalent search using wildcards, use FindWildByPath().
2. 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().

TFindFile::FindWildByPath TFindFile::File TFindFile::Find

Parameters

aFileName

The filename to search for. If this specifies a directory as well as a filename, then that directory is searched first.

aPathList

A list of directories to be searched. 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:.When path is empty then session path will be used for the search.

(generated from Symbian Developer Library)

FindWild()

IMPORT_C TInt TFindFile::FindWild

(

CDir *&

aDirList

)

Searches for the next file/directory.

This should be used after a successful call to FindWildByPath() or FindWildByDir(), for the next occurrences of the filename in the path or drive list.Using function SetFindMask it is possible to specify a combination of attributes that the drives to be searched must match.

Notes:

1. 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.
2. The caller of the function is responsible for deleting aDir after the function has returned. On error this pointer will be set NULL, thus safe to delete.
3. Calling TFindFile::File() after a successful search, will return the drive letter and the directory containing the file(s). The filenames may be retrieved via the array of TEntry::iName objects contained in aDir. If you want to retrieve the fully qualified path of a file, you will need to parse the path and the filename using the TParse class or derived classes.

out: On success a pointer to the internally allocated by this method CDir object, which in turn contains the entries for all files matching aFileName in the first directory in which a match occurred. In this case this API caller is responsible for deleting aDir. If some error occured (including KErrNotFound meaning that nothing found) this pointer will be set to NULL, which is also safe to delete.

TParse TEntry::iName TFindFile::File TFindFile::FindWildByPath TFindFile::FindWildByDir TFindFile::SetFindMask()

Parameters

aDirList

in: a reference to the pointer that will be modified by this method.

(generated from Symbian Developer Library)

FindWildByDir()

IMPORT_C TInt TFindFile::FindWildByDir	(	const TDesC &	aFileName,
		const TDesC &	aDirPath,
		CDir *&	aDir
	)

Searches, using wildcards, for one or more files/directories 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.Using function SetFindMask it is possible to specify a combination of attributes that the drives to be searched must match.

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:

1. 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.
2. 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.
3. The caller of the function is responsible for deleting aDir after the function has returned. On error this pointer will be set NULL, thus safe to delete.
4. 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 aDir. If you want to retrieve the fully qualified path of a file, you will need to parse the path and the filename.

out: On success a pointer to the internally allocated by this method CDir object, which in turn contains the entries for all files matching aFileName in the first directory in which a match occurred. In this case this API caller is responsible for deleting aDir. If some error occured (including KErrNotFound meaning that nothing found) this pointer will be set to NULL, which is also safe to delete.

TFindFile::FindWild TFindFile::File TFindFile::SetFindMask()

Parameters

aFileName	The 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.
aDirPath	Path indicating a directory to search on each drive.
aDir	in: a reference to the pointer that will be modified by this method.

(generated from Symbian Developer Library)

FindWildByPath()

IMPORT_C TInt TFindFile::FindWildByPath	(	const TDesC &	aFileName,
		const TDesC *	aPathList,
		CDir *&	aDirList
	)

Searches for one or more files/directories 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().

Using function SetFindMask it is possible to specify a combination of attributes that the drives to be searched must match.

Notes:

1. 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.
2. The caller of the function is responsible for deleting aDir after the function has returned. On error this pointer will be set NULL, thus safe to delete.
3. 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::iName objects contained in aDir. If you want to retrieve the fully qualified path of a file, you need to parse the path and the filename.

out: On success a pointer to the internally allocated by this method CDir object, which in turn contains the entries for all files matching aFileName in the first directory in which a match occurred. In this case this API caller is responsible for deleting aDir. If some error occured (including KErrNotFound meaning that nothing found) this pointer will be set to NULL, which is also safe to delete.

TFindFile::FindWild TFindFile::File TEntry::iName TFindFile::SetFindMask()

Parameters

aFileName	The filename to search for. May contain wildcards. If it specifies a directory as well as a filename, then that directory is searched first.
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.
aDirList	in: a reference to the pointer that will be modified by this method.

(generated from Symbian Developer Library)

SetFindMask()

IMPORT_C TInt TFindFile::SetFindMask

(

TUint

aMask

)

Can be used in order to specify a combination of drive attributes that the drives to be searched must match.

When searching without specifying a mask, all drives, except the remote ones will be returned.

Parameters

aMask

The combination of drive attributes that we want the drives to match.

(generated from Symbian Developer Library)

---

The documentation for this class was generated from the following files:

• f32file.h
• f32file.h.dox