Fungsi StgCreateDocfileOnILockBytes (coml2api.h)

Artikel
08/22/2023

Fungsi StgCreateDocfileOnILockBytes membuat dan membuka objek penyimpanan file majemuk baru di atas objek byte-array yang disediakan oleh pemanggil. Objek penyimpanan mendukung implementasi com-provided, compound-file untuk antarmuka IStorage .

Sintaks

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parameter

[in] plkbyt

Penunjuk ke antarmuka ILockBytes pada objek byte-array yang mendasar untuk membuat file majemuk.

[in] grfMode

Menentukan mode akses yang akan digunakan saat membuka file gabungan baru. Untuk informasi selengkapnya, lihat Konstanta STGM dan bagian Keterangan di bawah ini.

[in] reserved

Dicadangkan untuk digunakan di masa mendatang; harus nol.

[out] ppstgOpen

Penunjuk ke lokasi penunjuk IStorage pada objek penyimpanan baru.

Nilai kembali

Fungsi StgCreateDocfileOnILockBytes juga dapat mengembalikan kesalahan sistem file apa pun, atau kesalahan sistem yang dibungkus dalam nilai pengembalian kesalahan antarmuka HRESULT, atau ILockBytes . Untuk informasi selengkapnya, lihat Strategi Penanganan Kesalahan dan Menangani Kesalahan yang Tidak Diketahui.

Keterangan

Fungsi StgCreateDocfileOnILockBytes membuat objek penyimpanan di atas objek array byte menggunakan implementasi file majemuk yang disediakan COM dari antarmuka IStorage . StgCreateDocfileOnILockBytes dapat digunakan untuk menyimpan dokumen di penyimpanan data arbitrer, seperti memori atau database relasional. Array byte (ditunjukkan oleh parameter pLkbyt , yang menunjuk ke antarmuka ILockBytes pada objek) digunakan untuk penyimpanan yang mendasar sebagai pengganti file disk.

Kecuali untuk menentukan objek byte-array yang disediakan programmer, StgCreateDocfileOnILockBytes mirip dengan fungsi StgCreateDocfile .

File campuran yang baru dibuat dibuka sesuai dengan mode akses dalam parameter grfMode , tunduk pada batasan berikut:

Perilaku mode berbagi dan isolasi transaksional bergantung pada implementasi ILockBytes yang mendukung LockRegion dan UnlockRegion dengan semantik LOCK_ONLYONCE . Implementasi dapat menunjukkan penyimpanan terstruktur, mereka mendukung fungsionalitas ini dengan mengatur bit LOCK_ONLYONCE di anggota STATSTGyang didukung grfLocksSupported. Jika implementasi ILockBytes tidak mendukung fungsionalitas ini, mode berbagi tidak akan diberlakukan, dan penerapan transaksional tingkat akar tidak akan berkoordinasi dengan benar dengan instans transaksional lain yang dibuka pada array byte yang sama. Aplikasi yang menggunakan implementasi ILockBytes yang tidak mendukung penguncian wilayah, seperti implementasi CreateStreamOnHGlobal , harus menghindari pembukaan beberapa instans bersamaan pada array byte yang sama.

StgCreateDocfileOnILockBytes tidak mendukung mode sederhana. Bendera STGM_SIMPLE , jika ada, diabaikan.

Untuk tujuan konversi, file dianggap sudah ada. Akibatnya, tidak berguna untuk menggunakan nilai STGM_FAILIFTHERE , karena menyebabkan kesalahan dikembalikan. Namun, baik STGM_CREATE maupun STGM_CONVERT tetap berguna.

Kemampuan untuk membangun file majemuk di atas objek byte-array disediakan untuk mendukung memiliki data (di bawah struktur pohon IStorage dan IStream ) hidup di ruang yang tidak konsisten. Mengingat kemampuan ini, tidak ada yang mencegah dokumen yang disimpan dalam file untuk menggunakan fasilitas ini. Misalnya, kontainer mungkin melakukan ini untuk meminimalkan dampak pada format filenya yang disebabkan oleh adopsi COM. Namun, disarankan agar dokumen COM mengadopsi antarmuka IStorage untuk penyimpanan tingkat luar mereka sendiri. Ini memiliki keuntungan berikut:

Struktur penyimpanan dokumen sama dengan struktur penyimpanannya ketika merupakan objek yang disematkan, mengurangi jumlah kasus yang perlu ditangani aplikasi.
Seseorang dapat menulis alat untuk mengakses objek yang disematkan dan ditautkan OLE dalam dokumen tanpa pengetahuan khusus tentang format file dokumen. Contoh alat tersebut adalah utilitas salinan yang menyalin semua dokumen yang disertakan dalam kontainer yang berisi objek yang ditautkan. Utilitas salinan seperti ini memerlukan akses ke tautan yang terkandung untuk menentukan jangkauan file yang akan disalin.
Implementasi IStorage mengatasi masalah cara menerapkan perubahan pada file. Aplikasi yang menggunakan antarmuka ILockBytes harus menangani masalah ini sendiri.

Persyaratan

Persyaratan	Nilai
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	coml2api.h (termasuk Objbase.h)
Pustaka	Ole32.lib
DLL	Ole32.dll

Lihat juga

StgCreateDocfile

Share via