Fungsi OleCreateEx (ole2.h)

Artikel
08/25/2023

Memperluas fungsionalitas OleCreate dengan mendukung instansiasi objek yang lebih efisien dalam kontainer yang memerlukan penembolokan beberapa format presentasi atau data, alih-alih format tunggal yang didukung oleh OleCreate.

Sintaks

HRESULT OleCreateEx(
  [in]  REFCLSID        rclsid,
  [in]  REFIID          riid,
  [in]  DWORD           dwFlags,
  [in]  DWORD           renderopt,
  [in]  ULONG           cFormats,
  [in]  DWORD           *rgAdvf,
  [in]  LPFORMATETC     rgFormatEtc,
  [in]  IAdviseSink     *lpAdviseSink,
  [out] DWORD           *rgdwConnection,
  [in]  LPOLECLIENTSITE pClientSite,
  [in]  LPSTORAGE       pStg,
  [out] LPVOID          *ppvObj
);

Parameter

[in] rclsid

Mengidentifikasi kelas objek yang akan dibuat.

[in] riid

Referensi ke pengidentifikasi antarmuka objek yang akan dikembalikan.

[in] dwFlags

Nilai ini bisa 0 atau OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Nilai yang diambil dari enumerasi OLERENDER .

[in] cFormats

Ketika renderopt OLERENDER_FORMAT, menunjukkan jumlah struktur FORMATETC dalam array rgFormatEtc , yang harus setidaknya satu. Dalam semua kasus lain, parameter ini harus nol.

[in] rgAdvf

Ketika renderopt OLERENDER_FORMAT, menunjuk ke array elemen DWORD cFormats, yang masing-masing merupakan kombinasi nilai dari enumerasi ADVF . Setiap elemen array ini diteruskan sebagai parameter advf ke panggilan ke IOleCache::Cache atau IDataObject::D Advise, tergantung pada apakah pAdviseSinkNULL atau non-NULL (lihat di bawah). Dalam semua kasus lain, parameter ini harus NULL.

[in] rgFormatEtc

Saat renderopt OLERENDER_FORMAT, menunjuk ke array struktur FORMATETC cFormats. Ketika pAdviseSink adalah NULL, setiap elemen array ini diteruskan sebagai parameter pFormatEtc ke panggilan ke IOleCache::Cache objek. Ini mengisi cache data dan presentasi yang dikelola oleh penangan dalam proses objek (biasanya handler default) dengan presentasi atau data lain yang dapat di-cache. Ketika pAdviseSinknon-NULL, setiap elemen array ini diteruskan sebagai parameter pFormatEtc ke panggilan ke IDataObject::D Advise. Ini memungkinkan pemanggil (biasanya Kontainer OLE) untuk melakukan penembolokan atau pemrosesan data sendiri yang diterima dari objek . Dalam semua kasus lain, parameter ini harus NULL.

[in] lpAdviseSink

Saat renderopt OLERENDER_FORMAT, mungkin penunjuk IAdviseSink yang valid, menunjukkan penembolokan kustom atau pemrosesan saran data, atau NULL, yang menunjukkan penembolokan default format data. Dalam semua kasus lain, parameter ini harus NULL.

[out] rgdwConnection

Lokasi untuk mengembalikan array nilai dwConnection yang dikembalikan ketika antarmuka pAdviseSink didaftarkan untuk setiap koneksi saran menggunakan IDataObject::D Advise, atau NULL jika koneksi saran yang dikembalikan tidak diperlukan. Harus NULL, jika pAdviseSinkADALAH NULL.

[in] pClientSite

Arahkan ke antarmuka utama tempat objek akan meminta layanan dari kontainernya. Parameter ini mungkin NULL, dalam hal ini adalah tanggung jawab pemanggil untuk membuat situs klien sesegera mungkin menggunakan IOleObject::SetClientSite.

[in] pStg

Arahkan ke penyimpanan yang akan digunakan untuk objek dan data default atau penembolokan presentasi yang dibuat untuk objek tersebut. Parameter ini mungkin bukan NULL.

[out] ppvObj

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

Nilai kembali

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

Menampilkan kode	Deskripsi
E_NOINTERFACE	Pengidentifikasi antarmuka yang disediakan tidak valid.

Keterangan

Panggilan berikut ke OleCreate:

OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

setara dengan panggilan berikut ke OleCreateEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateEx(rclsid, riid, renderopt, 1, &amp;advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

Fungsi instansiasi yang ada, (OleCreate, OleCreateFromFile, OleCreateFromData, OleCreateLink, OleCreateLinkToFile, dan OleCreateLinkFromData) hanya membuat satu presentasi atau cache format data di lokasi cache default (dalam aliran '\001OlePresXXX' dari IStorage yang diteruskan), selama instansiasi. Plus, cache ini harus dibuat ketika objek berikutnya memasuki status berjalan. Karena sebagian besar aplikasi memerlukan penembolokan setidaknya dua presentasi (layar dan printer) dan mungkin memerlukan penembolokan data dalam format atau lokasi yang berbeda dari handler, aplikasi biasanya harus meluncurkan dan mematikan server objek beberapa kali untuk mem-primer cache data mereka selama pembuatan objek, yaitu, Sisipkan Objek, Sisipkan Objek dari File, dan Tempel Objek.

Versi yang diperluas dari fungsi pembuatan ini menyelesaikan masalah ini. OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, dan OleCreateLinkFromDataEx berisi parameter baru berikut: dwFlags untuk menunjukkan opsi tambahan, cFormats untuk menunjukkan berapa banyak format yang akan di-cache, rgAdvf, dari enumerasi ADVF , untuk menentukan bendera saran untuk setiap format yang akan di-cache, pAdviseSink untuk menunjukkan apakah penembolokan presentasi (penanganan default) atau data (non-default-handler) diperlukan, rgdwConnection untuk mengembalikan cookie IDataObject::D Advise , dan pFormatEtc, array format daripada satu format.

Kontainer yang mengharuskan beberapa presentasi di-cache atas nama mereka oleh handler objek cukup memanggil fungsi-fungsi ini dan menentukan jumlah format dalam cFormats, bendera ADVF untuk setiap format di rgAdvf, dan serangkaian format dalam pFormatEtc. Kontainer ini melewati NULL untuk pAdviseSink.

Kontainer yang melakukan semua data atau penembolokan presentasi mereka sendiri melakukan langkah-langkah yang sama ini, tetapi meneruskan pAdviseSinknon-NULL. Mereka melakukan penembolokan atau manipulasi objek atau data mereka sendiri selama IAdviseSink::OnDataChange. Biasanya kontainer tersebut tidak pernah membangun koneksi nasihat dengan ADVF_NODATA, meskipun tidak dicegah untuk melakukannya.

Fungsi baru ini untuk Dokumen Gabungan OLE. Dengan menggunakan fungsi ini, aplikasi dapat menghindari langkah-langkah peluncuran dan inisialisasi berulang yang diperlukan oleh fungsi saat ini. Mereka ditargetkan pada aplikasi kontainer Dokumen Majemuk OLE yang menggunakan data default- dan penembolokan presentasi, dan juga pada aplikasi yang menyediakan penembolokan dan transfer data mereka sendiri dari dukungan IDataObject::D Advise yang mendasar.

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