Fungsi StgCreateStorageEx (coml2api.h)

Fungsi StgCreateStorageEx membuat objek penyimpanan baru menggunakan implementasi yang disediakan untuk IStorage atau antarmuka 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.

Sintaksis

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 menjadi nama relatif atau NULL. Jika NULL, file sementara dialokasikan dengan nama unik. Jika non-NULL, ukuran string tidak boleh melebihi karakter MAX_PATH.

Windows 2000: Tidak seperti fungsi CreateFile, Anda tidak dapat 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	Arti
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 yang mendasar, operasi ini akan gagal.
Semua nilai lain dari stgfmt	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. JikaNULL non-, 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, lihatSTGOPTIONS .

[in] pSecurityDescriptor

Memungkinkan ACL diatur saat file dibuat. Jika tidak 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) 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.

Komentar

Ketika aplikasi memodifikasi filenya, aplikasi 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 untuk 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 bergantung 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 kumpulan properti NTFS, aturan berbagi khusus berlaku. Untuk informasi selengkapnya, lihatImplementasi IPropertySetStorage-NTFS .

Jika file majemuk dibuat dalam mode yang ditransaksikan (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 menerapkan perubahan tersebut dengan memanggil IStorage::Commit. Oleh karena itu, perubahan tersebut akan hilang.

Menentukan STGM_SIMPLE menyediakan implementasi objek file mampul yang jauh lebih cepat dalam kasus yang terbatas, tetapi sering digunakan yang melibatkan aplikasi yang memerlukan implementasi file gabungan 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 pada IStorage. Secara khusus, dalam mode sederhana, metode IStorage yang didukung adalah CreateStream, Commit, 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 IStorage mengembalikan STG_E_INVALIDFUNCTION.

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

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

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	coml2api.h (termasuk Objbase.h)
Pustaka	Ole32.lib
DLL	Ole32.dll

Lihat juga

CreateFile

STGFMT

Konstanta STGM

STGOPTIONS

StgCreateDocFileOnILockBytes

StgCreateDocfile

StgOpenStorageEx

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2023-08-22