Metode IMarshal::MarshalInterface (objidl.h)

Artikel
08/25/2023

Marshals penunjuk antarmuka.

Sintaks

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

Parameter

[in] pStm

Penunjuk ke aliran yang akan digunakan selama marshaling.

[in] riid

Referensi ke pengidentifikasi antarmuka yang akan dinamai. Antarmuka ini harus berasal dari antarmuka IUnknown .

[in] pv

Penunjuk ke penunjuk antarmuka untuk dinamai marshal. Parameter ini bisa NULL jika pemanggil tidak memiliki penunjuk ke antarmuka yang diinginkan.

[in] dwDestContext

Konteks tujuan di mana antarmuka yang ditentukan tidak akan diubah. Nilai yang mungkin untuk dwDestContext berasal dari enumerasi MSHCTX. Saat ini, unmarshaling dapat terjadi baik di apartemen lain dari proses saat ini (MSHCTX_INPROC) atau dalam proses lain pada komputer yang sama dengan proses saat ini (MSHCTX_LOCAL).

[in] pvDestContext

Parameter ini dicadangkan dan harus 0.

[in] mshlflags

Menunjukkan apakah data yang akan dinamai akan dikirimkan kembali ke proses klien—kasus umum—atau ditulis ke tabel global, tempat data dapat diambil oleh beberapa klien. Kemungkinan nilai berasal dari enumerasi MSHLFLAGS .

Menampilkan nilai

Metode ini dapat mengembalikan nilai pengembalian standar E_FAIL, serta nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Penunjuk antarmuka berhasil dinamai.
E_NOINTERFACE	Antarmuka yang ditentukan tidak didukung.
STG_E_MEDIUMFULL	Aliran penuh.

Keterangan

Metode ini dipanggil secara tidak langsung, dalam panggilan ke CoMarshalInterface, dengan kode apa pun dalam proses server bertanggung jawab untuk marshaling pointer ke antarmuka pada objek. Kode marshaling ini biasanya merupakan stub yang dihasilkan oleh COM untuk salah satu dari beberapa antarmuka yang dapat marshal penunjuk ke antarmuka yang diimplementasikan pada objek yang sama sekali berbeda. Contohnya termasuk antarmuka IClassFactory dan IOleItemContainer . Untuk tujuan diskusi, kode yang bertanggung jawab untuk marshaling pointer disebut marshaling stub.

Catatan untuk Penelepon

Biasanya, daripada memanggil MarshalInterface secara langsung, marshaling stub Anda seharusnya memanggil fungsi CoMarshalInterface , yang berisi panggilan ke metode ini. Stub melakukan panggilan ini untuk memerintahkan objek untuk menulis data marshaling-nya ke dalam aliran. Stub kemudian meneruskan data marshaling kembali ke proses klien atau menulisnya ke tabel global, di mana dapat dibatalkan napasnya oleh beberapa klien. Panggilan stub ke CoMarshalInterface biasanya didahului oleh panggilan ke CoGetMarshalSizeMax untuk mendapatkan ukuran maksimum buffer aliran tempat data marshaling akan ditulis.

Anda tidak secara eksplisit memanggil metode ini jika Anda menerapkan antarmuka COM yang ada atau menentukan antarmuka Anda sendiri menggunakan Microsoft Interface Definition Language (MIDL). Dalam kedua kasus, stub yang dihasilkan MIDL secara otomatis melakukan panggilan.

Jika Anda tidak menggunakan MIDL untuk menentukan antarmuka Anda sendiri, stub marshaling Anda harus memanggil metode ini, baik secara langsung maupun tidak langsung. Implementasi stub Anda harus memanggil MarshalInterface segera setelah panggilan sebelumnya ke IMarshal::GetMarshalSizeMax kembali. Karena nilai yang dikembalikan oleh GetMarshalSizeMax dijamin hanya valid selama status internal objek yang di-marsekal tidak berubah, penundaan dalam memanggil MarshalInterface menjalankan risiko bahwa objek akan memerlukan buffer aliran yang lebih besar daripada yang ditunjukkan awalnya.

Jika penelepon memiliki penunjuk ke antarmuka yang akan dinamai marshal, itu harus, sebagai masalah efisiensi, gunakan parameter pv untuk meneruskan pointer tersebut. Dengan cara ini, implementasi yang dapat menggunakan penunjuk seperti itu untuk menentukan CLSID yang sesuai untuk proksi tidak harus memanggil QueryInterface pada dirinya sendiri. Jika penelepon tidak memiliki penunjuk ke antarmuka yang akan dinamai marshal, penelepon dapat melewati NULL.

Catatan untuk Pelaksana

Implementasi MarshalInterface Anda harus menulis ke aliran data apa pun yang diperlukan untuk menginisialisasi proksi di sisi penerimaan. Data tersebut akan mencakup referensi ke antarmuka yang akan dinamai, nilai MSHLFLAGS yang menentukan apakah data harus dikembalikan ke proses klien atau ditulis ke tabel global, dan apa pun yang diperlukan untuk terhubung ke objek, seperti pipa bernama, menangani ke jendela, atau penunjuk ke saluran RPC.

Implementasi Anda tidak boleh berasumsi bahwa aliran cukup besar untuk menyimpan semua data. Sebaliknya, itu harus dengan anggun menangani kesalahan STG_E_MEDIUMFULL. Tepat sebelum keluar, implementasi Anda harus memposisikan penunjuk pencarian di aliran segera setelah byte terakhir dari data yang ditulis.

Jika parameter pv adalah NULL dan implementasi Anda memerlukan penunjuk antarmuka, parameter tersebut dapat memanggil QueryInterface pada objek saat ini untuk mendapatkannya. Parameter pv hanya ada untuk meningkatkan efisiensi.

Untuk memastikan bahwa implementasi MarshalInterface Anda terus berfungsi dengan baik karena konteks tujuan baru didukung di masa depan, delegasikan marshaling ke implementasi default COM untuk semua nilai dwDestContext yang tidak ditangani implementasi Anda. Untuk mendelegasikan marshaling ke implementasi default COM, panggil fungsi pembantu CoGetStandardMarshal .

Dengan menggunakan enumerasi MSHLFLAGS , penelepon dapat menentukan apakah penunjuk antarmuka akan dinamai kembali ke satu klien atau ditulis ke tabel global, di mana dapat dibatalkan namanya oleh beberapa klien. Anda harus memastikan bahwa objek Anda dapat menangani panggilan dari beberapa proksi yang mungkin dibuat dari data inisialisasi yang sama.

Persyaratan


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	objidl.h (termasuk ObjIdl.h)

Lihat juga

CoMarshalInterface

IMarshal

Bagikan melalui