Fungsi KsCreateFilterFactory (ks.h)
Fungsi** KsCreateFilterFactory** menambahkan pabrik filter ke perangkat tertentu.
Sintaks
KSDDKAPI NTSTATUS KsCreateFilterFactory(
[in] PDEVICE_OBJECT DeviceObject,
[in] const KSFILTER_DESCRIPTOR *Descriptor,
[in, optional] PWSTR RefString,
[in, optional] PSECURITY_DESCRIPTOR SecurityDescriptor,
[in] ULONG CreateItemFlags,
[in, optional] PFNKSFILTERFACTORYPOWER SleepCallback,
[in, optional] PFNKSFILTERFACTORYPOWER WakeCallback,
[out, optional] PKSFILTERFACTORY *FilterFactory
);
Parameter
[in] DeviceObject
Penunjuk ke struktur DEVICE_OBJECT untuk menambahkan pabrik filter.
[in] Descriptor
Penunjuk ke KSFILTER_DESCRIPTOR yang menjelaskan karakteristik filter individual yang dapat dibuat pabrik ini.
[in, optional] RefString
Jika argumen ini disediakan, string ini digunakan sebagai string referensi untuk filter yang dibuat oleh pabrik ini. Jika tidak, GUID referensi yang disediakan dalam deskriptor digunakan.
[in, optional] SecurityDescriptor
Deskriptor keamanan yang digunakan dalam pembuatan filter oleh pabrik filter ini. Jika NULL, tidak ada deskriptor yang disediakan.
[in] CreateItemFlags
Tabel berikut mencantumkan bendera yang digunakan penulis minidriver untuk menentukan karakteristik filter yang dapat dibuat oleh pabrik filter baru. Atur parameter ini ke bitwise ATAU bendera di bawah ini.
| Bendera | Makna |
|---|---|
| KSCREATE_ITEM_SECURITY_CHANGED | Menunjukkan bahwa deskriptor keamanan pada tipe objek ini telah diubah dan harus dipertahankan. |
| KSCREATE_ITEM_WILDCARD | Menunjukkan bahwa item buat ini mewakili kartubebas yang digunakan untuk setiap permintaan pembuatan yang tidak cocok dengan item buat lainnya. Urutan entri kartubebas dalam daftar item buat tidak relevan. Hanya satu entri kartubebas yang valid pada daftar item buat apa pun. |
| KSCREATE_ITEM_NOPARAMETERS | Menunjukkan bahwa item buat ini tidak mengizinkan parameter apa pun diteruskan, dan gagal jika ada yang ditemukan. (Biasanya, buat parameter diteruskan ke handler buat.) Bendera ini tidak dapat digunakan dengan bendera kartubebas. |
| KSCREATE_ITEM_FREEONSTOP | Menunjukkan bahwa item buat harus dibebaskan saat manajer PnP mengirim IRP_MN_STOP_DEVICE. Perhatikan bahwa AVStream secara otomatis membebaskan item buat tersebut ketika perangkat menerima penghentian PnP (setelah klien menerima pemberitahuan penghentian PnP). |
[in, optional] SleepCallback
Penunjuk ke rutinitas yang disediakan minidriver yang menerima pemberitahuan bahwa perangkat yang terkait dengan filter ini akan tidur. Prototipe rutin sebagai berikut:
void SleepCallback (IN PKSFILTERFACTORY FilterFactory,
IN DEVICE_POWER_STATE State);
Jika parameter ini NULL, pabrik filter ini tidak diberi tahu bahwa perangkat akan tidur. Lihat Status Daya Perangkat.
[in, optional] WakeCallback
Penunjuk ke rutinitas yang disediakan minidriver yang menerima pemberitahuan bahwa perangkat yang terkait dengan filter ini bangun. Prototipe rutin sebagai berikut:
void WakeCallback (IN PKSFILTERFACTORY FilterFactory,
IN DEVICE_POWER_STATE State);
Jika parameter ini NULL, pabrik filter ini tidak diberi tahu bahwa perangkat sudah bangun. Lihat Status Daya Perangkat.
[out, optional] FilterFactory
Penunjuk ke struktur KSFILTERFACTORY yang diatur AVStream untuk menunjuk ke objek pabrik filter yang baru dibuat. Jika parameter opsional ini tidak ditentukan, pemanggil tidak diberi tahu tentang objek pabrik filter yang dihasilkan.
Mengembalikan nilai
Mengembalikan STATUS_SUCCESS jika pabrik filter dapat dibuat. Jika tidak, ia mengembalikan kode kesalahan yang sesuai.
Keterangan
Jika Anda memanggil KsCreateFilterFactory setelah AVStrMiniDevicePostStart), Anda kemudian harus memanggil KsFilterFactorySetDeviceClassesState untuk mengaktifkan kelas perangkat. (Juga panggil KsFilterFactorySetDeviceClassesState untuk menonaktifkan pabrik filter.)
Jika Anda memanggil KsCreateFilterFactory dalam konteks AVStrMiniDevicePostStart atau sebelumnya, Anda tidak perlu melakukan ini.
Sebelum memanggil fungsi ini, minidriver harus mendapatkan mutex perangkat. Untuk informasi tentang cara melakukannya, lihat Device Mutex di AVStream.
Fungsi ini harus digunakan oleh minidriver yang menginisialisasi dirinya sendiri tanpa panggilan ke KsInitializeDriver atau yang harus secara dinamis menambahkan dan menghapus jenis filter baru.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Tersedia di Microsoft Windows XP dan sistem operasi yang lebih baru serta DirectX 8.0 dan versi DirectX yang lebih baru. |
| Target Platform | Universal |
| Header | ks.h (termasuk Ks.h) |
| Pustaka | Ks.lib |
| IRQL | PASSIVE_LEVEL |