Fungsi FilterFindFirst (fltuser.h)

Artikel
08/23/2023

Fungsi FilterFindFirst mengembalikan informasi tentang driver filter (instans driver minifilter atau driver filter warisan) dan digunakan untuk mulai memindai filter dalam daftar global filter terdaftar.

Sintaks

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

Parameter

[in] dwInformationClass

Jenis informasi pengandar filter yang diminta. Parameter ini harus menjadi salah satu nilai berikut.

Nilai	Makna
FilterFullInformation	Buffer yang ditujukkan oleh parameter lpBuffer menerima struktur FILTER_FULL_INFORMATION untuk setiap instans minifilter. Filter warisan diabaikan.
FilterAggregateBasicInformation	Buffer yang ditujukkan oleh parameter lpBuffer menerima struktur FILTER_AGGREGATE_BASIC_INFORMATION untuk setiap instans minifilter atau filter warisan. Nilai dwInformationClass ini tersedia dimulai dengan Windows Server 2003 dengan SP1 dan Windows XP dengan SP2 dengan rollup manajer filter. Untuk informasi selengkapnya tentang paket rollup manajer filter untuk Windows XP dengan SP2, lihat artikel 914882, " Paket rollup manajer filter untuk Windows XP SP2," di Pangkalan Pengetahuan Microsoft.
FilterAggregateStandardInformation	Buffer yang ditujukkan oleh parameter lpBuffer menerima struktur FILTER_AGGREGATE_STANDARD_INFORMATION untuk setiap instans minifilter atau filter warisan. Nilai dwInformationClass 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 dituju lpBuffer jika panggilan ke FilterFindFirst berhasil. Parameter ini diperlukan dan tidak boleh NULL.

[out] lpFilterFind

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel pencarian untuk driver filter jika panggilan ke FilterFindFirst berhasil; jika tidak, ia menerima INVALID_HANDLE_VALUE. Handel pencarian ini dapat digunakan dalam panggilan berikutnya ke FilterFindNext dan FilterFindClose.

Nilai kembali

FilterFindFirst 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 ditujukkan 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 FilterAggregateStandardInformation ditentukan untuk sistem operasi sebelum Windows Vista, FilterFindFirst mengembalikan nilai HRESULT ini.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Pengandar filter tidak ditemukan dalam daftar global filter terdaftar.

Keterangan

Fungsi FilterFindFirst membuka handel pencarian dan mengembalikan informasi tentang driver filter pertama yang ditemukan dalam daftar global filter terdaftar. Setelah handel pencarian dibuat, panggil fungsi FilterFindNext untuk mencari filter lain dalam daftar global. Ketika handel pencarian tidak lagi diperlukan, tutup dengan memanggil FilterFindClose.

Dimulai dengan Microsoft Windows Server 2003 dengan SP1 dan Windows XP dengan Paket Layanan 1 (SP1) dengan rollup manajer filter, FilterFindFirst dan FilterFindNext dapat memberikan informasi driver filter lama dan informasi instans driver minifilter. Pada versi Windows yang lebih lama, FilterFindFirst dan FilterFindNext hanya dapat memberikan informasi tentang minifilter (lihat deskripsi untuk parameter dwInformationClass di atas).

FilterFindFirst dan FilterFindNext mengembalikan informasi tentang driver filter dalam urutan penurunan jarak dari sistem file dasar. Informasi tentang filter terjauh dari sistem file dasar dikembalikan terlebih dahulu. Informasi tentang filter terjauh kedua dikembalikan kedua. Informasi tentang filter yang paling dekat dengan sistem file dasar dikembalikan terakhir.

Jika input dwBufferSize terlalu kecil, lpFilterFind menerima INVALID_HANDLE_VALUE, dan lpBytesReturned menerima jumlah byte yang diperlukan untuk menyimpan informasi yang diminta.