Fungsi OleCreateLinkToFileEx (ole2.h)

Artikel
02/29/2024

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

Sintaks

HRESULT OleCreateLinkToFileEx(
  [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] lpszFileName

Arahkan ke nama file untuk membuat tautan.

[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

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

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 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 . 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 .

[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.

[out] rgdwConnection

Lokasi untuk mengembalikan array nilai dwConnection yang dikembalikan ketika antarmuka IAdviseSink 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 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.
E_INVALIDARG	Satu atau beberapa parameter tidak valid.

Keterangan

Panggilan berikut ke OleCreateLinkToFile:

OleCreateLinkToFile(lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

setara dengan panggilan berikut ke OleCreateLinkToFileEx:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateLinkToFileEx(lpszFileName, riid, renderopt, 1, &amp;advf, pFormatEtc, NULL, 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 rgFormatEtc, 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 rgFormatEtc. 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 kontainer tersebut 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