Fungsi OleCreateEmbeddingHelper (ole2.h)

Artikel
03/15/2023

Membuat objek pembantu penyematan OLE menggunakan kode yang disediakan aplikasi yang diagregasi dengan potongan penangan objek default OLE. Objek pembantu ini dapat dibuat dan digunakan dalam konteks dan peran tertentu, seperti yang ditentukan oleh pemanggil.

Sintaks

HRESULT OleCreateEmbeddingHelper(
  [in]  REFCLSID       clsid,
  [in]  LPUNKNOWN      pUnkOuter,
  [in]  DWORD          flags,
  [in]  LPCLASSFACTORY pCF,
  [in]  REFIID         riid,
  [out] LPVOID         *lplpObj
);

Parameter

[in] clsid

CLSID dari kelas yang akan dibantu.

[in] pUnkOuter

Jika pembantu penyematan akan diagregasi, arahkan ke antarmuka IUnknown kontrol objek luar. Jika tidak digabungkan, meskipun ini jarang terjadi, nilainya harus NULL.

[in] flags

DWORD berisi bendera yang menentukan peran dan konteks pembuatan untuk pembantu penyematan. Untuk nilai hukum, lihat bagian Keterangan berikut ini.

[in] pCF

Arahkan ke antarmuka IClassFactory pada objek kelas yang digunakan fungsi untuk membuat objek sekunder. Dalam beberapa situasi, nilai ini mungkin NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] riid

Referensi ke pengidentifikasi antarmuka yang diinginkan oleh pemanggil.

[out] lplpObj

Alamat variabel pointer yang menerima pointer antarmuka yang diminta dalam riid. Setelah berhasil kembali, *ppvObj berisi penunjuk antarmuka yang diminta pada pembantu penyematan yang baru dibuat.

Nilai kembali

Fungsi ini mengembalikan S_OK pada keberhasilan. Nilai lain yang mungkin termasuk yang berikut ini.

Menampilkan kode	Deskripsi
E_OUTOFMEMORY	Memori untuk operasi tidak cukup.
E_INVALIDARG	Satu atau beberapa parameter tidak valid.
E_UNEXPECTED	Terjadi kesalahan tidak terduga.
E_NOINTERFACE	Pengidentifikasi antarmuka yang disediakan tidak valid.

Keterangan

Fungsi OleCreateEmbeddingHelper membuat objek yang mendukung implementasi antarmuka yang sama yang ditemukan di handler default, tetapi yang memiliki kait tambahan yang memungkinkannya digunakan lebih umum daripada hanya sebagai objek handler. Dua panggilan berikut menghasilkan hasil yang sama:

OleCreateEmbeddingHelper(clsid, pUnkOuter, EMBDHLP_INPROC_HANDLER | 
    EMBDHLP_CREATENOW, NULL, iid, ppvObj) 
 
OleCreateDefaultHandler(clsid, pUnkOuter, iid, ppvObj)

Pembantu penyematan dapat diagregasi; pUnkOuter adalah IUnknown pengendali dari agregat yang menjadi bagian pembantu penyematan. Ini digunakan untuk membuat instans baru handler default OLE, yang dapat digunakan untuk mendukung objek dalam berbagai peran. Penelepon meneruskan pointer ke implementasi IClassFactory ke OleCreateEmbeddingHelper. Objek ini dan handler default kemudian diagregasi untuk membuat objek pembantu penyematan baru.

Fungsi OleCreateEmbeddingHelper biasanya digunakan untuk mendukung salah satu implementasi berikut:

Aplikasi objek EXE yang digunakan sebagai kontainer dan server, dan yang mendukung penyisipan objek ke dalam dirinya sendiri. Untuk kasus ini, CreateEmbeddingHelper memungkinkan objek untuk mendukung antarmuka yang biasanya hanya didukung di handler. Untuk mencapai hal ini, aplikasi harus terlebih dahulu mendaftarkan CLSID-nya untuk konteks yang berbeda, melakukan dua panggilan pendaftaran ke fungsi CoRegisterClassObject , bukan satu, sebagai berikut:
```
CoRegisterClassObject(clsidMe, pUnkCfLocal, CLSCTX_LOCAL_SERVER, 
        REGCLS_MULTI_SEPARATE...) 
 
    CoRegisterClassObject(clsidMe, pUnkCfInProc, CLSCTX_INPROC_SERVER, 
    
        REGCLS_MULTI_SEPARATE...) 
```
Dalam panggilan ini, Anda akan meneruskan implementasi pabrik kelas yang berbeda ke masing-masing pUnkCfLocal dan pUnkCfInProc. Pabrik kelas yang ditunjukkan oleh pUnkCfLocal akan digunakan untuk membuat objek yang akan disematkan dalam proses jarak jauh, yang merupakan kasus normal yang menggunakan objek handler yang terkait dengan klien. Namun, ketika server membuat objek dan menyematkannya dalam dirinya sendiri, pUnkCfInProc menunjuk ke objek kelas yang dapat membuat objek yang mendukung antarmuka handler. Kelas lokal digunakan untuk membuat objek dan kelas dalam proses membuat pembantu penyematan, meneruskan penunjuk ke pabrik kelas objek pertama di pCF.
Handler objek dalam proses kustom, dalam hal ini, DLL membuat pembantu penyematan dengan meneruskan penunjuk ke implementasi privat IClassFactory di pCF.

Parameter bendera menunjukkan bagaimana pembantu penyematan akan digunakan dan bagaimana dan kapan pembantu penyematan diinisialisasi. Nilai untuk bendera diperoleh dengan nilai bersama-sama OR dari tabel berikut.

Nilai untuk Parameter bendera	Tujuan
EMBDHLP_INPROC_HANDLER	Membuat pembantu penyematan yang dapat digunakan dengan aplikasi objek DLL; secara khusus, pembantu mengekspos fitur penembolokan dari handler objek default.
EMBDHLP_INPROC_SERVER	Membuat pembantu penyematan yang akan digunakan sebagai bagian dari server dalam proses. pCF tidak boleh NULL.
EMBDHLP_CREATENOW	Membuat objek sekunder menggunakan pCF segera; jika pCF NULL, manajer proksi standar digunakan.
EMBDHLP_DELAYCREATE	Menunda pembuatan objek sekunder hingga diperlukan (ketika pembantu dimasukkan ke dalam status berjalan) untuk meningkatkan kecepatan dan penggunaan memori. pCF tidak boleh NULL. Bendera EMBDHLP_INPROC_HANDLER tidak dapat digunakan dengan bendera ini.

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	ole2.h
Pustaka	Ole32.lib
DLL	Ole32.dll
Set API	ext-ms-win-com-ole32-l1-1-5 (diperkenalkan dalam Windows 10, versi 10.0.15063)

Lihat juga

OleCreateDefaultHandler

Bagikan melalui