Struktur KSPIN (ks.h)

Artikel
02/26/2024

Struktur KSPIN menjelaskan pin yang diinstansiasi.

Sintaks

typedef struct _KSPIN {
  const KSPIN_DESCRIPTOR_EX *Descriptor;
  KSOBJECT_BAG              Bag;
  PVOID                     Context;
  ULONG                     Id;
  KSPIN_COMMUNICATION       Communication;
  BOOLEAN                   ConnectionIsExternal;
  KSPIN_INTERFACE           ConnectionInterface;
  KSPIN_MEDIUM              ConnectionMedium;
  KSPRIORITY                ConnectionPriority;
  PKSDATAFORMAT             ConnectionFormat;
  PKSMULTIPLE_ITEM          AttributeList;
  ULONG                     StreamHeaderSize;
  KSPIN_DATAFLOW            DataFlow;
  KSSTATE                   DeviceState;
  KSRESET                   ResetState;
  KSSTATE                   ClientState;
} KSPIN, *PKSPIN;

Anggota

Descriptor

Penunjuk ke deskriptor pin untuk pin tertentu ini. Lihat KSPIN_DESCRIPTOR_EX untuk informasi selengkapnya.

Bag

Anggota ini menentukan KSOBJECT_BAG (struktur KSOBJECT_BAG setara dengan jenis PVOID) untuk instans pin tertentu ini. Tas Objek adalah struktur yang digunakan untuk mengaitkan memori dinamis dengan objek AVStream tertentu. Apa pun di tas objek pin secara otomatis dibersihkan ketika pin ditutup.

Context

Penunjuk ke buffer. Klien dapat menggunakan Konteks untuk mengaitkan informasi konteks dengan instans pin tertentu. Biasanya, ini digunakan untuk ekstensi pin/stream dan dialokasikan dalam buat pengiriman yang disediakan dalam tabel pengiriman pin. Perhatikan bahwa memori dinamis apa pun yang dialokasikan untuk informasi konteks harus ditempatkan di tas objek instans pin menggunakan KsAddItemToObjectBag. Konteks diinisialisasi ke nilai anggota Konteksdari KSFILTER induk pada saat pin dibuat. Lihat Hierarki Objek AVStream.

Id

Anggota ini menentukan pengidentifikasi jenis pin. Ini adalah indeks ke dalam array deskriptor pin yang disediakan untuk jenis filter yang diberikan.

Communication

Anggota ini menentukan KSPIN_COMMUNICATION_NONE, KSPIN_COMMUNICATION_SINK, KSPIN_COMMUNICATION_SOURCE, KSPIN_COMMUNICATION_BOTH, atau KSPIN_COMMUNICATION_BRIDGE. Lihat KSPROPERTY_PIN_COMMUNICATION untuk arti setiap nilai.

ConnectionIsExternal

Anggota ini menentukan nilai Boolean yang, jika TRUE, menunjukkan bahwa pin yang terhubung tidak mendukung jabat tangan koneksi AVStream. Jika FALSE, menunjukkan bahwa pin yang terhubung mendukung jabat tangan koneksi AVStream. Ini adalah indikasi apakah koneksi antara pin ini dan pin yang terhubung dengannya adalah koneksi antara dua pin AVStream.

ConnectionInterface

Anggota ini berisi struktur KSPIN_INTERFACE yang mengidentifikasi antarmuka yang digunakan untuk koneksi. Informasi ini disediakan oleh penyusun grafik saat pin dibuat.

ConnectionMedium

Anggota ini berisi struktur KSPIN_MEDIUM yang mengidentifikasi media koneksi yang harus digunakan pin ini. Informasi ini disediakan oleh penyusun grafik saat pin dibuat.

ConnectionPriority

Anggota ini berisi struktur KSPRIORITY yang menentukan prioritas koneksi. Informasi ini disediakan oleh penyusun grafik saat pin dibuat.

ConnectionFormat

Penunjuk ke struktur KSDATAFORMAT yang menentukan format data koneksi. Informasi ini awalnya disediakan oleh penyusun grafik saat pin dibuat dan dapat diubah melalui akses properti atau dengan format pesan perubahan yang dimasukkan ke dalam aliran. Akses ke anggota ini disinkronkan oleh mutex kontrol filter. Anggota ini tidak boleh diubah oleh klien.

AttributeList

Penunjuk ke struktur KSMULTIPLE_ITEM yang menentukan daftar atribut, yang disediakan selama pembuatan pin, untuk menjelaskan koneksi. Menentukan arah aliran data untuk pin ini (KSPIN_DATAFLOW_IN atau KSPIN_DATAFLOW_OUT). Informasi ini adalah atribut statis pin dan muncul di deskriptor pin. Ini di-cache di sini untuk akses di IRQL di atas PASSIVE_LEVEL.

StreamHeaderSize

Anggota ini menunjukkan ukuran dalam byte dari setiap struktur KSSTREAM_HEADER untuk pin ini. Biasanya digunakan untuk pin output, klien dapat mengatur ini ke nilai apa pun yang lebih besar dari sizeof (KSSTREAM_HEADER) dan memiliki header stream yang diperluas yang dialokasikan (setiap header stream akan menjadi byte StreamHeaderSize panjang). Jika klien tidak mengatur anggota ini, ini menunjukkan bahwa tidak ada informasi yang diperluas mengikuti header stream. Dalam situasi seperti itu, setiap header stream sangat berukuranof (KSSTREAM_HEADER). Klien dapat mengatur ini dalam pengiriman pembuatan pin.

DataFlow

Anggota ini menentukan arah aliran data untuk pin. Pengaturan yang mungkin KSPIN_DATAFLOW_IN dan KSPIN_DATAFLOW_OUT. Informasi ini adalah atribut statis pin dan muncul dalam struktur KSPIN_DESCRIPTOR yang relevan. Ini di-cache di sini untuk akses di IRQL di atas PASSIVE_LEVEL.

DeviceState

Anggota ini berisi enumerasi jenis KSSTATE yang mengidentifikasi status di mana pin telah diberitahu untuk transisi. Tidak harus sama dengan status pipa, yang dilaporkan melalui AVStrMiniPinSetDeviceState. Awalnya KSSTATE_STOP, anggota ini diubah ketika AVStream menerima properti status koneksi yang ditetapkan IOCTL. Akses disinkronkan menggunakan mutex kontrol filter. Minidriver tidak boleh mengubah anggota ini. Lihat catatan di bagian Keterangan di bawah ini. Lihat juga anggota ClientState .

ResetState

Anggota ini berisi enumerasi jenis KSRESET yang mengidentifikasi status reset pin saat ini. Pengaturan yang mungkin KSRESET_BEGIN dan KSRESET_END. Anggota ini awalnya diatur ke KSRESET_END dan diubah melalui akses properti. Akses ke anggota ini disinkronkan oleh mutex kontrol filter. Klien tidak boleh mengubah anggota ini.

ClientState

Anggota ini menentukan KSSTATE tempat pin saat ini diatur. Diperbarui segera sebelum AVStrMiniPinSetDeviceState dipanggil. Jika rutinitas panggilan balik ini gagal, AVStream mengembalikan ClientState ke nilai sebelumnya. Minidriver yang gagal transisi status dan yang memeriksa anggota ini selama pemrosesan harus menyadari urutan peristiwa ini.

Keterangan

Dalam banyak hal, pin adalah fokus perilaku filter. Ini tercermin dalam fakta bahwa struktur pin memiliki sejumlah besar anggota. Banyak minidriver perlu menyempurnakan perilaku pin dan mempertahankan konteks terkait pin tambahan. Untuk filter dengan perilaku pin yang cukup konvensional, tidak diperlukan penyempurnaan atau konteks tambahan. Dalam banyak kasus, perilaku pin default sudah cukup; pin diakses menggunakan Pemrosesan Filter-Sentris.

Untuk tujuan sinkronisasi, masa pakai objek ini adalah interval dimulai ketika fungsi pengiriman PraBuat minidriver dipanggil dan berakhir ketika fungsi Close dispatch minidriver kembali, dengan asumsi fungsi tidak mengembalikan STATUS_PENDING. Jika mengembalikan STATUS_PENDING, masa pakai objek berakhir ketika klien menunjukkan penyelesaian permintaan tutup dengan memanggil KsCompletePendingRequest.

Jika minidriver perlu menentukan apakah telah diberitahu untuk pergi ke KSSTATE tertentu, membandingkan nilai anggota DeviceState KSPIN dengan status tersebut bukanlah metode yang dapat diandalkan. Sebagai gantinya, lihat anggota ClientState , atau buat variabel di panggilan balik SetDeviceState lalu periksa variabel ini. SetDeviceState adalah anggota KSPIN_DISPATCH.

Lihat juga Object Bags.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Microsoft Windows XP dan sistem operasi yang lebih baru dan di Microsoft DirectX 8.0 dan versi yang lebih baru.
Header	ks.h (termasuk Ks.h)

Lihat juga

KsCompletePendingRequest