Fungsi StgOpenStorage (coml2api.h)

Artikel
08/22/2023

Fungsi StgOpenStorage membuka objek penyimpanan akar yang ada dalam sistem file. Gunakan fungsi ini untuk membuka file campuran. Jangan gunakan untuk membuka direktori, file, atau katalog ringkasan. Objek penyimpanan berlapis hanya dapat dibuka menggunakan metode IStorage induknya::OpenStorage .

Catatan Aplikasi harus menggunakan fungsi baru, StgOpenStorageEx, alih-alih StgOpenStorage, untuk memanfaatkan fitur Penyimpanan Terstruktur Windows dan yang ditingkatkan. Fungsi ini, StgOpenStorage, masih ada untuk kompatibilitas dengan aplikasi yang berjalan pada Windows 2000.

Sintaks

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Parameter

[in] pwcsName

Penunjuk ke jalur file string Unicode yang dihentikan null yang berisi objek penyimpanan untuk dibuka. Parameter ini diabaikan jika parameter pstgPriority bukan NULL.

[in] pstgPriority

Penunjuk ke antarmuka IStorage yang seharusnya NULL. Jika bukan NULL, parameter ini digunakan seperti yang dijelaskan di bawah ini di bagian Keterangan.

Setelah StgOpenStorage kembali, objek penyimpanan yang ditentukan dalam pStgPriority mungkin telah dirilis dan tidak boleh lagi digunakan.

[in] grfMode

Menentukan mode akses yang akan digunakan untuk membuka objek penyimpanan.

[in] snbExclude

Jika bukan NULL, arahkan ke blok elemen dalam penyimpanan yang akan dikecualikan saat objek penyimpanan dibuka. Pengecualian terjadi terlepas dari apakah salinan rekam jepret terjadi di tempat terbuka. Bisa NULL.

[in] reserved

Menunjukkan dicadangkan untuk digunakan di masa mendatang; harus nol.

[out] ppstgOpen

Penunjuk ke variabel pointer IStorage* yang menerima penunjuk antarmuka ke penyimpanan yang dibuka.

Nilai kembali

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

Keterangan

Fungsi StgOpenStorage membuka objek penyimpanan akar yang ditentukan sesuai dengan mode akses dalam parameter grfMode , dan, jika berhasil, memasok penunjuk IStorage ke objek penyimpanan yang dibuka dalam parameter ppstgOpen .

Untuk mendukung mode sederhana untuk menyimpan objek penyimpanan tanpa substorase, fungsi StgOpenStorage 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 berlaku untuk pembaca.

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

Dalam mode langsung, salah satu dari tiga kombinasi berikut valid.

    STGM_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE

Catatan Membuka objek penyimpanan dalam mode baca/tulis tanpa menolak izin tulis ke orang lain (parameter grfMode menentukan STGM_SHARE_DENY_WRITE) dapat menjadi operasi yang memakan waktu karena panggilan StgOpenStorage harus membuat rekam jepret dari seluruh objek penyimpanan.

Aplikasi sering mencoba membuka objek penyimpanan dengan izin akses berikut. Jika aplikasi berhasil, aplikasi tidak perlu membuat salinan rekam jepret.

STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

Aplikasi dapat kembali menggunakan izin dan membuat salinan rekam jepret, jika izin akses sebelumnya gagal. Aplikasi harus meminta pengguna sebelum membuat salinan yang memakan waktu.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition

Jika semantik berbagi dokumen yang tersirat oleh mode akses sesuai, aplikasi dapat mencoba membuka penyimpanan sebagai berikut. Dalam hal ini, jika aplikasi berhasil, salinan rekam jepret tidak akan dibuat (karena STGM_SHARE_DENY_WRITE ditentukan, menolak akses tulis orang lain).

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

Catatan Untuk mengurangi pengeluaran membuat salinan rekam jepret, aplikasi dapat membuka objek penyimpanan dalam mode prioritas (grfMode menentukan STGM_PRIORITY).

Parameter snbExclude menentukan sekumpulan nama elemen dalam objek penyimpanan ini yang akan dikosongkan saat objek penyimpanan dibuka: aliran diatur ke panjang nol; objek penyimpanan menghapus semua elemennya. Dengan mengecualikan aliran tertentu, biaya pembuatan salinan rekam jepret dapat berkurang secara signifikan. Hampir selalu, pendekatan ini digunakan setelah pertama kali membuka objek penyimpanan dalam mode prioritas, kemudian sepenuhnya membaca elemen yang sekarang dikecualikan ke dalam memori. Pembukaan mode prioritas sebelumnya dari objek penyimpanan ini harus diteruskan melalui parameter pstgPriority untuk menghapus pengecualian yang disiratkan oleh mode prioritas. Aplikasi panggilan bertanggung jawab untuk menulis ulang konten item yang dikecualikan sebelum melakukan. Dengan demikian, teknik ini kemungkinan besar hanya berguna untuk aplikasi yang dokumennya tidak memerlukan akses konstan ke objek penyimpanan mereka saat aktif.

Parameter pstgPriority dimaksudkan sebagai kenyamanan bagi penelepon yang menggantikan objek penyimpanan yang ada, sering kali satu dibuka dalam mode prioritas, dengan objek penyimpanan baru dibuka pada file yang sama tetapi dalam mode yang berbeda. Ketika pstgPriority bukan NULL, pstgPriority digunakan untuk menentukan nama file alih-alih pwcsName, yang diabaikan. Namun, disarankan agar aplikasi selalu meneruskan NULL untuk pstgPriority karena StgOpenStorage merilis objek dalam beberapa keadaan, dan tidak merilisnya dalam keadaan lain. Secara khusus, jika fungsi mengembalikan hasil kegagalan, pemanggil tidak dapat menentukan apakah objek penyimpanan dirilis atau tidak.

Fungsionalitas parameter pstgPriority dapat diduplikasi oleh pemanggil dengan cara yang lebih aman seperti yang ditunjukkan dalam contoh berikut:

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &amp;pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority-&gt;Stat(&amp;statstg, 0);
pStgPriority-&gt;Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &amp;pstgNew);
}

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

IStorage

StgCreateDocfile

StgOpenStorageEx