Antarmuka IKsAggregateControl (ksproxy.h)

Artikel
08/07/2023

Antarmuka IKsAggregateControl menyediakan metode yang menambahkan dan menghapus server COM sebagai penyedia agregat pada objek KS yang mendukung antarmuka.

Pengidentifikasi antarmuka (IID) untuk antarmuka ini IID_IKsAggregateControl.

Warisan

Antarmuka IKsAggregateControl mewarisi dari antarmuka IUnknown .

Metode

Antarmuka IKsAggregateControl memiliki metode ini.


IKsAggregateControl::KsAddAggregate Metode KsAddAggregate menambahkan server COM sebagai penyedia agregat ke daftar penyedia antarmuka untuk objek KS yang mengekspos antarmuka IKsAggregateControl.
IKsAggregateControl::KsRemoveAggregate Metode KsRemoveAggregate menghapus penyedia agregat server COM yang ditambahkan sebelumnya dari daftar penyedia antarmuka untuk objek KS yang mengekspos antarmuka IKsAggregateControl.

Keterangan

Semua properti, metode, dan kumpulan peristiwa yang didukung filter atau pin KS dapat diwakili pada representasi proksi DirectShow dari filter atau sematkan objek dengan antarmuka agregat nol atau lebih, dialog, dan sebagainya. Antarmuka agregat klien ini diatur ekstensi yang kemudian dapat digunakan untuk berkomunikasi ke objek KS yang mendasar untuk mewakili fungsionalitas set. Ekstensi yang ditetapkan adalah server COM terdaftar, yang dimuat melalui CoCreateInstance oleh filter KS atau sematkan pada waktu pembuatan handel.

Tujuan utama dari set ekstensi adalah untuk memungkinkan agregasi antarmuka sehingga mendukung beberapa set melalui satu atau beberapa antarmuka COM. Namun, implementasi juga dapat mencakup dukungan dialog, pemrosesan asinkron dalam utas, dan sebagainya. Pendaftaran handler set memungkinkan seseorang untuk menunjukkan antarmuka tertentu yang akan diagregasi atau bahwa daftar antarmuka yang tidak disebutkan namanya akan diekspos. Dalam kasus pertama, hanya kueri yang sesuai yang dikirim ke objek , dan dalam yang terakhir semua kueri yang tidak cocok dengan antarmuka yang sudah didukung dikirim ke objek ekstensi ini.

Ekstensi juga dapat menerima pemberitahuan perubahan status dengan mendukung antarmuka IDistributorNotify . Jika objek ekstensi mendukung antarmuka ini, objek tersebut akan diberi tahu tentang semua perubahan status mulai, berhenti, dan jeda sebelum filter itu sendiri memproses perubahan tersebut. Selain itu, metode IDistributorNotify::NotifyGraphChange digunakan pada ekstensi sematkan objek untuk menunjukkan bahwa instans pin KS baru saja ditutup. Metode ini hanya digunakan untuk ekstensi antarmuka pin dan dipanggil pada objek ekstensi setiap kali pin terputus atau terhubung kembali, sementara objek ekstensi masih dimuat dan diagregasi oleh objek pin.

Pemberitahuan tentang perubahan koneksi pin diperlukan karena ekstensi tidak dibongkar saat pin terputus. Sebagai gantinya, ekstensi dimuat pertama kali pin terhubung dan dibiarkan dimuat melalui pemutusan sambungan dan koneksi ulang, kecuali koneksi ulang menunjukkan bahwa set ekstensi tertentu tidak didukung pada pin lagi. Fakta ini memungkinkan objek ekstensi untuk mempertahankan status antara koneksi ulang, tetapi itu juga berarti bahwa ekstensi mungkin memerlukan informasi tentang apakah pin KS saat ini terhubung. Ekstensi dapat menentukan informasi ini dengan memanggil metode IKsObject::KsGetObjectHandle untuk mengkueri handel objek pin KS saat ekstensi menerima panggilan NotifyGraphChange . Ketika ekstensi pertama kali dimuat, ekstensi dapat mengasumsikan pin terhubung dan pemberitahuan berikutnya dapat menyiratkan pemutusan, atau koneksi ulang. Dengan demikian, pemberitahuan terjadi setelah perubahan aktual terjadi, dibandingkan dengan perubahan status, yang memberi tahu sebelumnya.

