Fungsi RoGetAgileReference (combaseapi.h)

Artikel
02/28/2024

Membuat referensi tangkas untuk objek yang ditentukan oleh antarmuka yang diberikan.

Sintaks

HRESULT RoGetAgileReference(
  [in]  AgileReferenceOptions options,
  [in]  REFIID                riid,
  [in]  IUnknown              *pUnk,
  [out] IAgileReference       **ppAgileReference
);

Parameter

[in] options

Opsi pendaftaran.

[in] riid

ID antarmuka objek tempat referensi tangkas diperoleh.

[in] pUnk

Penunjuk ke antarmuka yang akan dienkapsulasi dalam referensi tangkas. Jenisnya harus sama dengan riid. Ini mungkin penunjuk ke objek dalam proses atau penunjuk ke proksi objek.

[out] ppAgileReference

Referensi tangkas untuk objek . Panggil metode Resolve untuk melokalisasi objek ke apartemen tempat Resolve dipanggil.

Menampilkan nilai

Fungsi ini dapat mengembalikan salah satu nilai ini.

Mengembalikan nilai	Deskripsi
S_OK	Fungsi berhasil diselesaikan.
E_INVALIDARG	Parameter opsi tidak valid.
E_OUTOFMEMORY	Referensi tangkas tidak dapat dibangun karena kondisi kehabisan memori.
E_NOINTERFACE	Parameter pUnk tidak mendukung ID antarmuka yang ditentukan oleh parameter riid .
CO_E_NOT_SUPPORTED	Objek mengimplementasikan antarmuka INoMarshal .

Keterangan

Panggil fungsi RoGetAgileReference pada objek yang ada untuk meminta referensi tangkas ke objek. Objek mungkin atau mungkin tidak tangkas, tetapi IAgileReference yang dikembalikan tangkas. Referensi agile dapat diteruskan ke apartemen lain dalam proses yang sama, di mana objek asli diambil dengan menggunakan antarmuka IAgileReference .

Ini secara konseptual mirip dengan Global Interface Table (GIT) yang ada. Daripada berinteraksi dengan GIT, IAgileReference diperoleh dan digunakan untuk mengambil objek secara langsung. Sama seperti GIT hanya per proses, referensi tangkas per proses dan tidak dapat di-marshal.

Fitur referensi tangkas memberikan peningkatan performa atas GIT. Referensi tangkas melakukan marshaling bersemangat secara default, yang menyimpan panggilan lintas apartemen dalam kasus di mana objek diambil dari referensi tangkas di apartemen yang berbeda dari tempat referensi tangkas dibuat. Untuk peningkatan performa tambahan, pengguna fungsi RoGetAgileReference dapat menggunakan antarmuka yang sama untuk membuat IAgileReference dan menyelesaikan objek asli. Ini menyimpan panggilan QueryInterface tambahan untuk mendapatkan antarmuka yang diinginkan dari objek yang diselesaikan.

Misalnya, Anda memiliki objek non-agile bernama CDemoExample, yang mengimplementasikan antarmuka IDemo dan IExample. Panggil fungsi RoGetAgileReference dan teruskan objek, dengan IID_IDemo. Anda mendapatkan kembali penunjuk antarmuka IAgileReference , yang tangkas, sehingga Anda dapat meneruskannya ke apartemen yang berbeda. Di apartemen lain, panggil metode Resolve , dengan IID_IExample. Anda mendapatkan kembali pointer IExample yang dapat Anda gunakan di dalam apartemen ini. Penunjuk IExample ini adalah proksi IExample yang tersambung ke objek CDemoExample asli. Referensi tangkas menangani kompleksitas operasi seperti marshaling secara manual ke aliran dan unmarshaling di sisi lain batas apartemen.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8.1 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 R2 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	combaseapi.h
Pustaka	Ole32.lib
DLL	Ole32.dll

Lihat juga

AgileReferenceOptions

IAgileReference

Bagikan melalui