Fungsi StgCreateStorageEx (coml2api.h)

Artikel
08/22/2023

Fungsi StgCreateStorageEx membuat objek penyimpanan baru menggunakan implementasi yang disediakan untuk antarmuka IStorage atau IPropertySetStorage . Untuk membuka file yang ada, gunakan fungsi StgOpenStorageEx sebagai gantinya.

Aplikasi yang ditulis untuk Windows 2000, Windows Server 2003 dan Windows XP harus menggunakan StgCreateStorageEx daripada StgCreateDocfile untuk memanfaatkan fitur Windows 2000 dan Windows XP Structured Storage yang ditingkatkan.

Sintaks

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

Parameter

[in] pwcsName

Penunjuk ke jalur file yang akan dibuat. Ini diteruskan tanpa diinterpretasikan ke sistem file. Ini bisa berupa nama relatif atau NULL. Jika NULL, file sementara dialokasikan dengan nama unik. Jika non-NULL, ukuran string tidak boleh melebihi MAX_PATH karakter.

Windows 2000: Tidak seperti fungsi CreateFile , Anda tidak boleh melebihi batas MAX_PATH dengan menggunakan awalan "\?".

[in] grfMode

Nilai yang 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] stgfmt

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

[in] grfAttrs

Nilai yang bergantung pada nilai parameter stgfmt .

Nilai Parameter	Makna
STGFMT_DOCFILE	0, atau FILE_FLAG_NO_BUFFERING. Untuk informasi selengkapnya, lihat CreateFile. Jika ukuran sektor file, yang ditentukan dalam pStgOptions, bukan kelipatan bilangan bulat dari ukuran sektor fisik disk dasar, operasi ini akan gagal.
*Semua nilai stgfmt* lainnya**	Harus 0.

[in] pStgOptions

Parameter pStgOptions hanya valid jika parameter stgfmt diatur ke STGFMT_DOCFILE. Jika parameter stgfmt diatur ke STGFMT_DOCFILE, pStgOptions menunjuk ke struktur STGOPTIONS , yang menentukan fitur objek penyimpanan, seperti ukuran sektor. Parameter ini mungkin NULL, yang membuat objek penyimpanan dengan ukuran sektor default 512 byte. Jika non-NULL, anggota ulSectorSize harus diatur ke 512 atau 4096. Jika diatur ke 4096, STGM_SIMPLE mungkin tidak ditentukan dalam parameter grfMode . Anggota usVersion harus diatur sebelum memanggil StgCreateStorageEx. Untuk informasi selengkapnya, lihat STGOPTIONS.

[in] pSecurityDescriptor

Memungkinkan ACL diatur saat file dibuat. Jika bukan NULL, perlu menjadi penunjuk ke struktur SECURITY_ATTRIBUTES . Lihat CreateFile untuk informasi tentang cara mengatur ACL pada file.

Windows Server 2003, Windows 2000 Server, Windows XP, dan Windows 2000 Professional: Nilai harus NULL.

[in] riid

Nilai yang menentukan pengidentifikasi antarmuka (IID) dari penunjuk antarmuka yang akan dikembalikan. IID ini mungkin untuk antarmuka IStorage atau antarmuka IPropertySetStorage .

[out] ppObjectOpen

Penunjuk ke variabel penunjuk antarmuka yang menerima pointer untuk antarmuka pada objek penyimpanan baru; 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

Ketika aplikasi memodifikasi filenya, biasanya membuat salinan aslinya. Fungsi StgCreateStorageEx adalah salah satu cara untuk membuat salinan. Fungsi ini bekerja secara tidak langsung dengan API duplikasi Encrypting File System (EFS). Ketika Anda menggunakan fungsi ini, Anda harus mengatur opsi untuk penyimpanan file dalam struktur STGOPTIONS .

StgCreateStorageEx adalah superset dari fungsi StgCreateDocfile , dan harus digunakan oleh kode baru. Penyempurnaan di masa mendatang ke Penyimpanan Terstruktur akan diekspos melalui fungsi StgCreateStorageEx . Lihat bagian Persyaratan berikut untuk informasi tentang platform yang didukung.

Fungsi StgCreateStorageEx membuat objek penyimpanan baru menggunakan salah satu implementasi penyimpanan terstruktur yang disediakan sistem. Fungsi ini dapat digunakan untuk mendapatkan
Implementasi file majemuk IStorage, implementasi file majemuk IPropertySetStorage, atau untuk mendapatkan implementasi IPropertySetStorage NTFS.

Saat file baru dibuat, implementasi penyimpanan yang digunakan tergantung pada bendera yang Anda tentukan dan pada jenis drive tempat file disimpan. Untuk informasi selengkapnya, lihat enumerasi STGFMT .

StgCreateStorageEx 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 tentang nilai-nilai ini, lihat Konstanta STGM. Ini tidak valid, dalam mode langsung, untuk menentukan mode STGM_READ dalam parameter grfMode (mode langsung ditunjukkan dengan tidak menentukan bendera STGM_TRANSACTED). Fungsi ini tidak dapat digunakan untuk membuka file yang ada; gunakan fungsi StgOpenStorageEx sebagai gantinya.

Anda dapat menggunakan fungsi StgCreateStorageEx untuk mendapatkan akses ke penyimpanan akar dokumen penyimpanan terstruktur atau penyimpanan kumpulan properti dari file apa pun yang mendukung set properti. Lihat dokumentasi STGFMT untuk informasi tentang IID mana yang didukung untuk nilai STGFMT yang berbeda.

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

Jika file majemuk dibuat dalam mode bertransaksi (dengan menentukan STGM_TRANSACTED) dan mode baca-saja (dengan menentukan STGM_READ), dimungkinkan untuk membuat perubahan pada 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.

Menentukan STGM_SIMPLE menyediakan implementasi yang jauh lebih cepat dari objek file campuran dalam kasus yang terbatas, tetapi sering digunakan yang melibatkan aplikasi yang memerlukan implementasi file campuran dengan beberapa aliran dan tanpa penyimpanan. Untuk informasi selengkapnya, lihat Konstanta STGM. Tidak valid untuk menentukan bahwa STGM_TRANSACTED jika STGM_SIMPLE ditentukan.

Mode sederhana tidak mendukung semua metode di IStorage. Secara khusus, dalam mode sederhana, metode IStorage yang didukung adalah CreateStream, Commit, dan SetClass serta metode COM IUnknown QueryInterface, AddRef dan Release. Selain itu, SetElementTimes didukung dengan nama NULL , memungkinkan aplikasi untuk mengatur waktu pada penyimpanan root. Semua metode lain dari IStorage mengembalikan STG_E_INVALIDFUNCTION.

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 untuk direktori sistem file tempat file campuran dibuat. Jika STGM_TRANSACTED tidak ditentukan, dan STGM_CREATE ditentukan, file yang ada dengan nama yang sama akan dihancurkan sebelum membuat file baru.

Anda juga dapat menggunakan StgCreateStorageEx untuk membuat file gabungan sementara dengan meneruskan nilai NULL untuk parameter pwcsName . Namun, file-file ini bersifat sementara hanya dalam arti bahwa file tersebut memiliki nama unik yang disediakan sistem - file yang mungkin tidak berarti bagi pengguna. Pemanggil bertanggung jawab untuk menghapus file sementara setelah selesai, kecuali STGM_DELETEONRELEASE ditentukan untuk parameter grfMode . Untuk informasi selengkapnya tentang bendera ini, lihat Konstanta STGM.

Persyaratan


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