Fungsi FilterVolumeInstanceFindFirst (fltuser.h)

Artikel
08/23/2023

Fungsi FilterVolumeInstanceFindFirst mengembalikan informasi tentang instans driver minifilter atau driver filter warisan dan digunakan untuk mulai memindai driver filter yang melekat pada volume.

Sintaks

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

Parameter

[in] lpVolumeName

Penunjuk ke string karakter lebar yang dihentikan null yang berisi nama volume tempat instans minifilter atau filter warisan dilampirkan.

String input lpVolumeName dapat berupa salah satu dari berikut ini. Garis miring terbelakang (\) bersifat opsional.

Huruf kandar, seperti D:\
Jalur ke titik pemasangan volume, seperti c:\mnt\edrive\
Pengidentifikasi volume unik (juga disebut nama GUID volume), seperti \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Nama perangkat yang tidak konsisten (juga disebut nama target atau nama perangkat NT), seperti \Device\HarddiskVolume1\

[in] dwInformationClass

Jenis struktur informasi driver filter dikembalikan. Parameter ini harus berisi salah satu nilai berikut.

Nilai	Makna
InstanceBasicInformation	Mengembalikan struktur INSTANCE_BASIC_INFORMATION untuk instans minifilter. Driver filter warisan diabaikan.
InstanceFullInformation	Mengembalikan struktur INSTANCE_FULL_INFORMATION untuk instans minifilter. Driver filter warisan diabaikan.
InstancePartialInformation	Mengembalikan struktur INSTANCE_PARTIAL_INFORMATION untuk instans minifilter. Driver filter warisan diabaikan.
InstanceAggregateStandardInformation	Mengembalikan struktur INSTANCE_AGGREGATE_STANDARD_INFORMATION untuk instans. Anggota LegacyFilter struktur tidak digunakan. Struktur ini tersedia dimulai dengan Windows Vista.

[out] lpBuffer

Arahkan ke buffer yang dialokasikan penelepon yang menerima informasi yang diminta. Jenis informasi yang dikembalikan dalam buffer ditentukan oleh parameter dwInformationClass .

[in] dwBufferSize

Ukuran, dalam byte, dari buffer yang dirujuk parameter lpBuffer . Pemanggil harus mengatur parameter ini sesuai dengan dwInformationClass yang diberikan.

[out] lpBytesReturned

Penunjuk ke variabel yang dialokasikan penelepon yang menerima jumlah byte yang dikembalikan dalam buffer yang ditunjuk lpBuffer jika panggilan ke FilterVolumeInstanceFindFirst berhasil. Parameter ini diperlukan dan tidak boleh NULL.

[out] lpVolumeInstanceFind

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel pencarian untuk instans minifilter atau filter warisan (hanya ketika InstanceAggregateStandardInformation ditentukan) jika panggilan ke FilterVolumeInstanceFindFirst berhasil. Jika tidak, lpVolumeInstanceFind menerima INVALID_HANDLE_VALUE. Handel pencarian ini dapat digunakan dalam panggilan berikutnya ke FilterVolumeInstanceFindNext dan FilterVolumeInstanceFindClose.

Nilai kembali

FilterVolumeInstanceFindFirst mengembalikan S_OK jika berhasil. Jika tidak, ia mengembalikan nilai kesalahan HRESULT, seperti salah satu hal berikut ini:

Menampilkan kode	Deskripsi
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Buffer yang diacu oleh lpBuffer tidak cukup besar untuk berisi informasi yang diminta. Ketika nilai ini dikembalikan, lpBytesReturned akan berisi ukuran, dalam byte, dari buffer yang diperlukan untuk struktur dwInformationClass yang diberikan.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	Nilai yang tidak valid ditentukan untuk parameter dwInformationClass . Misalnya, jika InstanceAggregateStandardInformation ditentukan untuk sistem operasi sebelum Windows Vista, FilterVolumeInstanceFindFirst mengembalikan nilai HRESULT ini.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Pengandar filter tidak ditemukan pada volume yang diberikan.

Keterangan

Fungsi FilterVolumeInstanceFindFirst membuka handel pencarian dan mengembalikan informasi tentang driver filter pertama yang ditemukan yang dilampirkan ke volume bernama lpVolumeName. Setelah handel pencarian dibuat, panggil FilterVolumeInstanceFindNext untuk mencari driver filter lain yang dilampirkan ke volume yang sama. Ketika handel pencarian tidak lagi diperlukan, tutup dengan memanggil FilterVolumeInstanceFindClose.

Dimulai dengan Windows Vista, FilterVolumeInstanceFindFirst dapat mengembalikan informasi driver filter warisan dan informasi instans driver minifilter ketika nilai parameter dwInformationClass adalah InstanceAggregateStandardInformation. Untuk sistem operasi sebelumnya, fungsi ini tidak dapat mengembalikan informasi filter warisan karena struktur INSTANCE_AGGREGATE_STANDARD_INFORMATION tidak tersedia.