Fungsi FilterInstanceFindFirst (fltuser.h)

Artikel
08/23/2023

Fungsi FilterInstanceFindFirst mengembalikan informasi tentang instans driver minifilter dan digunakan sebagai titik awal untuk memindai instans minifilter.

Sintaks

HRESULT FilterInstanceFindFirst(
  [in]  LPCWSTR                    lpFilterName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpFilterInstanceFind
);

Parameter

[in] lpFilterName

Penunjuk ke string karakter lebar yang dihentikan null yang berisi nama driver minifilter yang memiliki instans.

[in] dwInformationClass

Jenis struktur informasi instans dikembalikan. Parameter ini harus menjadi salah satu nilai berikut.

Nilai	Makna
InstanceBasicInformation	Mengembalikan struktur INSTANCE_BASIC_INFORMATION untuk instans.
InstanceFullInformation	Mengembalikan struktur INSTANCE_FULL_INFORMATION untuk instans.
InstancePartialInformation	Mengembalikan struktur INSTANCE_PARTIAL_INFORMATION untuk instans.
InstanceAggregateStandardInformation	Mengembalikan struktur INSTANCE_AGGREGATE_STANDARD_INFORMATION untuk instans. Bagian LegacyFilter dari 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 FilterInstanceFindFirst berhasil. Parameter ini diperlukan dan tidak boleh NULL.

[out] lpFilterInstanceFind

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel pencarian untuk minifilter jika panggilan ke FilterInstanceFindFirst berhasil; jika tidak, ia menerima INVALID_HANDLE_VALUE. Handel pencarian ini dapat digunakan dalam panggilan berikutnya ke FilterInstanceFindNext dan FilterInstanceFindClose.

Nilai kembali

FilterInstanceFindFirst 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, fungsi mengembalikan nilai HRESULT ini.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Minifilter yang ditentukan oleh parameter lpFilterName tidak memiliki instans pada tumpukan sistem file.

Keterangan

Fungsi FilterInstanceFindFirst membuka handel pencarian dan mengembalikan informasi tentang instans untuk minifilter yang dinamai oleh lpFilterName. Setelah handel pencarian dibuat, panggil FilterInstanceFindNext untuk mencari instans lain dari minifilter yang sama. Ketika handel pencarian tidak lagi diperlukan, tutup dengan memanggil FilterInstanceFindClose.