Ekstensi yang ditetapkan pada dasarnya adalah server COM yang secara opsional mengekspos antarmuka IDistributorNotify dan nol atau lebih antarmuka agregat lainnya yang dapat digunakan oleh klien filter untuk memanipulasi set yang diwakili objek ekstensi. Pada permintaan pembuatan objek ekstensi melalui CoCreateInstance, server selalu disajikan IUnknown luar untuk membuat objek COM. IUnknown ini adalah antarmuka pada filter atau objek pin yang memuat ekstensi set. Penunjuk antarmuka IUnknown dapat digunakan untuk mengkueri informasi atau antarmuka dari filter atau pin, seperti IKsControl. Namun, tidak ada referensi yang harus dibiarkan pada objek luar, karena akan menghasilkan jumlah referensi melingkar. Menggunakan antarmuka tanpa jumlah referensi dapat diterima, karena ekstensi diagregasi oleh objek luar dan, menurut definisi, dihancurkan ketika jumlah referensi objek luar mencapai nol.

Untuk memuat ekstensi set, proksi mencari GUID dari setiap set yang dikumpulkan dari filter atau pin, menentukan apakah masing-masing ada di registri. GUID untuk setiap set yang memiliki ekstensi yang dimuat adalah:

HKLM\System\CurrentControlSet\Control\MediaInterfaces\{set guid}

Jika subkunci ini ada, GUID set sesuai langsung dengan GUID yang digunakan dalam parameter server COM dari panggilan CoCreateInstance . Setiap subkey mungkin juga memiliki iid nilai biner bernama yang berisi representasi biner GUID agar antarmuka diagregasi untuk ekstensi set ini. Ini adalah GUID antarmuka yang akan menyebabkan QueryInterface pada filter atau pin dikirim ke server COM untuk ekstensi ini. Jika nilai bernama ini tidak ada di bawah kunci sekumpulan, semua panggilan QueryInterface yang tidak diketahui akan dirutekan melalui objek ekstensi ini, sehingga memungkinkannya untuk mendukung banyak antarmuka untuk set tertentu yang terekspos pada objek yang mendasar. GUID set dapat digunakan sebagai pengidentifikasi antarmuka dengan mengatur iid menjadi GUID set, atau dengan tidak mengatur nilai iid. Dalam kasus terakhir, kueri tambahan yang tidak didukung dapat dikirim ke objek ekstensi.

Meskipun kunci registri MediaInterfaces dapat digunakan untuk secara eksplisit menunjukkan antarmuka mana (jika ada) agregat penyedia, seluruh entri tidak perlu ada. Implikasinya adalah bahwa server COM apa pun dapat dimuat melalui IKsAggregateControl sehingga server COM ini menyediakan antarmuka agregat, apakah server COM tercantum di bawah kunci registri MediaInterfaces .

Untuk set yang didukung dan sudah menentukan penangan objek ekstensi yang secara otomatis terdaftar pada waktu penginstalan atau ketika jenis perangkat tertentu ditambahkan ke sistem, penginstalan driver tidak perlu melakukan pekerjaan tambahan dalam mengekspos antarmuka COM ini untuk filter mereka. Namun, untuk mengekspos antarmuka COM untuk set privat, entri MediaInterfaces dan entri server COM perlu ditambahkan ketika filter diinstal.

Proksi juga memungkinkan filter untuk mengambil alih server COM untuk set yang terdaftar di bawah MediaInterfaces. Untuk mengambil alih, buat kunci SetAliases di bawah kunci registri antarmuka Plug and Play. CLSID dan FriendlyName terletak di jalur HKLM\...\SetAliases.

Selain itu, masukkan nilai bernama {set guid}, yang merupakan format string dari GUID yang ditetapkan, sebagai nilai biner GUID untuk subkunji pengganti MediaInterfaces . Dengan demikian, untuk filter ini atau objek apa pun di bawah filter ini, semua set dengan GUID ini akan menggunakan GUID alternatif ini untuk mencari entri MediaInterfaces daripada GUID dari set itu sendiri. Entri MediaInterfaces baru akan didaftarkan seperti biasa.

Untuk informasi selengkapnya tentang IDistributorNotify, IUnknown, dan CoCreateInstance, lihat dokumentasi Microsoft Windows SDK.