Metode IUnknown::QueryInterface(REFIID,void**) (unknwn.h)

  • Artikel

Mengkueri objek COM untuk penunjuk ke salah satu antarmukanya; mengidentifikasi antarmuka dengan referensi ke pengidentifikasi antarmukanya (IID). Jika objek COM mengimplementasikan antarmuka, maka ia mengembalikan pointer ke antarmuka tersebut setelah memanggil IUnknown::AddRef di atasnya.

Sintaks

HRESULT QueryInterface(
  REFIID riid,
  void   **ppvObject
);

Parameter

riid

Jenis: REFIID

Referensi ke pengidentifikasi antarmuka (IID) antarmuka yang sedang dikueri.

ppvObject

Jenis: batal**

Alamat pointer ke antarmuka dengan IID yang ditentukan dalam parameter riid . Karena Anda meneruskan alamat penunjuk antarmuka, metode dapat menimpa alamat tersebut dengan penunjuk ke antarmuka yang sedang dikueri. Setelah berhasil kembali, *ppvObject (alamat dereferensi) berisi penunjuk ke antarmuka yang diminta. Jika objek tidak mendukung antarmuka, metode mengatur *ppvObject (alamat dereferensi) ke nullptr.

Nilai kembali

Metode ini mengembalikan S_OK jika antarmuka didukung, dan E_NOINTERFACE sebaliknya. Jika ppvObject (alamat) adalah nullptr, maka metode ini mengembalikan E_POINTER.

Keterangan

Untuk objek COM tertentu (juga dikenal sebagai komponen COM), kueri tertentu untuk antarmuka IUnknown pada antarmuka objek mana pun harus selalu mengembalikan nilai pointer yang sama. Ini memungkinkan klien untuk menentukan apakah dua pointer menunjuk ke komponen yang sama dengan memanggil QueryInterface dengan IID_IUnknown dan membandingkan hasilnya. Ini secara khusus tidak terjadi bahwa kueri untuk antarmuka selain IUnknown (bahkan antarmuka yang sama melalui pointer yang sama) harus mengembalikan nilai pointer yang sama.

Ada empat persyaratan untuk implementasi QueryInterface (Dalam kasus ini, "harus berhasil" berarti "harus berhasil menghalangi kegagalan bencana.").

  • Kumpulan antarmuka yang dapat diakses pada objek melalui QueryInterface harus statis, bukan dinamis. Ini berarti bahwa jika panggilan ke QueryInterface untuk penunjuk ke antarmuka tertentu berhasil pertama kalinya, maka panggilan harus berhasil lagi. Jika panggilan gagal untuk pertama kalinya, maka panggilan harus gagal pada semua panggilan berikutnya.
  • Ini harus refleksif—jika klien memegang pointer ke antarmuka pada objek, dan klien meminta antarmuka tersebut, maka panggilan harus berhasil.
  • Ini harus simetris—jika klien yang memegang pointer ke satu kueri antarmuka berhasil untuk yang lain, maka kueri melalui penunjuk yang diperoleh untuk antarmuka pertama harus berhasil.
  • Ini harus transitif—jika klien yang memegang pointer ke satu kueri antarmuka berhasil selama satu detik, dan melalui kueri penunjuk tersebut berhasil untuk antarmuka ketiga, maka kueri untuk antarmuka pertama melalui penunjuk untuk antarmuka ketiga harus berhasil.

Catatan untuk pelaksana

Implementasi QueryInterface tidak boleh memeriksa ACL. Alasan utama untuk aturan ini adalah bahwa COM mengharuskan objek yang mendukung antarmuka tertentu selalu mengembalikan keberhasilan ketika dikueri untuk antarmuka tersebut. Alasan lain adalah bahwa memeriksa ACL di QueryInterface tidak memberikan keamanan nyata karena setiap klien yang memiliki akses ke antarmuka tertentu dapat menyerahkannya langsung ke klien lain tanpa panggilan kembali ke server. Selain itu, karena COM menyimpan pointer antarmuka, COM tidak memanggil QueryInterface di server setiap kali klien melakukan kueri.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Target Platform Windows
Header unknwn.h

Lihat juga