Fungsi StgCreateDocfile (coml2api.h)

Artikel
08/22/2023

Fungsi StgCreateDocfile membuat objek penyimpanan file campuran baru menggunakan implementasi file campuran yang disediakan COM untuk antarmuka IStorage .

Catatan Aplikasi harus menggunakan fungsi baru, StgCreateStorageEx, alih-alih StgCreateDocfile, untuk memanfaatkan fitur Penyimpanan Terstruktur yang ditingkatkan. Fungsi ini, StgCreateDocfile, masih ada untuk kompatibilitas dengan Windows 2000.

Sintaks

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parameter

[in] pwcsName

Penunjuk ke nama string Unicode yang dihentikan null untuk file gabungan yang sedang dibuat. Ini diteruskan tanpa diinterpretasikan ke sistem file. Ini bisa berupa nama relatif atau NULL. Jika NULL, file campuran sementara dialokasikan dengan nama unik.

[in] grfMode

Menentukan mode akses yang akan digunakan saat membuka objek penyimpanan baru. Untuk informasi selengkapnya, lihat Konstanta STGM. Jika penelepon menentukan mode yang ditransaksikan bersama dengan STGM_CREATE atau STGM_CONVERT, penimpaan atau konversi terjadi saat operasi penerapan dipanggil untuk penyimpanan akar. Jika IStorage::Commit tidak dipanggil untuk objek penyimpanan akar, konten file sebelumnya akan dipulihkan. STGM_CREATE dan STGM_CONVERT tidak dapat dikombinasikan dengan bendera STGM_NOSNAPSHOT, karena salinan rekam jepret diperlukan saat file ditimpa atau dikonversi dalam mode yang ditransaksikan.

[in] reserved

Dicadangkan untuk digunakan di masa mendatang; harus nol.

[out] ppstgOpen

Penunjuk ke lokasi penunjuk IStorage ke objek penyimpanan baru.

Nilai kembali

StgCreateDocfile juga dapat mengembalikan kesalahan sistem file atau kesalahan sistem yang dibungkus dalam HRESULT. Untuk informasi selengkapnya, lihat Strategi Penanganan Kesalahan dan Menangani Kesalahan yang Tidak Diketahui.

Keterangan

Fungsi StgCreateDocfile membuat objek penyimpanan baru menggunakan implementasi com-provided, compound-file untuk antarmuka IStorage . Nama file gabungan terbuka dapat diambil dengan memanggil metode IStorage::Stat .

StgCreateDocfile membuat file jika tidak ada. Jika memang ada, penggunaan bendera STGM_CREATE, STGM_CONVERT, dan STGM_FAILIFTHERE dalam parameter grfMode menunjukkan cara melanjutkan. Untuk informasi selengkapnya, lihat Konstanta STGM.

Jika file majemuk dibuka dalam mode yang ditransaksikan (parameter grfMode menentukan STGM_TRANSACTED) dan file dengan nama ini sudah ada, file yang ada tidak diubah sampai semua perubahan luar biasa dilakukan. Jika proses panggilan tidak memiliki akses tulis ke file yang ada (karena kontrol akses dalam sistem file), parameter grfMode hanya dapat menentukan STGM_READ dan tidak STGM_WRITE atau STGM_READWRITE. File majemuk terbuka baru yang dihasilkan masih dapat ditulis, tetapi operasi penerapan berikutnya akan gagal (dalam mode bertransaksi, izin tulis diberlakukan pada waktu penerapan).

Menentukan STGM_SIMPLE menyediakan implementasi objek file mabuk yang jauh lebih cepat dalam kasus yang terbatas, tetapi sering digunakan. Ini dapat digunakan oleh aplikasi yang memerlukan implementasi file campuran dengan beberapa aliran dan tanpa penyimpanan. Mode sederhana tidak mendukung semua metode di IStorage. Untuk informasi selengkapnya, lihat Konstanta STGM.

Jika parameter grfMode menentukan STGM_TRANSACTED dan belum ada file dengan nama yang ditentukan oleh parameter pwcsName , file segera dibuat. Dalam sistem file yang dikontrol akses, pemanggil harus memiliki izin tulis di direktori sistem file tempat file gabungan dibuat. Jika STGM_TRANSACTED tidak ditentukan, dan STGM_CREATE ditentukan, file yang ada dengan nama yang sama akan dihancurkan sebelum file baru dibuat.

StgCreateDocfile dapat digunakan untuk membuat file gabungan sementara dengan meneruskan nilai NULL untuk parameter pwcsName . Namun, file-file ini bersifat sementara hanya dalam arti bahwa mereka memiliki nama unik yang disediakan sistem - kemungkinan file yang tidak berarti bagi pengguna. Pemanggil bertanggung jawab untuk menghapus file sementara setelah selesai, kecuali STGM_DELETEONRELEASE ditentukan untuk parameter grfMode .

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

Konstanta STGM

StgCreateDocFileOnILockBytes

StgCreateStorageEx

Bagikan melalui