struktur KSFILTER_DESCRIPTOR (ks.h)

Artikel
03/09/2023

Struktur KSFILTER_DESCRIPTOR menjelaskan karakteristik filter yang dibuat oleh pabrik filter tertentu.

Sintaks

typedef struct _KSFILTER_DESCRIPTOR {
  const KSFILTER_DISPATCH     *Dispatch;
  const KSAUTOMATION_TABLE    *AutomationTable;
  ULONG                       Version;
  ULONG                       Flags;
  const GUID                  *ReferenceGuid;
  ULONG                       PinDescriptorsCount;
  ULONG                       PinDescriptorSize;
  const KSPIN_DESCRIPTOR_EX   *PinDescriptors;
  ULONG                       CategoriesCount;
  const GUID                  *Categories;
  ULONG                       NodeDescriptorsCount;
  ULONG                       NodeDescriptorSize;
  const KSNODE_DESCRIPTOR     *NodeDescriptors;
  ULONG                       ConnectionsCount;
  const KSTOPOLOGY_CONNECTION *Connections;
  const KSCOMPONENTID         *ComponentId;
} KSFILTER_DESCRIPTOR, *PKSFILTER_DESCRIPTOR;

Anggota

Dispatch

Penunjuk ke struktur KSFILTER_DISPATCH untuk jenis filter ini. Anggota ini bersifat opsional dan hanya perlu disediakan oleh klien yang ingin menerima pemberitahuan tentang pembuatan filter, penghapusan, dan sebagainya. Driver yang tertarik pada pemrosesan data (transformasi) biasanya menyediakan tabel pengiriman ini dan fungsi pemrosesan. Menyediakan fungsi pemrosesan filter alih-alih fungsi pemrosesan pin individual adalah apa yang membuat driver filter-sentris alih-alih pin-sentris.

AutomationTable

Penunjuk ke struktur KSAUTOMATION_TABLE untuk jenis filter ini. Tabel otomatisasi adalah apa yang menjelaskan properti, metode, dan peristiwa yang didukung oleh filter ini. Tabel otomatisasi ini digabungkan dengan tabel otomatisasi yang disediakan oleh AVStream untuk semua filter. Jika klien menyediakan properti, metode, atau penanganan aktivitas yang sudah diterapkan oleh AVStream, implementasi klien menggantikan AVStream.

Version

Anggota ini menentukan versi deskriptor filter. Anggota ini harus diatur ke KSFILTER_DESCRIPTOR_VERSION.

Flags

Bendera yang menjelaskan perilaku filter. Tentukan bendera menggunakan OR bitwise, dengan pengecualian KSFILTER_FLAG_CRITICAL_PROCESSING dan KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, yang saling eksklusif:

Bendera	Deskripsi
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Menunjukkan bahwa filter memproses di IRQL DISPATCH_LEVEL dibandingkan dengan PASSIVE_LEVEL. Ini berlaku untuk panggilan balik proses filter seperti yang dijelaskan dalam KSFILTER_DISPATCH.
KSFILTER_FLAG_CRITICAL_PROCESSING	Jika pemrosesan asinkron telah ditentukan atau jika sistem berjalan pada PASSIVE_LEVEL dan panggilan proses masuk pada DISPATCH_LEVEL, pemrosesan dilakukan dalam item kerja yang diantrekan. Bendera ini menunjukkan bahwa item kerja harus ditempatkan pada antrean kerja penting dibandingkan dengan antrean kerja yang tertunda.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Atur bendera ini jika filter yang bersentris filter perlu menerima sampel panjang nol (header stream dengan bendera tetapi tidak ada data). Jika bendera ini tidak diatur, sampel panjang nol diteruskan ke pin hilir, dengan penyebaran otomatis bendera yang diperlukan. Perhatikan bahwa ini identik dengan perilaku default di DX8 dan sebelumnya. Jika ini terjadi, sampel ini melewati minidriver. Atur bendera Hentikan di KSPROCESSPIN untuk "mematikan" bendera ini. Lihat juga Pemrosesan Filter-Sentris.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Bendera ini mencegah akses mode pengguna ke filter tertentu dan semua pin yang dibuat pada filter ini.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Jika pemrosesan asinkron telah ditentukan atau jika sistem berjalan pada PASSIVE_LEVEL dan panggilan proses masuk pada DISPATCH_LEVEL, AVStream memproses item kerja yang diantrekan. Bendera ini menunjukkan bahwa item kerja harus ditempatkan pada antrean kerja hiperkritik dibandingkan dengan antrean kerja yang tertunda atau antrean kerja penting.

ReferenceGuid

Penunjuk ke GUID yang merupakan representasi biner dari string referensi Unicode yang mengidentifikasi jenis filter ini. Jika ada beberapa pabrik filter, masing-masing harus memiliki GUID yang unik. Perhatikan juga bahwa metode lain untuk menyediakan string referensi mengharuskan deskriptor filter didaftarkan menggunakan KsCreateFilterFactory. Nilai yang ditentukan dalam ReferenceGuid harus cocok dengan GUID referensi khusus filter dalam file INF driver. Lihat Menginisialisasi AVStream Minidriver.

PinDescriptorsCount

Anggota ini menentukan jumlah deskriptor pin yang disediakan untuk jenis filter ini di anggota PinDescriptors . Pada Windows XP dan yang lebih baru, PinDescriptorsCount mungkin nol jika driver membuat pin secara dinamis.

PinDescriptorSize

Anggota ini menentukan ukuran setiap deskriptor individu dalam tabel deskriptor. Nilai ini harus kelipatan delapan dan harus setidaknya ukuranof (KSPIN_DESCRIPTOR_EX). Nilai yang lebih besar memungkinkan informasi deskriptor khusus klien ditambahkan ke deskriptor pin. Lihat informasi tambahan di Keterangan.

PinDescriptors

Penunjuk ke array struktur KSPIN_DESCRIPTOR_EX yang menjelaskan pin yang didukung oleh jenis filter ini. Jika PinDescriptorsCount adalah nol, atur anggota ini ke NULL..

CategoriesCount

Anggota ini menentukan jumlah GUID kategori yang disediakan dalam anggota Kategori untuk jenis filter ini. Nol adalah nilai hukum untuk anggota ini.

Categories

Penunjuk ke array GUID kategori untuk jenis filter ini. Jika diperlukan, antarmuka perangkat terdaftar untuk setiap kategori. Anggota ini mungkin null jika dan hanya jika CategoriesCount adalah nol.

NodeDescriptorsCount

Anggota ini menentukan jumlah deskriptor simpul topologi yang disediakan dalam NodeDescriptors. Nol adalah nilai hukum untuk anggota ini.

NodeDescriptorSize

Anggota ini menentukan ukuran dalam byte dari setiap deskriptor individu dalam tabel deskriptor. Nilai ini harus kelipatan delapan dan setidaknya sizeof(KSNODE_DESCRIPTOR). Nilai yang lebih besar memungkinkan informasi deskriptor khusus klien ditambahkan ke deskriptor simpul. Lihat informasi tambahan di Keterangan.

NodeDescriptors

Penunjuk ke array struktur KSNODE_DESCRIPTOR yang menjelaskan node topologi untuk jenis filter ini. Anggota ini mungkin null jika dan hanya jika NodeDescriptorsCount adalah nol.

ConnectionsCount

Anggota ini menentukan jumlah koneksi topologi yang ada di Connections. Anggota ini mungkin nol yang menunjukkan bahwa set koneksi default digunakan. Menggunakan koneksi default berarti bahwa topologi filter dijelaskan dengan satu simpul topologi di mana setiap pin pada filter terhubung ke ID yang sesuai pada simpul topologi. Arah setiap koneksi ditentukan oleh aliran data pin.

Connections

Penunjuk ke array struktur KSTOPOLOGY_CONNECTION ada dalam jenis filter ini. Anggota ini bersifat opsional; mungkin NULL jika dan hanya jika ConnectionsCount adalah nol (dalam hal ini, topologi default digunakan).

ComponentId

Penunjuk ke struktur KSCOMPONENTID untuk jenis filter ini. Ini digunakan untuk properti ID komponen yang menyediakan informasi identifikasi. Anggota ini bersifat opsional.

Keterangan

Dalam menjabarkan deskriptor filter, ada sejumlah makro yang mungkin berguna bagi pemanggil. Alih-alih menentukan jumlah, ukuran, dan tabel untuk deskriptor pin, kategori, deskriptor simpul, dan koneksi, ada sejumlah makro yang berguna:

Makro	Deskripsi
DEFINE_KSFILTER_PIN_DESCRIPTORS(Table)	Secara otomatis menyisipkan jumlah item dalam tabel, ukuran setiap item dalam tabel, dan tabel deskriptor pin itu sendiri ke dalam deskriptor filter.
DEFINE_KSFILTER_CATEGORIES(Table)	Secara otomatis menyisipkan jumlah kategori dalam tabel dan tabel itu sendiri ke dalam deskriptor filter.
DEFINE_KSFILTER_CATEGORIES_NULL	Secara otomatis mengisi anggota kategori untuk filter yang tidak menentukan kategori.
DEFINE_KSFILTER_NODE_DESCRIPTORS(Table)	Secara otomatis menyisipkan jumlah item dalam tabel, ukuran setiap item dalam tabel, dan tabel deskriptor simpul itu sendiri ke dalam deskriptor filter.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Secara otomatis mengisi anggota deskriptor simpul untuk filter yang tidak menentukan node topologi.
DEFINE_KSFILTER_CONNECTIONS(Table)	Secara otomatis menyisipkan jumlah koneksi dalam tabel dan tabel itu sendiri ke dalam deskriptor filter.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Secara otomatis mengisi tabel koneksi untuk filter yang tidak menentukan koneksi eksplisit.

Jika Anda tidak menggunakan DEFINE_KS_FILTER_PIN_DESCRIPTORS untuk mengatur PinDescriptorSize, maka Anda harus mengatur PinDescriptorSize ke sizeof(KSPIN_DESCRIPTOR_EX).

Demikian pula, jika Anda tidak menggunakan DEFINE_KS_FILTER_NODE_DESCRIPTORS untuk mengatur NodeDescriptorSize, maka Anda harus mengatur NodeDescriptorSize ke sizeof(KSNODE_DESCRIPTOR).