Struktur KSPROPERTY

Artikel
06/15/2023

Struktur KSPROPERTY menentukan satu properti streaming kernel dalam kumpulan properti.

Struktur KSEVENT, KSMETHOD, dan KSPROPERTY adalah alias untuk struktur KSIDENTIFIER . Dengan demikian, definisinya identik.

Sintaks

struct KSPROPERTY {
  GUID Set;
  ULONG Id;
  ULONG Flags;
};

Anggota

Set

Menentukan GUID yang mengidentifikasi kumpulan properti streaming kernel. Untuk informasi selengkapnya tentang GUID set properti, lihat bagian Keterangan di bawah ini.

Id

Menentukan anggota set properti.

Flags

Menentukan jenis permintaan. Jika Anda menulis minidriver kelas stream, lihat juga KSPROPERTY_ITEM untuk informasi bendera khusus kelas.

Bendera harus menjadi salah satu nilai yang tercantum dalam tabel berikut. Beberapa bendera dapat digabungkan menggunakan operasi OR bitwise.

Nilai	Deskripsi
KSPROPERTY_TYPE_GET	Mengambil nilai item properti yang ditentukan.
KSPROPERTY_TYPE_SET	Mengatur nilai item properti yang ditentukan.
KSPROPERTY_TYPE_SETSUPPORT	Kueri jika driver mendukung set properti ini.
KSPROPERTY_TYPE_BASICSUPPORT	Mengkueri tipe permintaan yang ditangani driver untuk item properti ini. Mengembalikan KSPROPERTY_TYPE_GET atau KSPROPERTY_TYPE_SET atau keduanya. Semua set properti harus mendukung bendera ini.
KSPROPERTY_TYPE_DEFAULTVALUES	Mengkueri nilai default untuk item properti yang ditentukan. Mengembalikan struktur jenis KSPROPERTY_VALUES.
KSPROPERTY_TYPE_RELATIONS	Mengkueri semua properti dengan dependensi pada pengaturan properti ini saat ini. Menentukan bahwa daftar relasi properti akan dikembalikan, atau jumlah ruang buffer yang diperlukan oleh daftar tersebut jika buffer pengembalian adalah ukuran ULONG. Setiap elemen berada di FILE_QUAD_ALIGNMENT, didahului oleh struktur KSMULTIPLE_ITEM . Ini tidak valid saat mengkueri dukungan properti yang diatur secara umum. Semua set properti harus mendukung bendera ini.
KSPROPERTY_TYPE_SERIALIZESET	Serialisasi kumpulan properti, menggunakan KSPROPERTY_SERIALHDR standar dan struktur KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_UNSERIALIZESET	Batalkan serialisasi kumpulan properti, menggunakan KSPROPERTY_SERIALHDR standar dan struktur KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE	Mengembalikan ULONG yang menentukan ukuran data properti saat diserialisasikan sebagai bagian dari permintaan KSPROPERTY_TYPE_SERIALIZESET . Ukuran nol menunjukkan bahwa properti tidak perlu diserialisasikan.
KSPROPERTY_TYPE_SERIALIZERAW	Menentukan bahwa properti dalam set ini harus diserialisasikan oleh penangan dukungan set properti, jika ada. Jika tidak, panggilan gagal. Format serialisasi bersifat privat. Operasi ini harus menjadi inversi dari KSPROPERTY_TYPE_UNSERIALIZERAW.
KSPROPERTY_TYPE_TOPOLOGY	Properti yang diteruskan berjenis KSP_NODE, di mana NodeId menunjukkan ID numerik dari node topologi. Jangan atur bendera ini sendiri; sebaliknya, ATAU dengan bendera lain dalam tabel ini.
KSPROPERTY_TYPE_UNSERIALIZERAW	Menentukan bahwa buffer yang disediakan berisi sekelompok properti milik set ini yang harus tidak diserialisasi oleh handler dukungan kumpulan properti, jika ada. Jika tidak, panggilan gagal. Format serialisasi bersifat privat. Operasi ini harus menjadi inversi dari KSPROPERTY_TYPE_SERIALIZERAW.

Keterangan

Ukuran buffer output yang dilewatkan menentukan data apa yang dikembalikan dari permintaan KSPROPERTY_TYPE_BASICSUPPORT. Jika buffer output adalah ukuran ULONG, hanya bendera akses yang dikembalikan. Jika buffer output adalah ukuran struktur KSPROPERTY_DESCRIPTION , struktur diisi dengan bendera akses, ukuran inklusif dari seluruh informasi nilai, informasi jenis nilai properti, dan jumlah daftar anggota yang sesuai dengan struktur.

Untuk permintaan KSPROPERTY_TYPE_RELATIONS, data yang dikembalikan juga tergantung pada ukuran buffer output. Jika ukuran buffer output adalah nol, ukuran yang diperlukan untuk mengembalikan properti terkait dikembalikan dalam BytesReturned dengan status peringatan STATUS_BUFFER_OVERFLOW. Jika buffer adalah ukuran struktur KSMULTIPLE_ITEM , ukuran byte dan jumlah relasi dikembalikan. Jika tidak, buffer diperkirakan akan cukup lama untuk mengembalikan struktur KSMULTIPLE_ITEM dan semua pengidentifikasi properti terkait, yang dikembalikan sebagai daftar struktur KSIDENTIFIER .

KSPROPERTY_TYPE_SERIALIZESET dan permintaan KSPROPERTY_TYPE_UNSERIALIZESET memungkinkan interaksi dengan beberapa properti dengan satu panggilan dari klien. Jika handler streaming kernel digunakan untuk memproses permintaan properti, ini dipecah menjadi beberapa panggilan oleh fungsi KsPropertyHandler . Saat menggunakan handler ini, definisi set properti mengontrol properti mana yang akan diserialisasikan.

Untuk permintaan serialisasi, anggota SerializedSize dari struktur KSPROPERTY_ITEM yang relevan diperiksa untuk nilai bukan nol yang menunjukkan ukuran, dalam byte, dari properti . Jika nilai anggota SerializedSize adalah 1, itu tidak diketahui dan harus dikueri (semua properti yang tidak diketahui dimulai dengan struktur KSMULTIPLE_ITEM yang dapat dikueri secara terpisah). Untuk mengkueri ukuran total yang akan diambil serialisasi, klien melewati buffer panjang nol dalam panggilan ke DeviceIoControl. BytesReturned kemudian mengembalikan ukuran, dalam byte, bahwa buffer harus menserialisasikan set, dan status peringatan STATUS_BUFFER_OVERFLOW. Buffer yang dialokasikan ukuran tersebut kemudian dapat diisi dengan data serial.

Format buffer serialisasi adalah KSPROPERTY_SERIALHDR, diikuti oleh properti berseri. Setiap properti yang mengikuti berisi header (KSPROPERTY_SERIAL), diikuti oleh data properti, dengan awal setiap properti pada FILE_LONG_ALIGNMENT. Perhatikan bahwa struktur header serial didefinisikan berada di FILE_LONG_ALIGNMENT.

KSPROPERTY_TYPE_SERIALIZERAW dan KSPROPERTY_TYPE_UNSERIALIZERAW didukung jika ada penangan item properti. Fungsi KsPropertyHandler memanggil handler yang disediakan oleh minidriver. Ukuran buffer yang diperlukan untuk serialisasi juga dapat dikueri dengan meneruskan buffer panjang nol ke permintaan mentah serialisasi. Karena handler dilampirkan ke item properti daripada kumpulan properti, item tertentu dalam kumpulan properti harus ditentukan dalam parameter Properti . Handler ini dapat menangani beberapa properti dalam set.

Microsoft menyediakan beberapa GUID set properti yang ditentukan sistem. Minidriver menentukan salah satu GUID ini di Atur anggota. Set properti streaming kernel biasanya dimulai dengan KSPROPSETID atau awalan PROPSETID . Set properti streaming kernel didefinisikan dalam ks.h, ksmedia.h, bdamedia.h, dan mungkin file header lainnya.

Untuk informasi selengkapnya tentang peristiwa streaming kernel, lihat Properti KS, Peristiwa, dan Metode.