FindFirstFileTransactedA 함수(winbase.h)

아티클
06/02/2023

[Microsoft는 개발자가 애플리케이션의 요구 사항을 달성하기 위해 대체 수단을 활용하는 것이 좋습니다. TxF가 개발된 많은 시나리오는 더 간단하고 쉽게 사용할 수 있는 기술을 통해 달성할 수 있습니다. 또한 이후 버전의 Microsoft Windows에서는 TxF를 사용하지 못할 수도 있습니다. TxF에 대한 자세한 내용과 대안은 트랜잭션 NTFS 사용에 대한 대안을 참조하세요.]

트랜잭션 작업으로 디렉터리를 검색하여 특정 이름과 일치하는 이름을 가진 파일 또는 하위 디렉터리를 찾습니다.

이 함수는 FindFirstFileEx 함수의 트랜잭션된 형태입니다.

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

구문

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

매개 변수

[in] lpFileName

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

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

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

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

팁

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

파일은 로컬 컴퓨터에 있어야 합니다. 그렇지 않으면 함수가 실패하고 마지막 오류 코드가 ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE 설정됩니다.

[in] fInfoLevelId

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

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

[out] lpFindFileData

찾은 파일 또는 하위 디렉터리에 대한 정보를 수신하는 WIN32_FIND_DATA 구조체에 대한 포인터입니다.

[in] fSearchOp

수행할 필터링 유형으로 와일드카드 일치와 다릅니다.

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

lpSearchFilter

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

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

[in] dwAdditionalFlags

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

값	의미
FIND_FIRST_EX_CASE_SENSITIVE 1	검색은 대/소문자를 구분합니다.

[in] hTransaction

트랜잭션에 대한 핸들입니다. 이 핸들은 CreateTransaction 함수에서 반환됩니다.

반환 값

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

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

설명

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

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

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

참고 드물게 이 함수를 호출할 때 NTFS 파일 시스템에 대한 파일 정보가 최신 정보가 아닐 수 있습니다. 현재 파일 정보를 가져오려면 GetFileInformationByHandle 함수를 호출합니다.

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

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

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

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

참고 문자열 "\\?\"을 앞에 추가해도 루트 디렉터리에 대한 액세스가 허용되지 않습니다.

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

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

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

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

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

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

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	No
SMB 3.0 TFO(투명 장애 조치(failover))	No
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	No
CsvFS(클러스터 공유 볼륨 파일 시스템)	No
ReFS(Resilient File System)	No

SMB 3.0은 TxF를 지원하지 않습니다.

참고

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winbase.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll