struktur KSPROPERTY_ITEM (ks.h)

Artikel
03/09/2023

Driver menggunakan struktur KSPROPERTY_ITEM untuk menjelaskan bagaimana mereka mendukung properti dalam kumpulan properti.

Sintaks

typedef struct {
  ULONG                   PropertyId;
  union {
    PFNKSHANDLER GetPropertyHandler;
    BOOLEAN      GetSupported;
  };
  ULONG                   MinProperty;
  ULONG                   MinData;
  union {
    PFNKSHANDLER SetPropertyHandler;
    BOOLEAN      SetSupported;
  };
  const KSPROPERTY_VALUES *Values;
  ULONG                   RelationsCount;
  const KSPROPERTY        *Relations;
  PFNKSHANDLER            SupportHandler;
  ULONG                   SerializedSize;
} KSPROPERTY_ITEM, *PKSPROPERTY_ITEM;

Anggota

PropertyId

Menentukan ID properti yang sedang dijelaskan.

GetPropertyHandler

Pointer ke KStrGetPropertyHandler yang disediakan minidriver. Jika NULL, properti tidak dapat dibaca. Anggota ini hanya digunakan oleh driver yang menggunakan antarmuka kelas AVStream atau Stream.

GetSupported

Atur ke TRUE jika properti ini mendukung permintaan get, FALSE jika tidak. (Driver kelas memenuhi permintaan melalui permintaan SRB_GET_DEVICE_PROPERTY atau SRB_GET_STREAM_PROPERTY.) Anggota ini hanya digunakan oleh minidriver yang berjalan di bawah kelas stream.

MinProperty

Menentukan panjang buffer minimum untuk menahan pengidentifikasi properti. Ini harus setidaknya ukuranof (KSPROPERTY).

MinData

Menentukan panjang buffer minimum untuk menahan data yang dibaca dari atau ditulis ke properti ini.

SetPropertyHandler

Pointer ke KStrSetPropertyHandler yang disediakan minidriver. Jika NULL, properti tidak dapat diatur. Anggota ini hanya digunakan oleh driver yang menggunakan antarmuka kelas AVStream atau Stream.

SetSupported

Atur ke TRUE jika properti ini mendukung permintaan yang ditetapkan, FALSE jika tidak. (Driver kelas memenuhi permintaan melalui permintaan SRB_SET_DEVICE_PROPERTY atau SRB_SET_STREAM_PROPERTY.)

Values

Penunjuk ke struktur jenis KSPROPERTY_VALUES. Menentukan nilai yang dapat diterima dan/atau default untuk properti . Ini sama dengan nilai yang dilaporkan oleh driver sebagai respons terhadap permintaan IOCTL_KS_PROPERTY dengan bendera KSPROPERTY_TYPE_BASICSUPPORT dan KSPROPERTY_TYPE_DEFAULTVALUES ditetapkan.

RelationsCount

Menentukan jumlah entri dalam array yang ditujukkan oleh anggota Hubungan .

Relations

Menunjuk ke array struktur KSPROPERTY yang mewakili properti yang terkait dengan yang satu ini. Dua properti dianggap terkait jika mengubah satu properti dapat memengaruhi nilai properti lainnya. Anggota Bendera dari setiap entri tidak digunakan.

SupportHandler

Berikan anggota ini hanya jika menerapkan format Anda sendiri untuk serialisasi mentah atau unserialisasi mentah. Kueri dukungan dasar, kueri rentang, dan kueri relasi secara otomatis ditangani oleh AVStream, yang mengembalikan nilai yang relevan dari anggota lain dari struktur KSPROPERTY_ITEM ini.

SerializedSize

Menentukan ukuran properti saat diserialisasikan dalam permintaan KSPROPERTY_TYPE_SERIALIZESET. Ini harus nol jika properti tidak dapat diserialisasikan. Lihat KSPROPERTY untuk informasi selengkapnya.

Keterangan

Stream minidriver kelas menggunakan KSPROPERTY_ITEM untuk menjelaskan kepada klien cara memenuhi permintaan properti pada setiap properti dalam satu set. Penanganan untuk properti yang ditetapkan secara keseluruhan ditentukan dalam struktur KSPROPERTY_SET , yang berisi pointer ke array struktur KSPROPERTY_ITEM.

Driver kelas stream menangani permintaan properti atas nama minidriver. Ketika driver kelas stream memerlukan informasi lebih lanjut dari minidriver, ia meneruskan permintaan SRB_XXX ke salah satu rutinitas StrMiniReceiveXXXRequest minidriver. Driver kelas stream menangani berbagai jenis permintaan seperti yang tercantum dalam tabel berikut.

Nilai bendera permintaan properti	Respons
KSPROPERTY_TYPE_GET	Jika GetSupportedTRUE, driver kelas stream mengirimkan permintaan SRB_GET_DEVICE_PROPERTY atau SRB_GET_STREAM_PROPERTY ke rutinitas minidriver StrMiniReceiveXXXRequest yang sesuai.
KSPROPERTY_TYPE_SET	Jika SetSupportedTRUE, driver kelas stream mengirimkan permintaan SRB_SET_DEVICE_PROPERTY atau SRB_SET_STREAM_PROPERTY ke rutinitas minidriver StrMiniReceiveXXXRequest yang sesuai.
KSPROPERTY_TYPE_BASICSUPPORT	Driver kelas stream menggunakan KSPROPERTY_ITEM untuk mendapatkan informasi yang diperlukan untuk memenuhi permintaan ini. Misalnya, untuk menentukan jenis data dan rentang data properti yang diizinkan, mereka masing-masing menggunakan anggota Nilai dari struktur ini.
KSPROPERTY_TYPE_SETSUPPORT	Driver kelas stream menyelesaikan IRP permintaan properti sebagai STATUS_SUCCESS hanya jika driver menyediakan entri untuk properti yang diatur dalam struktur KSPROPERTY_SET .
KSPROPERTY_TYPE_DEFAULTVALUES	Driver kelas stream menggunakan anggota Nilai dari struktur ini untuk menentukan nilai default untuk data properti.
KSPROPERTY_TYPE_RELATIONS	Driver kelas stream menggunakan anggota Relasi untuk menentukan properti apa yang terkait dengan properti ini.

Jika klien menentukan KSPROPERTY_TYPE_DEFAULTVALUES, driver menggunakan buffer data untuk mengembalikan deskripsi jenis nilainya, termasuk mungkin rentang yang diizinkan dan nilai defaultnya. Bendera ini mirip dengan hasil KSPROPERTY_TYPE_BASICSUPPORT, kecuali bahwa nilai yang dikembalikan adalah nilai yang telah ditandai dengan KSPROPERTY_MEMBER_FLAG_DEFAULT di anggota Bendera struktur KSPROPERTY_MEMBERSHEADER.

Untuk informasi selengkapnya, lihat Properti KS.