| 术语 | findfirstfileex |
| 释义 | FindFirstFileEx 语法： C++ HANDLE WINAPI FindFirstFileEx( __in LPCTSTR lpFileName, __in FINDEX_INFO_LEVELS fInfoLevelId, __out LPVOID lpFindFileData, __in FINDEX_SEARCH_OPS fSearchOp, __reserved LPVOID lpSearchFilter, __in DWORD dwAdditionalFlags ); FindFirstFileEx功能 搜索一个文件或文件的名称和属性符合这些指定的子目录的目录。 对于这一职能的最基本的版本，请FindFirstFile。 作为一个要执行此操作的事务操作，请使用FindFirstFileTransacted功能。 参数 lpFileName [in] 该目录或路径和文件名，可以包括通配符，例如，一个星号(*)或问号(？)。 这个参数不能为NULL，一个无效的字符串(例如，空字符串或一个字符串，它缺少终止空字符)，或者结束一个尾部反斜杠(\\)。 如果字符串以一个通配符，期限，或目录名结束后，用户必须访问根路径上所有子目录。 在此函数的ANSI版本，名称被限制为MAX_PATH字符。为了延长此限制，以约32,000宽字符，调用的功能和前面加上“\\ Unicode版本\\？\\”的路径。有关更多信息，请参见命名一个文件。 fInfoLevelId [in] 返回的数据信息的Level。 这个参数是FINDEX_INFO_LEVELS枚举值之一。 lpFindFileData [out] 一个缓冲区，接收文件数据的指针。 指针的类型是由信息是在fInfoLevelId参数中指定的Level。 fSearchOp [in] 在执行过滤即由不同类型的通配符匹配。 这个参数是FINDEX_SEARCH_OPS枚举值之一。 lpSearchFilter 一个指针搜索条件如果指定fSearchOp需要的搜寻信息。 在这个时候，支持的fSearchOp值都需要扩展搜索信息。因此，这个指针必须为NULL。 dwAdditionalFlags [in] 指定附加的选项来控制搜寻。 ValueMeaning FIND_FIRST_EX_CASE_SENSITIVE 1Searches区分大小写。 FIND_FIRST_EX_LARGE_FETCH 2Uses一个目录查询，从而增加了发现经营业绩较大的缓冲区。 Windows Server 2008中，Windows Vista中的Windows Server 2003，和Windows XP/2000：此值不支持，直到Windows服务器2008 R2和Windows 7。 返回值 如果函数成功，返回值是一个搜索在随后的电话用于FindNextFile或FindClose处理，以及lpFindFileData参数包含的第一个文件或目录信息找到。 如果函数失败或未能找到从在lpFileName参数搜索字符串的文件，返回值是INVALID_HANDLE_VALUE和lpFindFileData的内容是不确定的。为了获得更多错误信息，调用GetLastError函数。 备注 该FindFirstFileEx函数打开一个搜索句柄和返回有关信息的第一个文件，该文件系统的名称指定模式匹配的发现。这可能是也可能不是第一个文件或目录，在一个目录中，上市申请(如dir命令)时，给予相同的文件名字符串模式。这是因为FindFirstFileEx并没有在搜索结果的排序。有关其他信息，请参见FindNextFile。 下面的列表列出了一些其他的搜索特点： 在严格执行搜索的文件名没有任何属性，如日期或文件类型。 搜寻工作包括长和短文件名。 尝试打开一个以反斜杠搜索总是失败。 传递一个无效的字符串，空，或lpFileName参数为空字符串，是不是这个功能的有效使用。在这种情况下，结果是不确定的。 注意：在极少数情况下，文件在NTFS文件系统的信息可能不是您的时候调用此函数电流。为了成为获取当前文件的信息保证，调用GetFileInformationByHandle功能。 如果底层文件系统不支持过滤指定类型，目录以外的过滤，FindFirstFileEx的错误而失败ERROR_NOT_SUPPORTED。应用程序必须使用FINDEX_SEARCH_OPS类型FileExSearchNameMatch和履行自己的过滤。 处理后成立的搜索，请在FindNextFile函数中为其他文件的搜索匹配的相同的过滤正在执行相同的模式。当搜索处理是不需要的，应当使用FindClose函数关闭。 如前所述，您不能使用一个尾部反斜杠(\\)在为FindFirstFileEx lpFileName输入字符串，因此它可能不是很明显了如何搜索根目录。如果您想看到的文件或取得的根目录的属性，下列选项将适用于： 要检查在根目录中的文件，可以使用的“C：\\ *”，并通过目录步骤使用FindNextFile。 为了得到一个根目录的属性，使用GetFileAttributes函数。 注意：前面加上字符串“\\ \\？\\”不允许访问根目录。 网络共享上，您可以使用下列形成lpFileName：“\\ \\服务器\\服务\\ *”。但是，您不能使用一个lpFileName，为自己点的共享，例如，“\\ \\服务器\\服务”是无效的。 要检查一个目录不是根目录，请使用该目录的路径，如果没有一个尾部反斜杠。例如，争论的“C：\\ Windows的”返回有关目录“C：\\ Windows”时，一个目录或文件在“C：\\ Windows无法信息”。要检查文件和目录在“C：\\ Windows”时，使用的lpFileName的“C：\\的Windows \\ *”。 下面的调用： FindFirstFileEx(lpFileName， FindExInfoStandard， lpFindData， FindExSearchNameMatch， 空， 0); 等同于以下调用： FindFirstFile(lpFileName，lpFindData); 请注意，其他线程或进程可以创建或删除与此之间的时间您查询的结果，当您靠这个信息文件的名称。如果这是您的应用程序，一个可能的解决方案可能引起关注的是使用CREATE_NEW CreateFile函数(它失败如果该文件存在)或OPEN_EXISTING(其中失败如果文件不存在)。 如果您正在写一个32位应用程序列出目录中的所有文件和应用程序可能在运行64位的计算机，您应该调用之前调用FindFirstFileEx和之后的最后一次调用FindNextFile呼叫Wow64RevertWow64FsRedirection Wow64DisableWow64FsRedirection。有关更多信息，请参阅文件系统重定向器。 如果路径指向一个符号链接，WIN32_FIND_DATA缓冲区包含符号链接信息，而不是目标。 实例 下面的代码显示了FindFirstFileEx最小的使用。此程序相当于在FindFirstFile主题中的示例。 #include #include #include void _tmain(int argc, TCHAR *argv[]) { WIN32_FIND_DATA FindFileData; HANDLE hFind; if( argc != 2 ) { _tprintf(TEXT("Usage: %s [target_file]\\n"), argv[0]); return; } _tprintf (TEXT("Target file is %s\\n"), argv[1]); hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData, FindExSearchNameMatch, NULL, 0); if (hFind == INVALID_HANDLE_VALUE) { printf ("FindFirstFileEx failed (%d)\\n", GetLastError()); return; } else { _tprintf (TEXT("The first file found is %s\\n"), FindFileData.cFileName); FindClose(hFind); } } 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinBase.h(头文件：winuser.h) LibraryKernel32.lib DLLKernel32.dll Unicode和ANSI namesFindFirstFileExW(Unicode)和FindFirstFileExA(ANSI)的 参见 文件管理函数 FindClose FINDEX_INFO_LEVELS FINDEX_SEARCH_OPS FindFirstFile FindFirstFileTransacted FindNextFile GetFileAttributes 命名一个文件 符号链接 使用Windows头 WIN32_FIND_DATA 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年9月3日 ＝＝英文原文＝＝FindFirstFileEx Function Searches a directory for a file or subdirectory with a name and attributes that match those specified. For the most basic version of this function, see FindFirstFile . To perform this operation as a transacted operation, use the FindFirstFileTransacted function. Syntax C++ HANDLE WINAPI FindFirstFileEx( __in LPCTSTR lpFileName, __in FINDEX_INFO_LEVELS fInfoLevelId, __out LPVOID lpFindFileData, __in FINDEX_SEARCH_OPS fSearchOp, __reserved LPVOID lpSearchFilter, __in DWORD dwAdditionalFlags ); Parameters lpFileName [in] The directory or path, and the file name, which can include wildcard characters, for example, an asterisk (*) or a question mark (?). This parameter should not be NULL, an invalid string (for example, an empty string or a string that is missing the terminating null character), or end in a trailing backslash (\\). If the string ends with a wildcard, period, or directory name, the user must have access to the root and all subdirectories on the path. In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to approximately 32,000 wide characters, call the Unicode version of the function and prepend "\\\\?\\" to the path. For more information, see Naming a File . fInfoLevelId [in] The information level of the returned data. This parameter is one of the FINDEX_INFO_LEVELS enumeration values. lpFindFileData [out] A pointer to the buffer that receives the file data. The pointer type is determined by the level of information that is specified in the fInfoLevelId parameter. fSearchOp [in] The type of filtering to perform that is different from wildcard matching. This parameter is one of the FINDEX_SEARCH_OPS enumeration values. lpSearchFilter A pointer to the search criteria if the specified fSearchOp needs structured search information. At this time, none of the supported fSearchOp values require extended search information. Therefore, this pointer must be NULL. dwAdditionalFlags [in] Specifies additional flags that control the search. ValueMeaning FIND_FIRST_EX_CASE_SENSITIVE 1Searches are case-sensitive. FIND_FIRST_EX_LARGE_FETCH 2Uses a larger buffer for directory queries, which can increase performance of the find operation. Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP/2000: This value is not supported until Windows Server 2008 R2 and Windows 7. Return Value If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose , and the lpFindFileData parameter contains information about the first file or directory found. If the function fails or fails to locate files from the search string in the lpFileName parameter, the return value is INVALID_HANDLE_VALUE and the contents of lpFindFileData are indeterminate. To get extended error information, call the GetLastError function. Remarks The FindFirstFileEx function opens a search handle and returns information about the first file that the file system finds with a name that matches the specified pattern. This may or may not be the first file or directory that appears in a directory-listing application (such as the dir command) when given the same file name string pattern. This is because FindFirstFileEx does no sorting of the search results. For additional information, see FindNextFile. The following list identifies some other search characteristics: The search is performed strictly on the name of the file, not on any attributes such as a date or a file type. The search includes the long and short file names. An attempt to open a search with a trailing backslash always fails. Passing an invalid string, NULL, or empty string for the lpFileName parameter is not a valid use of this function. Results in this case are undefined. Note In rare cases, file information on NTFS file systems may not be current at the time you call this function. To be assured of getting the current file information, call the GetFileInformationByHandle function. If the underlying file system does not support the specified type of filtering, other than directory filtering, FindFirstFileEx fails with the error ERROR_NOT_SUPPORTED. The application must use FINDEX_SEARCH_OPS type FileExSearchNameMatch and perform its own filtering. After the search handle is established, use it in the FindNextFile function to search for other files that match the same pattern with the same filtering that is being performed. When the search handle is not needed, it should be closed by using the FindClose function. As stated previously, you cannot use a trailing backslash (\\) in the lpFileName input string for FindFirstFileEx, therefore it may not be obvious how to search root directories. If you want to see files or get the attributes of a root directory, the following options would apply: To examine files in a root directory, you can use "C:\\*" and step through the directory by using FindNextFile . To get the attributes of a root directory, use the GetFileAttributes function. Note Prepending the string "\\\\?\\" does not allow access to the root directory. On network shares, you can use an lpFileName in the form of the following: "\\\\server\\service\\*". However, you cannot use an lpFileName that points to the share itself; for example, "\\\\server\\service" is not valid. To examine a directory that is not a root directory, use the path to that directory, without a trailing backslash. For example, an argument of "C:\\Windows" returns information about the directory "C:\\Windows", not about a directory or file in "C:\\Windows". To examine the files and directories in "C:\\Windows", use an lpFileName of "C:\\Windows\\*". The following call: FindFirstFileEx( lpFileName, FindExInfoStandard, lpFindData, FindExSearchNameMatch, NULL, 0 ); Is equivalent to the following call: FindFirstFile( lpFileName, lpFindData ); Be aware that some other thread or process could create or delete a file with this name between the time you query for the result and the time you act on the information. If this is a potential concern for your application, one possible solution is to use the CreateFile function with CREATE_NEW (which fails if the file exists) or OPEN_EXISTING (which fails if the file does not exist). If you are writing a 32-bit application to list all the files in a directory and the application may be run on a 64-bit computer, you should call Wow64DisableWow64FsRedirection before calling FindFirstFileEx and call Wow64RevertWow64FsRedirection after the last call to FindNextFile. For more information, see File System Redirector . If the path points to a symbolic link, the WIN32_FIND_DATA buffer contains information about the symbolic link, not the target. Examples The following code shows a minimal use of FindFirstFileEx. This program is equivalent to the example in the FindFirstFile topic. #include #include #include void _tmain(int argc, TCHAR *argv[]) { WIN32_FIND_DATA FindFileData; HANDLE hFind; if( argc != 2 ) { _tprintf(TEXT("Usage: %s [target_file]\\n"), argv[0]); return; } _tprintf (TEXT("Target file is %s\\n"), argv[1]); hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData, FindExSearchNameMatch, NULL, 0); if (hFind == INVALID_HANDLE_VALUE) { printf ("FindFirstFileEx failed (%d)\\n", GetLastError()); return; } else { _tprintf (TEXT("The first file found is %s\\n"), FindFileData.cFileName); FindClose(hFind); } } Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinBase.h (include Windows.h) LibraryKernel32.lib DLLKernel32.dll Unicode and ANSI namesFindFirstFileExW (Unicode) and FindFirstFileExA (ANSI) See Also File Management Functions FindClose FINDEX_INFO_LEVELS FINDEX_SEARCH_OPS FindFirstFile FindFirstFileTransacted FindNextFile GetFileAttributes Naming a File Symbolic Links Using the Windows Headers WIN32_FIND_DATA Send comments about this topic to Microsoft Build date: 9/3/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa364419(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。