Performs local file searches and is the base class for CGopherFileFind and CFtpFileFind, which perform Internet file searches.

class CFileFind : public CObject

CFileFind includes member functions that begin a search, locate a file, and return the title, name, or path of the file. For Internet searches, the member function GetFileURL returns the file's URL.

CFileFind is the base class for two other MFC classes designed to search particular server types: CGopherFileFind works specifically with gopher servers, and CFtpFileFind works specifically with FTP servers. Together, these three classes provide a seamless mechanism for the client to find files, regardless of the server protocol, the file type, or location, on either a local machine or a remote server.

The following code will enumerate all the files in the current directory, printing the name of each file:

[!code-cppNVC_MFCFiles#31]

To keep the example simple, this code uses the C++ Standard Library cout class. The cout line could be replaced with a call to CListBox::AddString, for example, in a program with a graphical user interface.

For more information about how to use CFileFind and the other WinInet classes, see the article Internet Programming with WinInet.

CObject

CFileFind

Header: afx.h

This member function is called when a CFileFind object is constructed.

CFileFind();
CFileFind(CAtlTransactionManager* pTM);

pTM
Pointer to CAtlTransactionManager object

See the example for CFileFind::GetFileName.

Call this member function to end the search, reset the context, and release all resources.

void Close();

After calling Close, you do not have to create a new CFileFind instance before calling FindFile to begin a new search.

See the example for CFileFind::GetFileName.

Closes the file specified by the current search handle.

virtual void CloseContext();

Closes the file specified by the current value of the search handle. Override this function to change the default behavior.

You must call the FindFile or FindNextFile functions at least once to retrieve a valid search handle. The FindFile and FindNextFile functions use the search handle to locate files with names that match a given name.

Call this member function to open a file search.

virtual BOOL FindFile(
    LPCTSTR pstrName = NULL,
    DWORD dwUnused = 0);

pstrName
A pointer to a string containing the name of the file to find. If you pass NULL for pstrName, FindFile does a wildcard (*.*) search.

dwUnused
Reserved to make FindFile polymorphic with derived classes. Must be 0.

Nonzero if successful; otherwise 0. To get extended error information, call the Win32 function GetLastError.

After calling FindFile to begin the file search, call FindNextFile to retrieve subsequent files. You must call FindNextFile at least once before calling any of the following attribute member functions:

• GetCreationTime

• GetFileName

• GetFileTitle

• GetFilePath

• GetFileURL

• GetLastAccessTime

• GetLastWriteTime

• GetLength

• GetRoot

• IsArchived

• IsCompressed

• IsDirectory

• IsDots

• IsHidden

• IsNormal

• IsReadOnly

• IsSystem

• IsTemporary

• MatchesMask

See the example for CFileFind::IsDirectory.

Call this member function to continue a file search from a previous call to FindFile.

virtual BOOL FindNextFile();

Nonzero if there are more files; zero if the file found is the last one in the directory or if an error occurred. To get extended error information, call the Win32 function GetLastError. If the file found is the last file in the directory, or if no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

You must call FindNextFile at least once before calling any of the following attribute member functions:

• GetCreationTime

• GetFileName

• GetFileTitle

• GetFilePath

• GetFileURL

• GetLastAccessTime

• GetLastWriteTime

• GetLength

• GetRoot

• IsArchived

• IsCompressed

• IsDirectory

• IsDots

• IsHidden

• IsNormal

• IsReadOnly

• IsSystem

• IsTemporary

• MatchesMask

FindNextFile wraps the Win32 function FindNextFile.

See the example for CFileFind::IsDirectory.

Call this member function to get the time the specified file was created.

virtual BOOL GetCreationTime(FILETIME* pTimeStamp) const;
virtual BOOL GetCreationTime(CTime& refTime) const;

pTimeStamp
A pointer to a FILETIME structure containing the time the file was created.

refTime
A reference to a CTime object.

Nonzero if successful; 0 if unsuccessful. GetCreationTime returns 0 only if FindNextFile has never been called on this CFileFind object.

You must call FindNextFile at least once before calling GetCreationTime.

See the example for CFileFind::GetLength.

Call this member function to get the name of the found file.

virtual CString GetFileName() const;

The name of the most-recently-found file.

You must call FindNextFile at least once before calling GetFileName.

GetFileName is one of three CFileFind member functions that return some form of the file name. The following list describes the three and how they vary:

• GetFileName returns the file name, including the extension. For example, calling GetFileName to generate a user message about the file c:\myhtml\myfile.txt returns the file name myfile.txt.

• GetFilePath returns the entire path for the file. For example, calling GetFilePath to generate a user message about the file c:\myhtml\myfile.txt returns the file path c:\myhtml\myfile.txt.

• GetFileTitle returns the file name, excluding the file extension. For example, calling GetFileTitle to generate a user message about the file c:\myhtml\myfile.txt returns the file title myfile.

[!code-cppNVC_MFCFiles#32]

Call this member function to get the full path of the specified file.

virtual CString GetFilePath() const;

The path of the specified file.

You must call FindNextFile at least once before calling GetFilePath.

GetFilePath is one of three CFileFind member functions that return some form of the file name. The following list describes the three and how they vary:

• GetFileName returns the file name, including the extension. For example, calling GetFileName to generate a user message about the file c:\myhtml\myfile.txt returns the file name myfile.txt.

• GetFilePath returns the entire path for the file. For example, calling GetFilePath to generate a user message about the file c:\myhtml\myfile.txt returns the file path c:\myhtml\myfile.txt.

• GetFileTitle returns the file name, excluding the file extension. For example, calling GetFileTitle to generate a user message about the file c:\myhtml\myfile.txt returns the file title myfile.

See the example for CFileFind::GetFileName.

Call this member function to get the title of the found file.

virtual CString GetFileTitle() const;

The title of the file.

You must call FindNextFile at least once before calling GetFileTitle.

GetFileTitle is one of three CFileFind member functions that return some form of the file name. The following list describes the three and how they vary:

• GetFileName returns the file name, including the extension. For example, calling GetFileName to generate a user message about the file c:\myhtml\myfile.txt returns the file name myfile.txt.

• GetFilePath returns the entire path for the file. For example, calling GetFilePath to generate a user message about the file c:\myhtml\myfile.txt returns the file path c:\myhtml\myfile.txt.

• GetFileTitle returns the file name, excluding the file extension. For example, calling GetFileTitle to generate a user message about the file c:\myhtml\myfile.txt returns the file title myfile.

See the example for CFileFind::GetFileName.

Call this member function to retrieve the specified URL.

virtual CString GetFileURL() const;

The complete URL.

You must call FindNextFile at least once before calling GetFileURL.

GetFileURL is similar to the member function GetFilePath, except that it returns the URL in the form file://path. For example, calling GetFileURL to get the complete URL for myfile.txt returns the URL file://c:\myhtml\myfile.txt.

See the example for CFileFind::GetFileName.

Call this member function to get the time that the specified file was last accessed.

virtual BOOL GetLastAccessTime(CTime& refTime) const;
virtual BOOL GetLastAccessTime(FILETIME* pTimeStamp) const;

refTime
A reference to a CTime object.

pTimeStamp
A pointer to a FILETIME structure containing the time the file was last accessed.

Nonzero if successful; 0 if unsuccessful. GetLastAccessTime returns 0 only if FindNextFile has never been called on this CFileFind object.

You must call FindNextFile at least once before calling GetLastAccessTime.

See the example for CFileFind::GetLength.

Call this member function to get the last time the file was changed.

virtual BOOL GetLastWriteTime(FILETIME* pTimeStamp) const;
virtual BOOL GetLastWriteTime(CTime& refTime) const;

pTimeStamp
A pointer to a FILETIME structure containing the time the file was last written to.

refTime
A reference to a CTime object.

Nonzero if successful; 0 if unsuccessful. GetLastWriteTime returns 0 only if FindNextFile has never been called on this CFileFind object.

You must call FindNextFile at least once before calling GetLastWriteTime.

See the example for CFileFind::GetLength.

Call this member function to get the length of the found file, in bytes.

ULONGLONG GetLength() const;

The length of the found file, in bytes.

You must call FindNextFile at least once before calling GetLength.

GetLength uses the Win32 structure WIN32_FIND_DATA to get and return the value of the file size, in bytes.

[!code-cppNVC_MFCFiles#33]

Call this member function to get the root of the found file.

virtual CString GetRoot() const;

The root of the active search.

You must call FindNextFile at least once before calling GetRoot.

This member function returns the drive specifier and path name used to start a search. For example, calling FindFile with *.dat results in GetRoot returning an empty string. Passing a path, such as c:\windows\system\*.dll, to FindFile results GetRoot returning c:\windows\system\.

See the example for CFileFind::GetFileName.

Call this member function to determine if the found file is archived.

BOOL IsArchived() const;

Nonzero if successful; otherwise 0.

Applications mark an archive file, which is to be backed up or removed, with FILE_ATTRIBUTE_ARCHIVE, a file attribute identified in the WIN32_FIND_DATA structure.

You must call FindNextFile at least once before calling IsArchived.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Call this member function to determine if the found file is compressed.

BOOL IsCompressed() const;

Nonzero if successful; otherwise 0.

A compressed file is marked with FILE_ATTRIBUTE_COMPRESSED, a file attribute identified in the WIN32_FIND_DATA structure. For a file, this attribute indicates that all of the data in the file is compressed. For a directory, this attribute indicates that compression is the default for newly created files and subdirectories.

You must call FindNextFile at least once before calling IsCompressed.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Call this member function to determine if the found file is a directory.

BOOL IsDirectory() const;

Nonzero if successful; otherwise 0.

A file that is a directory is marked with FILE_ATTRIBUTE_DIRECTORY a file attribute identified in the WIN32_FIND_DATA structure.

You must call FindNextFile at least once before calling IsDirectory.

See the member function MatchesMask for a complete list of file attributes.

This small program recurses every directory on the C:\ drive and prints the name of the directory.

[!code-cppNVC_MFCFiles#34]

Call this member function to test for the current directory and parent directory markers while iterating through files.

virtual BOOL IsDots() const;

Nonzero if the found file has the name "." or "..", which indicates that the found file is actually a directory. Otherwise 0.

You must call FindNextFile at least once before calling IsDots.

See the example for CFileFind::IsDirectory.

Call this member function to determine if the found file is hidden.

BOOL IsHidden() const;

Nonzero if successful; otherwise 0.

Hidden files, which are marked with FILE_ATTRIBUTE_HIDDEN, a file attribute identified in the WIN32_FIND_DATA structure. A hidden file is not included in an ordinary directory listing.

You must call FindNextFile at least once before calling IsHidden.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Call this member function to determine if the found file is a normal file.

BOOL IsNormal() const;

Nonzero if successful; otherwise 0.

Files marked with FILE_ATTRIBUTE_NORMAL, a file attribute identified in the WIN32_FIND_DATA structure. A normal file has no other attributes set. All other file attributes override this attribute.

You must call FindNextFile at least once before calling IsNormal.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Call this member function to determine if the found file is read-only.

BOOL IsReadOnly() const;

Nonzero if successful; otherwise 0.

A read-only file is marked with FILE_ATTRIBUTE_READONLY, a file attribute identified in the WIN32_FIND_DATA structure. Applications can read such a file, but they cannot write to it or delete it.

You must call FindNextFile at least once before calling IsReadOnly.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Call this member function to determine if the found file is a system file.

BOOL IsSystem() const;

Nonzero if successful; otherwise 0.

A system file is marked with FILE_ATTRIBUTE_SYSTEM, a file attribute identified in the WIN32_FIND_DATA structure. A system file is part of, or is used exclusively by, the operating system.

You must call FindNextFile at least once before calling IsSystem.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Call this member function to determine if the found file is a temporary file.

BOOL IsTemporary() const;

Nonzero if successful; otherwise 0.

A temporary file is marked with FILE_ATTRIBUTE_TEMPORARY, a file attribute identified in the WIN32_FIND_DATA structure. A temporary file is used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file's data remains in memory without being flushed to the media because the file will soon be deleted.

You must call FindNextFile at least once before calling IsTemporary.

See the member function MatchesMask for a complete list of file attributes.

See the example for CFileFind::GetLength.

Pointer to a CAtlTransactionManager object.

CAtlTransactionManager* m_pTM;

Call this member function to test the file attributes on the found file.

virtual BOOL MatchesMask(DWORD dwMask) const;

dwMask
Specifies one or more file attributes, identified in the WIN32_FIND_DATA structure, for the found file. To search for multiple attributes, use the bitwise OR (|) operator. Any combination of the following attributes is acceptable:

• FILE_ATTRIBUTE_ARCHIVE The file is an archive file. Applications use this attribute to mark files for backup or removal.

• FILE_ATTRIBUTE_COMPRESSED The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.

• FILE_ATTRIBUTE_DIRECTORY The file is a directory.

• FILE_ATTRIBUTE_NORMAL The file has no other attributes set. This attribute is valid only if used alone. All other file attributes override this attribute.

• FILE_ATTRIBUTE_HIDDEN The file is hidden. It is not to be included in an ordinary directory listing.

• FILE_ATTRIBUTE_READONLY The file is read only. Applications can read the file but cannot write to it or delete it.

• FILE_ATTRIBUTE_SYSTEM The file is part of or is used exclusively by the operating system.

• FILE_ATTRIBUTE_TEMPORARY The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file's data remains in memory without being flushed to the media because the file will soon be deleted.

Nonzero if successful; otherwise 0. To get extended error information, call the Win32 function GetLastError.

You must call FindNextFile at least once before calling MatchesMask.

[!code-cppNVC_MFCFiles#35]

CObject Class
Hierarchy Chart
CFtpFileFind Class
CGopherFileFind Class
CInternetFile Class
CGopherFile Class
CHttpFile Class