FilterFindFirst 함수(fltuser.h)

아티클
08/23/2023

FilterFindFirst 함수는 필터 드라이버(미니필터 드라이버 instance 또는 레거시 필터 드라이버)에 대한 정보를 반환하고 등록된 필터의 전역 목록에서 필터 검사를 시작하는 데 사용됩니다.

구문

HRESULT FilterFindFirst(
  [in]  FILTER_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                   lpBuffer,
  [in]  DWORD                    dwBufferSize,
  [out] LPDWORD                  lpBytesReturned,
  [out] LPHANDLE                 lpFilterFind
);

매개 변수

[in] dwInformationClass

요청된 필터 드라이버 정보의 유형입니다. 이 매개 변수는 다음 값 중 하나여야 합니다.

값	의미
FilterFullInformation	lpBuffer 매개 변수가 가리키는 버퍼는 각 미니필터 instance 대한 FILTER_FULL_INFORMATION 구조를 받습니다. 레거시 필터는 무시됩니다.
FilterAggregateBasicInformation	lpBuffer 매개 변수가 가리키는 버퍼는 각 미니필터 instance 또는 레거시 필터에 대한 FILTER_AGGREGATE_BASIC_INFORMATION 구조를 받습니다. 이 dwInformationClass 값은 Windows Server 2003 SP1 및 Windows XP SP2 및 필터 관리자 롤업부터 사용할 수 있습니다. SP2를 사용하는 Windows XP용 필터 관리자 롤업 패키지에 대한 자세한 내용은 Microsoft 기술 자료의 " Windows XP SP2용 필터 관리자 롤업 패키지" 914882 문서를 참조하세요.
FilterAggregateStandardInformation	lpBuffer 매개 변수가 가리키는 버퍼는 각 미니필터 instance 또는 레거시 필터에 대한 FILTER_AGGREGATE_STANDARD_INFORMATION 구조를 받습니다. 이 dwInformationClass 값은 Windows Vista부터 사용할 수 있습니다.

[out] lpBuffer

요청된 정보를 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다. 버퍼에서 반환되는 정보의 형식은 dwInformationClass 매개 변수에 의해 정의됩니다.

[in] dwBufferSize

lpBuffer 매개 변수가 가리키는 버퍼의 크기(바이트)입니다. 호출자는 지정된 dwInformationClass에 따라 이 매개 변수를 설정해야 합니다.

[out] lpBytesReturned

FilterFindFirst 호출이 성공하면 lpBuffer가 가리키는 버퍼에 반환된 바이트 수를 수신하는 호출자 할당 변수에 대한 포인터입니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

[out] lpFilterFind

FilterFindFirst에 대한 호출이 성공하는 경우 필터 드라이버에 대한 검색 핸들을 수신하는 호출자가 할당한 변수에 대한 포인터입니다. 그렇지 않으면 INVALID_HANDLE_VALUE 받습니다. 이 검색 핸들은 FilterFindNext 및 FilterFindClose에 대한 후속 호출에서 사용할 수 있습니다.

반환 값

FilterFindFirst 는 성공하면 S_OK 반환합니다. 그렇지 않으면 다음 중 하나와 같은 HRESULT 오류 값이 반환됩니다.

반환 코드	설명
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	lpBuffer가 가리키는 버퍼가 요청된 정보를 포함할 만큼 크지 않습니다. 이 값이 반환되면 lpBytesReturned 에는 지정된 dwInformationClass 구조에 필요한 버퍼의 크기(바이트)가 포함됩니다.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	dwInformationClass 매개 변수에 대해 잘못된 값이 지정되었습니다. 예를 들어 Windows Vista 이전의 운영 체제에 대해 FilterAggregateStandardInformation 이 지정된 경우 FilterFindFirst 는 이 HRESULT 값을 반환합니다.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	등록된 필터의 전역 목록에서 필터 드라이버를 찾을 수 없습니다.

설명

FilterFindFirst 함수는 검색 핸들을 열고 등록된 필터의 전역 목록에 있는 첫 번째 필터 드라이버에 대한 정보를 반환합니다. 검색 핸들이 설정되면 FilterFindNext 함수를 호출하여 전역 목록에서 다른 필터를 검색합니다. 검색 핸들이 더 이상 필요하지 않으면 FilterFindClose를 호출하여 닫습니다.

필터 관리자 롤업이 포함된 MICROSOFT Windows Server 2003 SP1 및 WINDOWS XP SP1(서비스 팩 1)부터 FilterFindFirst 및 FilterFindNext는 레거시 필터 드라이버 정보 및 미니필터 드라이버 instance 정보를 제공할 수 있습니다. 이전 버전의 Windows에서 FilterFindFirst 및 FilterFindNext 는 미니 필터에 대한 정보만 제공할 수 있습니다(위의 dwInformationClass 매개 변수에 대한 설명 참조).

FilterFindFirst 및 FilterFindNext 는 기본 파일 시스템에서 거리를 줄이는 순서대로 필터 드라이버에 대한 정보를 반환합니다. 기본 파일 시스템에서 가장 멀리 떨어진 필터에 대한 정보가 먼저 반환됩니다. 두 번째로 먼 필터에 대한 정보가 두 번째로 반환됩니다. 기본 파일 시스템에 가장 가까운 필터에 대한 정보가 마지막으로 반환됩니다.

입력 dwBufferSize 가 너무 작으면 lpFilterFind 는 INVALID_HANDLE_VALUE 수신하고 lpBytesReturned 은 요청된 정보를 저장하는 데 필요한 바이트 수를 받습니다.