Home Library Learn Downloads Support Community
Sign in | United States - English | |
12 out of 32 rated this helpful - Rate this topic

FindNextFile function

Applies to: desktop apps | Metro style apps

Continues a file search from a previous call to the FindFirstFile, FindFirstFileEx, or FindFirstFileTransacted functions.

Syntax

Copy 
BOOL WINAPI FindNextFile(
  __in   HANDLE hFindFile,
  __out  LPWIN32_FIND_DATA lpFindFileData
);

Parameters

hFindFile [in]

The search handle returned by a previous call to the FindFirstFile or FindFirstFileEx function.

lpFindFileData [out]

A pointer to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory.

Return value

If the function succeeds, the return value is nonzero and the lpFindFileData parameter contains information about the next file or directory found.

If the function fails, the return value is zero and the contents of lpFindFileData are indeterminate. To get extended error information, call the GetLastError function.

If the function fails because no more matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Remarks

This function uses the same search filters that were used to create the search handle passed in the hFindFile parameter. For additional information, see FindFirstFile and FindFirstFileEx.

The order in which the search returns the files, such as alphabetical order, is not guaranteed, and is dependent on the file system. If the data must be sorted, the application must do the ordering after obtaining all the results.

Note  In rare cases or on a heavily loaded system, file attribute information on NTFS file systems may not be current at the time this function is called. To be assured of getting the current NTFS file system file attributes, call the GetFileInformationByHandle function.

The order in which this function returns the file names is dependent on the file system type. With the NTFS file system and CDFS file systems, the names are usually returned in alphabetical order. With FAT file systems, the names are usually returned in the order the files were written to the disk, which may or may not be in alphabetical order. However, as stated previously, these behaviors are not guaranteed.

If the path points to a symbolic link, the WIN32_FIND_DATA buffer contains information about the symbolic link, not the target.

Transacted Operations

If there is a transaction bound to the file enumeration handle, then the files that are returned are subject to transaction isolation rules.

Examples

For an example, see Listing the Files in a Directory.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header
WinBase.h (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

Unicode and ANSI names

FindNextFileW (Unicode) and FindNextFileA (ANSI)

See also

File Management Functions
FindClose
FindFirstFile
FindFirstFileEx
GetFileAttributes
SetFileAttributes
Symbolic Links
WIN32_FIND_DATA

 

 

Send comments about this topic to Microsoft

Build date: 4/17/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
File Order Sequence is not as Expected [like that in explorer]
If you have files with these names: x(1), x(2), ...., x(10), x(11), ... this same order would be observed in explorer. But when you enumerate these files using this API the order you get is: x(1), x(11), x(12)...., x(2), x(21), ...
History
a problem using this function
$0with this function I can list all file names in a directory,but after this done, my program broken off....I don't know why...T.T$0 $0call stack indicated like this">msvcp90d.dll!std::_Container_base_secure::_Orphan_all()  Line 223 + 0x5 bytesC++"$0 $0and my code:$0 $0$0 $0 $0m_hFileFind = FindFirstFile(m_charToWchar(aDirectory.c_str()), m_lpFirstFile);$0 $0$0 $0 $0aFileNames.push_back(m_wcharToChar(m_lpFirstFile->cFileName));$0 $0while (FindNextFile(m_hFileFind, m_lpFirstFile))$0 $0{$0 $0aFileNames.push_back(m_wcharToChar(m_lpFirstFile->cFileName));$0 $0//cout << m_wcharToChar(m_lpNowFile->cFileName, wcslen(m_lpFirstFile->cFileName)) <<endl;$0 $0}$0 $0 $0$0 $0please help me,thank you.$0 $0$0 $0 $0$0 $0 $0I solved it....it's not because of the api...it's I forget to return a vector.....sorry$0
History
Re: DWORD translates to an Unsigned Integer, not to an Integer.

You should be using this algorithm to get the correct answer. In C#:
 
FILETIME ft;
 
//some code here to get a file time
 
var time = DateTime.FromFileTimeUtc(checked((long)(((ulong)ft.dwHighDateTime << 32) | ft.dwLowDateTime)));
 
Also same for file sizes:
 
WIN32_FIND_DATA data;
 
//some code here to get find file data

long fileLength = checked((long)(((ulong)data.nFileSizeHigh<< 32) | data.nFileSizeLow));

History
The Remarks section should mention FindClose
It seems like best practice to close the handle when you are done searching with the FindClose function, but this article doesn't mention this, it only links to it in the 'See Also' section.
History
DWORD translates to an Unsigned Integer, not to an Integer.
Often we see that DWORD values like nFileSizeHigh and nFileSizeLow are translated to Integer values. This is wrong and results in negative filesizes for large files. Microsoft should fix this at the .NET namespace Microsoft.Win32.Win32Native+WIN32_FIND_DATA (mscorlib.dll). Reference: http://mcdrummerman.wordpress.com/2010/07/13/win32_find_data-and-negative-file-sizes/ The same problem is seen at the System.Runtime.InteropServices.ComTypes.FILETIME structure (mscorlib.dll). Reference: http://www.pinvoke.net/default.aspx/Structures/WIN32_FIND_DATA.html
History
SafeFileHandle Structure 
      Imports Microsoft.Win32.SafeHandles

In the top of thee code. Furthermore:

    <Serializable(), StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Auto)> _
            Structure WIN32_FIND_DATA
        Public dwFileAttributes As IO.FileAttributes
        Public ftCreationTime As FILETIME
        Public ftLastAccessTime As FILETIME
        Public ftLastWriteTime As FILETIME
        Public nFileSizeHigh As Integer
        Public nFileSizeLow As Integer
        Public dwReserved0 As Integer
        Public dwReserved1 As Integer
        <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=260)> _
          Public cFileName As String
        <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=14)> _
            Public cAlternate As String
    End Structure

    Structure FILETIME
        Public dwLowDateTime As Integer
        Public dwHighDateTime As Integer
    End Structure
History
WIN32_FIND_DATA to be used in subsequent calls?
The article states:
"The structure can be used in subsequent calls to FindNextFile to indicate from which file to continue the search."

How is this possible? There is no mention of the function reading from lpFindFileData, and the parameter is marked [out].
History
vb.net syntax 
<DllImport("kernel32.dll", CharSet:=CharSet.Unicode, SetLastError:=True)> _
Public Shared Function FindNextFile(<[In]> ByVal hFindFile As SafeFileHandle, <Out> ByRef lpFindFileData As WIN32_FIND_DATA) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
History
C# syntax 
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
internal static extern bool FindNextFile([In] SafeFileHandle hFindFile, out WIN32_FIND_DATA lpFindFileData);
History