FilterVolumeInstanceFindFirst 함수(fltuser.h)

아티클
08/23/2023

FilterVolumeInstanceFindFirst 함수는 미니필터 드라이버 instance 또는 레거시 필터 드라이버에 대한 정보를 반환하며 볼륨에 연결된 필터 드라이버 검사를 시작하는 데 사용됩니다.

구문

HRESULT FilterVolumeInstanceFindFirst(
  [in]  LPCWSTR                    lpVolumeName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpVolumeInstanceFind
);

매개 변수

[in] lpVolumeName

미니필터 instance 또는 레거시 필터가 연결된 볼륨의 이름을 포함하는 null로 끝나는 와이드 문자열에 대한 포인터입니다.

lpVolumeName 입력 문자열은 다음 중 한 개일 수 있습니다. 후행 백슬래시(\)는 선택 사항입니다.

드라이브 문자(예: D:\
볼륨 탑재 지점의 경로(예: c:\mnt\edrive\
고유한 볼륨 식별자( 볼륨 GUID 이름이라고도 함)(예: \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
존재하지 않는 디바이스 이름( 대상 이름 또는 NT 디바이스 이름이라고도 함)(예: \Device\HarddiskVolume1\

[in] dwInformationClass

반환된 필터 드라이버 정보 구조의 형식입니다. 이 매개 변수는 다음 값 중 하나를 포함해야 합니다.

값	의미
InstanceBasicInformation	미니필터 instance 대한 INSTANCE_BASIC_INFORMATION 구조를 반환합니다. 레거시 필터 드라이버는 무시됩니다.
InstanceFullInformation	미니필터 instance 대한 INSTANCE_FULL_INFORMATION 구조를 반환합니다. 레거시 필터 드라이버는 무시됩니다.
InstancePartialInformation	미니필터 instance 대한 INSTANCE_PARTIAL_INFORMATION 구조를 반환합니다. 레거시 필터 드라이버는 무시됩니다.
InstanceAggregateStandardInformation	instance 대한 INSTANCE_AGGREGATE_STANDARD_INFORMATION 구조를 반환합니다. 구조체의 LegacyFilter 멤버가 사용되지 않습니다. 이 구조는 Windows Vista부터 사용할 수 있습니다.

[out] lpBuffer

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

[in] dwBufferSize

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

[out] lpBytesReturned

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

[out] lpVolumeInstanceFind

FilterVolumeInstanceFindFirst에 대한 호출이 성공하는 경우 미니 필터 instance 또는 레거시 필터에 대한 검색 핸들을 수신하는 호출자 할당 변수에 대한 포인터입니다(InstanceAggregateStandardInformation이 지정된 경우에만). 그렇지 않으면 lpVolumeInstanceFind 는 INVALID_HANDLE_VALUE 받습니다. 이 검색 핸들은 FilterVolumeInstanceFindNext 및 FilterVolumeInstanceFindClose에 대한 후속 호출에서 사용할 수 있습니다.

반환 값

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

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

설명

FilterVolumeInstanceFindFirst 함수는 검색 핸들을 열고 lpVolumeName으로 명명된 볼륨에 연결된 첫 번째 필터 드라이버에 대한 정보를 반환합니다. 검색 핸들이 설정되면 FilterVolumeInstanceFindNext 를 호출하여 동일한 볼륨에 연결된 다른 필터 드라이버를 검색합니다. 검색 핸들이 더 이상 필요하지 않으면 FilterVolumeInstanceFindClose를 호출하여 닫습니다.

Windows Vista부터 FilterVolumeInstanceFindFirst는 dwInformationClass 매개 변수의 값이 InstanceAggregateStandardInformation인 경우 레거시 필터 드라이버 정보와 미니필터 드라이버 instance 정보를 모두 반환할 수 있습니다. 이전 운영 체제의 경우 INSTANCE_AGGREGATE_STANDARD_INFORMATION 구조를 사용할 수 없으므로 이 함수는 레거시 필터 정보를 반환할 수 없습니다.