FindFirstFileExA 함수(fileapi.h)

아티클
11/20/2024

디렉터리에서 지정된 이름과 특성과 일치하는 파일 또는 하위 디렉터리를 검색합니다.

이 함수의 가장 기본적인 버전은 FindFirstFile참조하세요.

이 작업을 트랜잭션 작업으로 수행하려면 FindFirstFileTransacted 함수를 사용합니다.

통사론

HANDLE FindFirstFileExA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags
);

매개 변수

[in] lpFileName

디렉터리 또는 경로 및 파일 이름입니다. 파일 이름에는 와일드카드 문자(예: 별표(*) 또는 물음표(?)가 포함될 수 있습니다.

이 매개 변수는 NULL , 잘못된 문자열(예: 빈 문자열 또는 종료 null 문자가 누락된 문자열) 또는 후행 백슬래시(\)로 끝나서는 안 됩니다.

문자열이 와일드카드, 마침표 또는 디렉터리 이름으로 끝나는 경우 사용자는 경로의 루트 및 모든 하위 디렉터리에 액세스할 수 있어야 합니다.

기본적으로 이름은 MAX_PATH 문자로 제한됩니다. 이 제한을 32,767자로 확장하려면 경로 앞에 "\\?\"를 추가합니다. 자세한 내용은 이름 지정 파일, 경로 및 네임스페이스참조하세요.

팁

Windows 10 버전 1607부터 "\\?\" 앞에 추가하지 않고 MAX_PATH 제한을 제거하도록 옵트인할 수 있습니다. 자세한 내용은 명명 파일, 경로 및 네임스페이스의 "최대 경로 길이 제한" 섹션을.

[in] fInfoLevelId

반환된 데이터의 정보 수준입니다.

이 매개 변수는 FINDEX_INFO_LEVELS 열거형 값 중 하나입니다.

[out] lpFindFileData

파일 데이터를 받는 버퍼에 대한 포인터입니다.

포인터 형식은 fInfoLevelId 매개 변수에 지정된 정보 수준에 따라 결정됩니다.

[in] fSearchOp

와일드카드 일치와 다른 수행할 필터링 유형입니다.

이 매개 변수는 FINDEX_SEARCH_OPS 열거형 값 중 하나입니다.

lpSearchFilter

지정된 fSearchOp 구조화된 검색 정보가 필요한 경우 검색 조건에 대한 포인터입니다.

현재 지원되는 fSearchOp 값에는 확장 검색 정보가 필요하지 않습니다. 따라서 이 포인터는 NULL합니다.

[in] dwAdditionalFlags

검색을 제어하는 추가 플래그를 지정합니다.

값	의미
FIND_FIRST_EX_CASE_SENSITIVE 1	검색은 대/소문자를 구분합니다.
FIND_FIRST_EX_LARGE_FETCH 2	더 큰 버퍼를 디렉터리 쿼리에 사용하므로 찾기 작업의 성능이 향상됩니다. Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 값은 Windows Server 2008 R2 및 Windows 7까지 지원되지 않습니다.
FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY 4	결과를 디스크에 물리적으로 있는 파일로 제한합니다. 이 플래그는 파일 가상화 필터가 있는 경우에만 관련이 있습니다.

반환 값

함수가 성공하면 반환 값은 FindNextFile 또는 findClose후속 호출에 사용되는 검색 핸들이며, lpFindFileData 매개 변수에는 찾은 첫 번째 파일 또는 디렉터리에 대한 정보가 포함됩니다.

함수가 lpFileName 매개 변수의 검색 문자열에서 파일을 찾지 못하거나 실패하면 반환 값이 INVALID_HANDLE_VALUElpFindFileData 내용이 확정되지 않습니다. 확장 오류 정보를 얻으려면 GetLastError 함수를 호출합니다.

발언

FindFirstFileEx 함수는 검색 핸들을 열고 지정된 패턴과 일치하는 이름으로 파일 시스템에서 찾은 첫 번째 파일에 대한 정보를 반환합니다. 동일한 파일 이름 문자열 패턴이 지정된 경우 디렉터리 목록 애플리케이션(예: dir 명령)에 표시되는 첫 번째 파일 또는 디렉터리일 수도 있습니다. FindFirstFileEx 검색 결과를 정렬하지 않기 때문입니다. 자세한 내용은 FindNextFile참조하세요.

다음 목록에서는 몇 가지 다른 검색 특성을 식별합니다.

검색은 날짜 또는 파일 형식과 같은 특성이 아니라 파일 이름에 따라 엄격하게 수행됩니다.
검색에는 길고 짧은 파일 이름이 포함됩니다.
후행 백슬래시를 사용하여 검색을 열려는 시도는 항상 실패합니다.
lpFileName 매개 변수에 대해 잘못된 문자열, NULL또는 빈 문자열을 전달하는 것은 이 함수를 잘못 사용하는 것이 아닙니다. 이 경우 결과는 정의되지 않습니다.

참고 드문 경우나 로드된 시스템에서는 이 함수가 호출될 때 NTFS 파일 시스템에 대한 파일 특성 정보가 최신 정보가 아닐 수 있습니다. 현재 NTFS 파일 시스템 파일 특성을 가져오려면 GetFileInformationByHandle 함수를 호출합니다.

기본 파일 시스템에서 디렉터리 필터링 이외의 지정된 형식의 필터링을 지원하지 않으면 FindFirstFileEx 오류 ERROR_NOT_SUPPORTED실패합니다. 애플리케이션은 FileExSearchNameMatch FINDEX_SEARCH_OPS 형식을 사용하고 자체 필터링을 수행해야 합니다.

검색 핸들이 설정되면 FindNextFile 함수에서 이 핸들을 사용하여 수행 중인 동일한 필터링과 동일한 패턴과 일치하는 다른 파일을 검색합니다. 검색 핸들이 필요하지 않은 경우 FindClose 함수를 사용하여 닫아야 합니다.

앞에서 설명한 대로 FindFirstFileEx대한 lpFileName 입력 문자열에서 후행 백슬래시(\)를 사용할 수 없으므로 루트 디렉터리를 검색하는 방법은 명확하지 않을 수 있습니다. 파일을 보거나 루트 디렉터리의 특성을 얻으려면 다음 옵션이 적용됩니다.

루트 디렉터리의 파일을 검사하려면 "C:\*"를 사용하고 FindNextFile사용하여 디렉터리를 단계별로 실행할 수 있습니다.
루트 디렉터리의 특성을 얻으려면 GetFileAttributes 함수를 사용합니다.

"\\?\" 문자열 앞에 루트 디렉터리에 대한 액세스를 허용하지 않습니다.

네트워크 공유에서 lpFileName "\\server\service\*" 형식으로 사용할 수 있습니다. 그러나 공유 자체를 가리키는 lpFileName 사용할 수 없습니다. 예를 들어 "\\server\service"가 잘못되었습니다.

루트 디렉터리가 아닌 디렉터리를 검사하려면 후행 백슬래시 없이 해당 디렉터리의 경로를 사용합니다. 예를 들어 "C:\Windows"의 인수는 "C:\Windows"의 디렉터리나 파일에 대한 정보가 아니라 "C:\Windows" 디렉터리에 대한 정보를 반환합니다. "C:\Windows"에서 파일 및 디렉터리를 검사하려면 "C:\Windows\*"의 lpFileName 사용합니다.

다음 호출:

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

다음 호출과 동일합니다.

FindFirstFile( lpFileName, lpFindData );

다른 스레드 또는 프로세스에서는 결과를 쿼리하는 시간과 정보에 대해 작업하는 시간 사이에 이 이름을 가진 파일을 만들거나 삭제할 수 있습니다. 애플리케이션에 대한 잠재적인 문제인 경우 한 가지 가능한 해결 방법은 CreateFile 함수를 CREATE_NEW(파일이 있는 경우 실패) 또는 OPEN_EXISTING(파일이 없는 경우 실패)와 함께 사용하는 것입니다.

디렉터리의 모든 파일을 나열하는 32비트 애플리케이션을 작성하는 경우 애플리케이션이 64비트 컴퓨터에서 실행될 수 있습니다. FindFirstFileEx 호출하기 전에 Wow64DisableWow64FsRedirection 호출하고 FindNextFile마지막 호출 후 wow64RevertWow64FsRedirection 호출해야 합니다. 자세한 내용은 파일 시스템 리렉터참조하세요.

경로가 기호 링크를 가리키는 경우 WIN32_FIND_DATA 버퍼에는 대상이 아닌 기호 링크에 대한 정보가 포함됩니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술에서 지원됩니다.

기술	지원
SMB(서버 메시지 블록) 3.0 프로토콜	예
SMB 3.0 TFO(투명한 장애 조치(failover)	예
SO(스케일 아웃 파일 공유)가 있는 SMB 3.0	예
CsvFS(클러스터 공유 볼륨 파일 시스템)	예
ReFS(복원 파일 시스템)	예

예제

다음 코드에서는 FindFirstFileEx최소 사용을 보여 있습니다. 이 프로그램은 FindFirstFile 항목의 예제와 동일합니다.

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

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);
   }
}

메모

fileapi.h 헤더는 FINDFirstFileEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한 규칙을 참조하세요.

요구 사항

요구	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll