Fungsi StgOpenStorageEx (coml2api.h)

Artikel
08/22/2023

Fungsi StgOpenStorageEx membuka objek penyimpanan akar yang ada dalam sistem file. Gunakan fungsi ini untuk membuka File Campuran dan file reguler. Untuk membuat file baru, gunakan fungsi StgCreateStorageEx .

Catatan Untuk menggunakan penyempurnaan, semua aplikasi Windows 2000, Windows XP, dan Windows Server 2003 harus memanggil StgOpenStorageEx, bukan StgOpenStorage. Fungsi StgOpenStorage digunakan untuk kompatibilitas dengan Windows 2000 dan aplikasi yang lebih lama.

Sintaks

HRESULT StgOpenStorageEx(
  [in]      const WCHAR          *pwcsName,
  [in]      DWORD                grfMode,
  [in]      DWORD                stgfmt,
  [in]      DWORD                grfAttrs,
  [in, out] STGOPTIONS           *pStgOptions,
  [in]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]      REFIID               riid,
  [out]     void                 **ppObjectOpen
);

Parameter

[in] pwcsName

Penunjuk ke jalur file string Unicode yang dihentikan null yang berisi objek penyimpanan. Ukuran string ini tidak boleh melebihi MAX_PATH karakter.

Windows Server 2003 dan Windows XP/2000: Tidak seperti fungsi CreateFile , batas MAX_PATH tidak dapat dilampaui dengan menggunakan awalan "\?".

[in] grfMode

Nilai yang menentukan mode akses untuk 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 bertransaksi.

Jika objek penyimpanan dibuka dalam mode langsung (STGM_DIRECT) dengan akses ke STGM_WRITE atau STGM_READWRITE, mode berbagi harus STGM_SHARE_EXCLUSIVE kecuali mode STGM_DIRECT_SWMR ditentukan. Untuk informasi lebih lanjut, lihat bagian Keterangan. Jika objek penyimpanan dibuka dalam mode langsung dengan akses ke STGM_READ, mode berbagi harus STGM_SHARE_EXCLUSIVE atau STGM_SHARE_DENY_WRITE, kecuali STGM_PRIORITY atau STGM_DIRECT_SWMR ditentukan. Untuk informasi lebih lanjut, lihat bagian Keterangan.

Mode di mana file dibuka dapat memengaruhi performa implementasi. Untuk informasi selengkapnya, lihat Batas Implementasi File Campuran.

[in] stgfmt

Nilai yang menentukan format file penyimpanan. Untuk informasi selengkapnya, lihat enumerasi STGFMT .

[in] grfAttrs

Nilai yang bergantung pada nilai parameter stgfmt .

STGFMT_DOCFILE harus nol (0) atau FILE_FLAG_NO_BUFFERING. Untuk informasi selengkapnya tentang nilai ini, lihat CreateFile. Jika ukuran sektor file, yang ditentukan dalam pStgOptions, bukan kelipatan bilangan bulat dari ukuran sektor fisik disk yang mendasar, maka operasi ini akan gagal. Semua nilai stgfmt lainnya harus nol.

[in, out] pStgOptions

Penunjuk ke struktur STGOPTIONS yang berisi data tentang objek penyimpanan yang dibuka. Parameter pStgOptions hanya valid jika parameter stgfmt diatur ke STGFMT_DOCFILE. Anggota usVersion harus diatur sebelum memanggil StgOpenStorageEx. Untuk informasi selengkapnya, lihat struktur STGOPTIONS .

[in] pSecurityDescriptor

Dipesan; harus nol.

[in] riid

Nilai yang menentukan GUID penunjuk antarmuka yang akan dikembalikan. Dapat juga menjadi nilai yang ditentukan header untuk IID_IStorage untuk mendapatkan antarmuka IStorage atau untuk IID_IPropertySetStorage untuk mendapatkan antarmuka IPropertySetStorage .

[out] ppObjectOpen

Alamat variabel penunjuk antarmuka yang menerima pointer untuk antarmuka pada objek penyimpanan yang dibuka; berisi NULL jika operasi gagal.

Mengembalikan nilai

Fungsi ini 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

StgOpenStorageEx adalah superset dari fungsi StgOpenStorage , dan harus digunakan oleh kode baru. Penyempurnaan di masa mendatang untuk penyimpanan terstruktur akan diekspos melalui fungsi ini. Untuk informasi selengkapnya tentang platform yang didukung, lihat bagian Persyaratan.

Fungsi StgOpenStorageEx membuka objek penyimpanan akar yang ditentukan sesuai dengan mode akses dalam parameter grfMode , dan, jika berhasil, memasok pointer antarmuka untuk objek penyimpanan yang dibuka di parameter ppObjectOpen . Fungsi ini dapat digunakan untuk mendapatkan implementasi file majemuk IStorage, implementasi file majemuk IPropertySetStorage, atau
Implementasi sistem file NTFS dari IPropertySetStorage.

Saat Anda membuka file, sistem memilih implementasi penyimpanan terstruktur tergantung pada bendera STGFMT mana yang Anda tentukan pada jenis file dan pada jenis drive tempat file disimpan.

Gunakan fungsi StgOpenStorageEx untuk mengakses penyimpanan akar dokumen penyimpanan terstruktur atau penyimpanan set properti dari file apa pun yang mendukung set properti. Untuk informasi selengkapnya tentang pengidentifikasi antarmuka (IID) mana yang didukung untuk nilai STGFMT yang berbeda, lihat STGFMT.

Ketika file dibuka dengan fungsi ini untuk mengakses implementasi set properti NTFS, aturan berbagi khusus berlaku. Untuk informasi selengkapnya, lihat Implementasi IPropertySetStorage-NTFS.

Jika file majemuk dibuka dalam mode bertransaksi, dengan menentukan STGM_TRANSACTED, dan mode baca-saja, dengan menentukan STGM_READ, dimungkinkan untuk mengubah objek penyimpanan yang dikembalikan. Misalnya, dimungkinkan untuk memanggil IStorage::CreateStream. Namun, tidak mungkin untuk melakukan perubahan tersebut dengan memanggil IStorage::Commit. Oleh karena itu, perubahan tersebut akan hilang.

Tidak valid untuk menggunakan bendera STGM_CREATE, STGM_DELETEONRELEASE, atau STGM_CONVERT dalam parameter grfMode untuk fungsi ini.

Untuk mendukung mode sederhana untuk menyimpan objek penyimpanan tanpa substorase, fungsi StgOpenStorageEx menerima salah satu dari dua kombinasi bendera berikut sebagai mode yang valid dalam parameter grfMode :

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

Untuk mendukung mode penulis tunggal, multireader, direct, kombinasi bendera pertama adalah parameter grfMode yang valid untuk penulis. Kombinasi bendera kedua valid untuk pembaca.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

Untuk informasi selengkapnya tentang mode sederhana dan mode penulis tunggal/beberapa pembaca, lihat Konstanta STGM.

Catatan Membuka objek penyimpanan mode yang ditransaksikan dalam mode baca dan/atau tulis tanpa menolak izin tulis ke orang lain (misalnya, parameter grfMode menentukan STGM_SHARE_DENY_WRITE) dapat memakan waktu karena panggilan StgOpenStorageEx harus membuat salinan rekam jepret dari seluruh objek penyimpanan.

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