Struktur KSIDENTIFIER (ks.h)
Struktur KSIDENTIFIER menentukan GUID yang secara unik mengidentifikasi sekumpulan GUID terkait, dan nilai indeks untuk merujuk ke anggota tertentu dalam set tersebut.
Typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM, dan KSPROPERTY adalah alias untuk struktur KSIDENTIFIER. Dengan demikian, definisinya identik. Lihat topik typedef individual untuk mengetahui secara spesifik tentang penggunaan.
Sintaks
typedef struct {
union {
struct {
GUID Set;
ULONG Id;
ULONG Flags;
} _IDENTIFIER;
struct {
GUID Set;
ULONG Id;
ULONG Flags;
};
LONGLONG Alignment;
};
} KSIDENTIFIER, *PKSIDENTIFIER;
Anggota
_IDENTIFIER
Lihat keterangan di bawah ini.
_IDENTIFIER.Set
Lihat keterangan di bawah ini.
_IDENTIFIER.Id
Lihat keterangan di bawah ini.
_IDENTIFIER.Flags
Lihat keterangan di bawah ini.
Set
Lihat keterangan di bawah ini.
Id
Lihat keterangan di bawah ini.
Flags
Lihat keterangan di bawah ini.
Alignment
Lihat keterangan di bawah ini.
Keterangan
Deskripsi anggota KSIDENTIFIER
Set
Menentukan GUID yang mengidentifikasi properti streaming kernel, peristiwa, metode, set bus komunikasi. Struktur KSPIN_INTERFACE menjelaskan antarmuka tertentu dalam set antarmuka. Struktur KSDEGRADE berisi strategi degradasi khusus. Untuk informasi selengkapnya, lihat bagian Keterangan di bawah ini.
Id
Menentukan anggota properti, peristiwa, set metode. Untuk KSPIN_MEDIUM, mengidentifikasi koneksi unik pada bus. Untuk KSPIN_INTERFACE, menentukan nomor ID antarmuka khusus ini dalam set antarmuka. Untuk KSDEGRADE, menentukan pengidentifikasi khusus set untuk item dalam set.
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.
Lihat topik typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM, dan KSPROPERTY untuk spesifik tentang penggunaan.
Menentukan jenis permintaan KSPROPERTY .
| Nilai Bendera KSPROPERTY | 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 set 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. |
Menentukan jenis permintaan KSEVENT . Bendera ini harus menjadi salah satu nilai yang tercantum dalam tabel berikut.
| Nilai Bendera KSEVENT | Deskripsi |
|---|---|
| KSEVENT_TYPE_ENABLE | Mengaktifkan pemberitahuan kejadian untuk jenis kejadian ini. Driver melanjutkan pemberitahuan peristiwa sampai klien secara eksplisit menonaktifkannya. |
| KSEVENT_TYPE_ONESHOT | Mengaktifkan pemberitahuan peristiwa untuk kejadian berikutnya dari kejadian ini saja. Klien tidak perlu (dan tidak boleh) menonaktifkan peristiwa setelah terjadi. |
| KSEVENT_TYPE_SETSUPPORT | Kueri untuk daftar set peristiwa, atau untuk dukungan set peristiwa tertentu. |
| KSEVENT_TYPE_BASICSUPPORT | Kueri untuk dukungan jenis peristiwa tertentu. |
| KSEVENT_TYPE_ENABLEBUFFERED | Alih-alih memberi tahu klien, driver mengantre pemberitahuan peristiwa. Klien kemudian mengeluarkan permintaan IOCTL_KS_ENABLE_EVENT kedua dengan KSEVENT_TYPE_QUERYBUFFER untuk menerima pemberitahuan peristiwa yang diantrekan. |
| KSEVENT_TYPE_TOPOLOGY | Menunjukkan bahwa peristiwa yang dilewatkan berjenis KSE_NODE, di mana NodeId menunjukkan ID numerik dari node topologi. Jangan atur bendera ini sendiri; sebaliknya, ATAU dengan bendera lain dari daftar ini. |
| KSEVENT_TYPE_QUERYBUFFER | Mengambil pemberitahuan peristiwa buffer berikutnya. |
Menentukan jenis permintaan KSMETHOD . Selain itu, lihat bendera KSMETHOD_TYPE_Xxx untuk KSMETHOD_ITEM. Permintaan dapat berisi kombinasi nilai yang tercantum dalam tabel berikut.
| Nilai Bendera KSMETHOD | Deskripsi |
|---|---|
| KSMETHOD_TYPE_BASICSUPPORT | Menunjukkan untuk mengkueri minidriver untuk menentukan apakah mendukung metode yang ditentukan dari set metode. |
| KSMETHOD_TYPE_SEND | Menunjukkan bahwa minidriver harus menjalankan metode yang ditentukan. Efek metode pada parameter yang diberikan harus diketahui oleh klien, yaitu, apakah parameter dibaca dari, ditulis ke, keduanya, atau tidak keduanya. Minidriver menggunakan struktur KSMETHOD_ITEM untuk menentukan efek metode pada parameter. |
| KSMETHOD_TYPE_SETSUPPORT | Menunjukkan untuk mengkueri minidriver untuk menentukan apakah mendukung kumpulan metode yang ditentukan. |
| KSMETHOD_TYPE_TOPOLOGY | Menunjukkan bahwa metode yang ditentukan berjenis KSM_NODE, di mana anggota NodeId adalah pengidentifikasi simpul topologi. Jangan atur bendera ini sendiri; sebaliknya, ATAU dengan bendera lain dari daftar ini. |
Untuk KSDEGRADE, menentukan persentase degradasi saat ini, yang dinyatakan dalam bagian per seribu (di mana nilai 1000 tidak mewakili degradasi), atau menentukan jumlah waktu dalam unit asli seperti yang ditentukan oleh antarmuka.
Alignment
Tidak digunakan. Anggota gabungan yang tidak disebutkan namanya digunakan untuk memaksa perataan yang tepat pada struktur yang tidak disebutkan namanya.
Catatan
Lihat topik typedef KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM, dan KSPROPERTY untuk spesifik tentang penggunaan.
Penggunaan ID dalam set memungkinkan seseorang untuk melakukan perbandingan besar tunggal untuk pengidentifikasi set, lalu perbandingan cepat yang lebih kecil (misalnya, dengan menggunakan pernyataan pengalih untuk pengidentifikasi dalam satu set). Misalnya, set properti disebut oleh pengidentifikasi GUID unik, dan properti dalam set tersebut disebut oleh ID pendek.
Metode, Peristiwa, Antarmuka, dan set menengah dapat dianggap sebagai "kelas" set.
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 properti streaming kernel, lihat Properti KS, Peristiwa, dan Metode.
Microsoft menyediakan beberapa GUID set peristiwa yang ditentukan sistem. Minidriver menentukan salah satu GUID ini di Atur anggota. Set peristiwa streaming kernel biasanya dimulai dengan awalan KSEVENTSETID . Set peristiwa 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.
Microsoft menyediakan beberapa GUID set metode yang ditentukan sistem. Minidriver menentukan salah satu GUID ini di Atur anggota. Set metode streaming kernel biasanya dimulai dengan awalan KSMETHODSETID . Set metode streaming kernel didefinisikan dalam ks.h, ksmedia.h, bdamedia.h, dan mungkin file header lainnya.
Untuk informasi selengkapnya tentang metode streaming kernel, lihat Properti KS, Peristiwa, dan Metode.
Klien dapat menggunakan permintaan IOCTL_KS_METHOD bersama dengan struktur KSMETHOD untuk menjalankan metode pada objek streaming kernel yang ditangani minidriver. Untuk informasi selengkapnya, lihat Metode KS.
Struktur KSPIN_MEDIUM mengidentifikasi media, dengan GUID menengah dan pengidentifikasi instans yang unik, yang dihasilkan dengan cara khusus bus. Ada nilai pengidentifikasi yang dipesan KSMEDIUM_TYPE_ANYINSTANCE yang digunakan saat instans bus tidak menjadi perhatian. Misalnya, KSMEDIUMSETID_Standard mengacu pada bus sistem, yang seharusnya hanya ada satu. Jadi pengidentifikasi instans ini selalu digunakan sebagai kenyamanan.
Pin dapat mendukung beberapa media dan antarmuka pada media tersebut. Cara di mana pin dijelaskan menyiratkan bahwa daftar antarmuka didukung pada semua media yang dijumlahkan untuk pin. Jika ada kasus di mana ini tidak benar, pin lain dapat digunakan untuk menjelaskan setiap subset antarmuka untuk media tertentu.
Media juga di-cache oleh streaming kernel untuk mempercepat pencarian untuk kemungkinan koneksi.
Contoh penggunaan struktur ini dapat ditemukan dalam sampel penyetel, di mana KSPIN_MEDIUM mewakili koneksi unik antara penyetel, crossbar, dan komponen tuner lainnya.
Anggota Bendera dapat berisi nilai yang berbeda berdasarkan jenis degradasi sinyal yang digunakan klien. Lihat Manajemen Kualitas. untuk detail lebih lanjut tentang strategi yang berbeda untuk memecahkan masalah manajemen kualitas dengan mengurangi kualitas sinyal.
Karena Bendera berisi nilai ULONG, beberapa permintaan Lewati mungkin diperlukan untuk memperbaiki masalah manajemen kualitas.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Header | ks.h (termasuk Ks.h) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk