Fungsi CoCreateFreeThreadedMarshaler (combaseapi.h)

Artikel
02/24/2024

Membuat objek yang dapat diagregasi yang mampu melakukan marshaling tergantung konteks.

Sintaks

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

Parameter

[in] punkOuter

Penunjuk ke objek agregat yang mengontrol IUnknown.

[out] ppunkMarshal

Alamat variabel pointer yang menerima penunjuk antarmuka ke marshaler yang dapat diagregasi.

Nilai kembali

Fungsi ini dapat mengembalikan nilai pengembalian standar E_OUTOFMEMORY, serta nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Marshaler dibuat.

Keterangan

Fungsi CoCreateFreeThreadedMarshaler memungkinkan objek untuk secara efisien membuat marshal penunjuk antarmuka di antara utas dalam proses yang sama. Jika objek Anda tidak mendukung marshaling interthread, Anda tidak perlu memanggil fungsi ini. Ini ditujukan untuk digunakan oleh server DLL berulir bebas yang harus diakses langsung oleh semua utas dalam proses, bahkan utas yang terkait dengan apartemen berulir tunggal. Ini custom-marshals pointer memori nyata ke apartemen lain sebagai "proksi" palsu dan dengan demikian memberikan akses langsung ke semua penelepon, bahkan jika mereka tidak berulir bebas.

Fungsi CoCreateFreeThreadedMarshaler melakukan tugas-tugas berikut:

Membuat objek marshaler berulir bebas.
Mengagregasi marshaler ini ke objek yang ditentukan oleh parameter punkOuter . Objek ini biasanya merupakan objek yang penunjuk antarmukanya akan dijadikan marshal.

Implementasi IMarshal objek agregat harus mendelegasikan panggilan QueryInterface untuk IID_IMarshal ke IUnknown dari marshaler berulir bebas. Setelah menerima panggilan, marshaler berulir bebas melakukan tugas-tugas berikut:

Memeriksa konteks tujuan yang ditentukan oleh parameter dwDestContext fungsi CoMarshalInterface.
Jika konteks tujuan MSHCTX_INPROC, salin penunjuk antarmuka ke aliran marshaling.
Jika konteks tujuan adalah nilai lain, menemukan atau membuat instans marshaler default (standar) COM dan mendelegasikan marshaling ke dalamnya.

Nilai untuk dwDestContext berasal dari enumerasi MSHCTX . MSHCTX_INPROC menunjukkan bahwa penunjuk antarmuka akan dinaungi di antara utas yang berbeda dalam proses yang sama. Karena kedua utas memiliki akses ke ruang alamat yang sama, utas klien dapat mendereferensikan penunjuk secara langsung daripada harus mengarahkan panggilan ke proksi. Dalam semua kasus lain, proksi diperlukan, sehingga CoCreateFreeThreadedMarshaler mendelegasikan pekerjaan marshaling ke implementasi default COM.

Perhatian besar harus dilakukan dalam menggunakan fungsi CoCreateFreeThreadedMarshaler . Ini karena performa objek yang mengagregasi marshaler utas bebas diperoleh melalui pelanggaran terhitung dari aturan COM, dengan risiko perilaku yang tidak terdefinisi yang selalu ada kecuali objek beroperasi dalam batasan tertentu. Pembatasan yang paling penting adalah:

Objek marshaler berulir bebas tidak dapat menahan penunjuk langsung ke antarmuka pada objek yang tidak mengagregasi marshaler berulir bebas sebagai bagian dari keadaannya. Jika objek menggunakan referensi langsung ke objek agregat utas tunggal biasa, objek tersebut dapat merusak properti utas tunggal mereka. Jika objek menggunakan referensi langsung ke objek agregat multithread biasa, objek ini dapat berperilaku dengan cara yang tidak menunjukkan sensitivitas terhadap kebutuhan klien agregat utas tunggal langsung. Misalnya, objek ini dapat memutar utas baru dan meneruskan parameter ke utas yang merupakan referensi ke objek agregat utas tunggal biasa.
Objek marshaler berulir bebas tidak dapat menyimpan referensi ke proksi ke objek di apartemen lain. Proksi sensitif terhadap model utas dan dapat mengembalikan RPC_E_WRONG_THREAD jika dipanggil oleh klien yang salah.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	combaseapi.h (termasuk Objbase.h)
Pustaka	Ole32.lib
DLL	Ole32.dll

Lihat juga

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream

Bagikan melalui