Fungsi OleCreateFromFileEx (ole2.h)

Artikel
02/29/2024

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

Sintaks

HRESULT OleCreateFromFileEx(
  [in]  REFCLSID        rclsid,
  [in]  LPCOLESTR       lpszFileName,
  [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

Parameter ini dicadangkan dan harus CLSID_NULL.

[in] lpszFileName

Penunjuk ke nama file tempat objek baru harus diinisialisasi.

[in] riid

Referensi ke pengidentifikasi antarmuka objek yang akan dikembalikan.

[in] dwFlags

Parameter ini bisa 0 atau OLECREATE_LEAVERUNNING (0x00000001).

[in] renderopt

Nilai yang diambil dari enumerasi OLERENDER .

[in] cFormats

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

[in] rgAdvf

Saat renderopt OLERENDER_FORMAT, menunjuk ke array elemen DWORD , 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 pAdviseSink adalah NULL 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 . 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 handler 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 .

[in] lpAdviseSink

Saat renderopt OLERENDER_FORMAT, mungkin merupakan penunjuk IAdviseSink yang valid, yang menunjukkan penembolokan kustom atau pemrosesan saran data, atau NULL, yang menunjukkan penembolokan default format data.

[out] rgdwConnection

Lokasi untuk mengembalikan array nilai dwConnection yang dikembalikan ketika antarmuka pAdviseSink didaftarkan untuk setiap koneksi penasihat menggunakan IDataObject::D Advise, atau NULL jika koneksi saran yang dikembalikan tidak diperlukan. Parameter ini harus NULL jika pAdviseSink adalah 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.

[out] ppvObj

Alamat variabel penunjuk output yang menerima pointer antarmuka yang diminta dalam riid. Setelah berhasil dikembalikan, *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.
E_INVALIDARG	Satu atau beberapa parameter tidak valid.

Keterangan

Panggilan berikut ke OleCreateFromFile:

OleCreateFromFile(rclsid, lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

setara dengan panggilan berikut ke OleCreateFromFileEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &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 data penembolokan dalam format atau lokasi yang berbeda dari handler, aplikasi biasanya harus meluncurkan dan mematikan server objek beberapa kali untuk memandu 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 rgFormatEtc, array format daripada format tunggal.

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

Kontainer melakukan semua penembolokan data atau 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