Konstanta STGM
Konstanta STGM adalah bendera yang menunjukkan kondisi untuk membuat dan menghapus objek dan mode akses untuk objek. Konstanta STGM disertakan dalam antarmuka IStorage, IStream, dan IPropertySetStorage dan dalam fungsi StgCreateDocfile, StgCreateStorageEx, StgCreateDocfileOnILockBytes, StgOpenStorage, dan StgOpenStorageEx .
Elemen-elemen ini sering digabungkan menggunakan operator OR. Mereka ditafsirkan dalam grup seperti yang tercantum dalam tabel berikut. Tidak valid untuk menggunakan lebih dari satu elemen dari satu grup.
Gunakan bendera dari grup pembuatan saat membuat objek, seperti dengan StgCreateStorageEx atau IStorage::CreateStream.
Untuk informasi selengkapnya tentang transaksi, lihat bagian Keterangan.
| Grup | Bendera | Nilai |
|---|---|---|
| Access | STGM_READ | 0x00000000L |
| STGM_WRITE | 0x00000001L | |
| STGM_READWRITE | 0x00000002L | |
| Berbagi | STGM_SHARE_DENY_NONE | 0x00000040L |
| STGM_SHARE_DENY_READ | 0x00000030L | |
| STGM_SHARE_DENY_WRITE | 0x00000020L | |
| STGM_SHARE_EXCLUSIVE | 0x00000010L | |
| STGM_PRIORITY | 0x00040000L | |
| Pembuatan | STGM_CREATE | 0x00001000L |
| STGM_CONVERT | 0x00020000L | |
| STGM_FAILIFTHERE | 0x00000000L | |
| Transaksi | STGM_DIRECT | 0x00000000L |
| STGM_TRANSACTED | 0x00010000L | |
| Performa Transaksi | STGM_NOSCRATCH | 0x00100000L |
| STGM_NOSNAPSHOT | 0x00200000L | |
| SWMR Langsung dan Sederhana | STGM_SIMPLE | 0x08000000L |
| STGM_DIRECT_SWMR | 0x00400000L | |
| Hapus Saat Rilis | STGM_DELETEONRELEASE | 0x04000000L |
-
STGM_READ
-
-
0x00000000L
-
Menunjukkan bahwa objek bersifat baca-saja, yang berarti bahwa modifikasi tidak dapat dilakukan. Misalnya, jika objek stream dibuka dengan STGM_READ, metode ISequentialStream::Read dapat dipanggil, tetapi metode ISequentialStream::Write mungkin tidak. Demikian pula, jika objek penyimpanan dibuka dengan STGM_READ, metode IStorage::OpenStream dan IStorage::OpenStorage dapat dipanggil, tetapi metode IStorage::CreateStream dan IStorage::CreateStorage mungkin tidak.
-
-
STGM_WRITE
-
-
0x00000001L
-
Memungkinkan Anda menyimpan perubahan pada objek, tetapi tidak mengizinkan akses ke datanya. Implementasi yang disediakan dari antarmuka IPropertyStorage dan IPropertySetStorage tidak mendukung mode tulis-saja ini.
-
-
STGM_READWRITE
-
-
0x00000002L
-
Memungkinkan akses dan modifikasi data objek. Misalnya, jika objek stream dibuat atau dibuka dalam mode ini, dimungkinkan untuk memanggil IStream::Read dan IStream::Write. Ketahuilah bahwa konstanta ini bukan biner SEDERHANA ATAU operasi elemen STGM_WRITE dan STGM_READ .
-
-
STGM_SHARE_DENY_NONE
-
-
0x00000040L
-
Menentukan bahwa pembukaan objek berikutnya tidak ditolak akses baca atau tulis. Jika tidak ada bendera dari grup berbagi yang ditentukan, bendera ini diasumsikan.
-
-
STGM_SHARE_DENY_READ
-
-
0x00000030L
-
Mencegah orang lain membuka objek dalam mode STGM_READ . Biasanya digunakan pada objek penyimpanan akar.
-
-
STGM_SHARE_DENY_WRITE
-
-
0x00000020L
-
Mencegah orang lain membuka objek untuk akses STGM_WRITE atau STGM_READWRITE . Dalam mode bertransaksi, berbagi STGM_SHARE_DENY_WRITE atau STGM_SHARE_EXCLUSIVE dapat secara signifikan meningkatkan performa karena tidak memerlukan rekam jepret. Untuk informasi selengkapnya tentang transaksi, lihat bagian Keterangan.
-
-
STGM_SHARE_EXCLUSIVE
-
-
0x00000010L
-
Mencegah orang lain membuka objek dalam mode apa pun. Ketahuilah bahwa nilai ini bukan operasi bitwise ATAU sederhana dari nilai STGM_SHARE_DENY_READ dan STGM_SHARE_DENY_WRITE . Dalam mode bertransaksi, berbagi STGM_SHARE_DENY_WRITE atau STGM_SHARE_EXCLUSIVE dapat secara signifikan meningkatkan performa karena tidak memerlukan rekam jepret. Untuk informasi selengkapnya tentang transaksi, lihat bagian Keterangan.
-
-
STGM_PRIORITY
-
-
0x00040000L
-
Membuka objek penyimpanan dengan akses eksklusif ke versi yang terakhir diterapkan. Dengan demikian, pengguna lain tidak dapat melakukan perubahan pada objek saat Anda membukanya dalam mode prioritas. Anda mendapatkan manfaat performa untuk operasi salin, tetapi Anda mencegah orang lain melakukan perubahan. Batasi waktu objek terbuka dalam mode prioritas. Anda harus menentukan STGM_DIRECT dan STGM_READ dengan mode prioritas, dan Anda tidak dapat menentukan STGM_DELETEONRELEASE. STGM_DELETEONRELEASE hanya valid saat membuat objek root, seperti dengan StgCreateStorageEx. Ini tidak valid saat membuka objek akar yang ada, seperti dengan StgOpenStorageEx. Ini juga tidak valid saat membuat atau membuka subelemen, seperti dengan IStorage::OpenStorage.
-
-
STGM_CREATE
-
-
0x00001000L
-
Menunjukkan bahwa objek penyimpanan atau aliran yang ada harus dihapus sebelum objek baru menggantikannya. Objek baru dibuat ketika bendera ini ditentukan hanya jika objek yang ada telah berhasil dihapus.
Bendera ini digunakan saat mencoba membuat:
- Objek penyimpanan pada disk, tetapi file nama tersebut ada.
- Objek di dalam objek penyimpanan, tetapi objek dengan nama yang ditentukan ada.
- Objek array byte, tetapi satu dengan nama yang ditentukan ada.
Bendera ini tidak dapat digunakan dengan operasi terbuka, seperti StgOpenStorageEx atau IStorage::OpenStream.
-
-
STGM_CONVERT
-
-
0x00020000L
-
Membuat objek baru sambil mempertahankan data yang ada dalam aliran bernama "Konten". Dalam kasus objek penyimpanan atau array byte, data lama diformat ke dalam aliran terlepas dari apakah file atau array byte yang ada saat ini berisi objek penyimpanan berlapis. Bendera ini hanya dapat digunakan saat membuat objek penyimpanan akar. Ini tidak dapat digunakan dalam objek penyimpanan; misalnya, di IStorage::CreateStream. Juga tidak valid untuk menggunakan bendera ini dan bendera STGM_DELETEONRELEASE secara bersamaan.
-
-
STGM_FAILIFTHERE
-
-
0x00000000L
-
Menyebabkan operasi pembuatan gagal jika ada objek dengan nama yang ditentukan. Dalam hal ini, STG_E_FILEALREADYEXISTS dikembalikan. Ini adalah mode pembuatan default; artinya, jika tidak ada bendera buat lain yang ditentukan, STGM_FAILIFTHERE tersirat.
-
-
STGM_DIRECT
-
-
0x00000000L
-
Menunjukkan bahwa, dalam mode langsung, setiap perubahan pada elemen penyimpanan atau aliran ditulis saat terjadi. Ini adalah default jika tidak ada STGM_DIRECT atau STGM_TRANSACTED yang ditentukan.
-
-
STGM_TRANSACTED
-
-
0x00010000L
-
Menunjukkan bahwa, dalam mode yang ditransaksikan, perubahan di-buffer dan ditulis hanya jika operasi penerapan eksplisit dipanggil. Untuk mengabaikan perubahan, panggil metode Kembalikan di antarmuka IStream, IStorage, atau IPropertyStorage . Implementasi file majemuk COM dari IStorage tidak mendukung aliran yang ditransaksikan, yang berarti bahwa aliran hanya dapat dibuka dalam mode langsung, dan Anda tidak dapat mengembalikan perubahan pada mereka, namun penyimpanan yang ditransaksikan didukung. Implementasi sistem file majemuk, berdiri sendiri, dan NTFS dari IPropertySetStorage juga tidak mendukung set properti sederhana yang ditransaksikan karena set properti ini disimpan dalam aliran. Namun, transaksi set properti nonsimple, yang dapat dibuat dengan menentukan bendera PROPSETFLAG_NONSIMPLE dalam parameter grfFlagsIPropertySetStorage::Create, didukung.
-
-
STGM_NOSCRATCH
-
-
0x00100000L
-
Menunjukkan bahwa, dalam mode yang ditransaksikan, file goresan sementara biasanya digunakan untuk menyimpan modifikasi hingga metode Penerapan dipanggil. Menentukan STGM_NOSCRATCH mengizinkan bagian file asli yang tidak digunakan untuk digunakan sebagai ruang kerja alih-alih membuat file baru untuk tujuan tersebut. Ini tidak memengaruhi data dalam file asli, dan dalam kasus tertentu dapat mengakibatkan peningkatan performa. Tidak valid untuk menentukan bendera ini tanpa juga menentukan STGM_TRANSACTED, dan bendera ini hanya dapat digunakan dalam akar terbuka. Untuk informasi selengkapnya tentang mode NoScratch, lihat bagian Keterangan.
-
-
STGM_NOSNAPSHOT
-
-
0x00200000L
-
Bendera ini digunakan saat membuka objek penyimpanan dengan STGM_TRANSACTED dan tanpa STGM_SHARE_EXCLUSIVE atau STGM_SHARE_DENY_WRITE. Dalam hal ini, menentukan STGM_NOSNAPSHOT mencegah implementasi yang disediakan sistem membuat salinan rekam jepret file. Sebagai gantinya, perubahan pada file ditulis ke akhir file. Ruang yang tidak digunakan tidak diklaim kembali kecuali konsolidasi dilakukan selama penerapan, dan hanya ada satu penulis saat ini pada file. Ketika file dibuka tanpa mode rekam jepret, operasi terbuka lain tidak dapat dilakukan tanpa menentukan STGM_NOSNAPSHOT. Bendera ini hanya dapat digunakan dalam operasi buka akar. Untuk informasi selengkapnya tentang mode NoSnapshot, lihat bagian Keterangan.
-
-
STGM_SIMPLE
-
-
0x08000000L
-
Menyediakan implementasi file campuran yang lebih cepat dalam kasus terbatas, tetapi sering digunakan. Untuk informasi lebih lanjut, lihat bagian Keterangan.
-
-
STGM_DIRECT_SWMR
-
-
0x00400000L
-
Mendukung mode langsung untuk operasi file penulis tunggal dan multireader. Untuk informasi lebih lanjut, lihat bagian Keterangan.
-
-
STGM_DELETEONRELEASE
-
-
0x04000000L
-
Menunjukkan bahwa file yang mendasar akan dihancurkan secara otomatis ketika objek penyimpanan akar dirilis. Fitur ini paling berguna untuk membuat file sementara. Bendera ini hanya dapat digunakan saat membuat objek root, seperti dengan StgCreateStorageEx. Ini tidak valid saat membuka objek root, seperti dengan StgOpenStorageEx, atau saat membuat atau membuka subelemen, seperti dengan IStorage::CreateStream. Juga tidak valid untuk menggunakan bendera ini dan bendera STGM_CONVERT secara bersamaan.
-
Keterangan
Anda dapat menggabungkan bendera ini, tetapi Anda hanya dapat memilih satu bendera dari setiap grup bendera terkait. Biasanya satu bendera dari setiap grup akses dan berbagi harus ditentukan untuk semua fungsi dan metode yang menggunakan konstanta ini. Bendera dari grup lain bersifat opsional.
Mode Bertransaksi
Saat bendera STGM_DIRECTditentukan, hanya salah satu kombinasi bendera berikut yang dapat ditentukan dari grup akses dan berbagi.
STGM_READ | STGM_SHARE_DENY_WRITE
STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_READ | STGM_PRIORITY
Ketahuilah bahwa mode langsung tersirat oleh tidak adanya STGM_TRANSACTED. Artinya, jika tidak ada STGM_DIRECT atau STGM_TRANSACTED yang ditentukan, STGM_DIRECT diasumsikan .
Saat bendera STGM_TRANSACTED ditentukan, objek dibuat atau dibuka dalam mode bertransaksi. Dalam mode ini, perubahan pada objek tidak bertahan sampai dilakukan. Misalnya, perubahan pada objek penyimpanan yang ditransaksikan tidak bertahan sampai metode IStorage::Commit dipanggil. Perubahan pada objek penyimpanan tersebut akan hilang jika objek penyimpanan dirilis (rilis akhir) sebelum metode Penerapan dipanggil, atau jika metode IStorage::Revert dipanggil.
Saat objek dibuat atau dibuka dalam mode bertransaksi, implementasi harus menyimpan data asli dan pembaruan untuk data ini, sehingga pembaruan dapat dikembalikan jika perlu. Ini biasanya dilakukan dengan menulis perubahan pada area goresan sampai dilakukan, atau dengan membuat salinan, yang disebut rekam jepret, dari data yang terakhir diterapkan.
Ketika objek penyimpanan akar dibuka dalam mode bertransaksi, lokasi dan perilaku data awal dan salinan rekam jepret dapat dikontrol untuk mengoptimalkan performa dengan bendera STGM_NOSCRATCH dan STGM_NOSNAPSHOT . (Objek penyimpanan akar diperoleh dari, misalnya, fungsi StgOpenStorageEx ; objek penyimpanan yang diperoleh dari metode IStorage::OpenStorage adalah objek substorage .) Biasanya, data coretan dan rekam jepret disimpan dalam file sementara, terpisah dari penyimpanan.
Efek dari bendera ini tergantung pada jumlah pembaca dan/atau penulis yang mengakses penyimpanan akar.
Dalam kasus "penulis tunggal", objek penyimpanan mode yang ditransaksikan dibuka untuk akses tulis dan tidak boleh ada akses lain ke file. Artinya, file dibuka dengan STGM_TRANSACTED, akses STGM_WRITE atau STGM_READWRITE, dan berbagi STGM_SHARE_EXCLUSIVE. Dalam hal ini, perubahan pada objek penyimpanan ditulis ke area coretan. Ketika perubahan tersebut diterapkan, perubahan tersebut disalin ke penyimpanan asli. Oleh karena itu, jika tidak ada perubahan yang benar-benar dilakukan pada objek penyimpanan, tidak akan ada transfer data yang tidak perlu.
Dalam kasus "multi-penulis", objek penyimpanan yang ditransaksikan dibuka untuk akses tulis, tetapi dibagikan seperti untuk memungkinkan penulis lain. Artinya, objek penyimpanan dibuka dengan STGM_TRANSACTED, akses STGM_WRITE atau STGM_READWRITE, dan berbagi STGM_SHARE_DENY_READ. Jika berbagi STGM_SHARE_DENY_NONE ditentukan sebagai gantinya, maka kasusnya adalah "multiple-writer, multiple-reader". Dalam kasus ini, rekam jepret data asli akan dibuat selama operasi terbuka. Oleh karena itu, bahkan jika tidak ada perubahan yang benar-benar dilakukan pada penyimpanan dan/atau sebenarnya tidak dibuka oleh penulis lain secara bersamaan, transfer data masih diperlukan selama pembukaan. Akibatnya performa open-time terbaik dapat diperoleh dengan membuka objek penyimpanan dalam mode STGM_SHARE_DENY_WRITE atau STGM_SHARE_EXCLUSIVE . Untuk informasi selengkapnya tentang bagaimana perubahan diterapkan ketika ada beberapa penulis, lihat IStorage::Commit.
Dalam kasus "penulis tunggal, beberapa pembaca", objek penyimpanan yang ditransaksikan dibuka untuk akses tulis, tetapi dibagikan dengan pembaca. Artinya, objek penyimpanan dibuka oleh penulis dengan STGM_TRANSACTED, akses STGM_READWRITE atau STGM_WRITE, dan berbagi STGM_SHARE_DENY_WRITE. Penyimpanan dibuka oleh pembaca dengan STGM_TRANSACTED, akses STGM_READ, dan berbagi STGM_SHARE_DENY_NONE. Dalam hal ini penulis menggunakan area coretan untuk menyimpan perubahan yang tidak dilakukan. Seperti dalam kasus di atas, pembaca dikenakan penalti performa open-time saat salinan rekam jepret data dibuat.
Biasanya, area coretan adalah file sementara, terpisah dari data asli. Ketika perubahan diterapkan pada file asli, data harus ditransfer dari file sementara. Untuk menghindari transfer data ini, bendera STGM_NOSCRATCHdapat ditentukan. Ketika bendera ini ditentukan, bagian dari file objek penyimpanan digunakan untuk area goresan, bukan file sementara terpisah. Akibatnya, menerapkan perubahan dapat dilakukan dengan cepat, karena sedikit transfer data yang diperlukan. Kerugiannya adalah bahwa file penyimpanan dapat menjadi lebih besar dari yang seharusnya, karena harus ditanam menjadi cukup besar untuk data asli dan area coretan. Untuk mengonsolidasikan data dan menghapus area yang tidak perlu ini, buka kembali penyimpanan akar dalam mode yang ditransaksikan, tetapi tanpa mengatur bendera STGM_NOSCRATCH . Kemudian, panggil IStorage::Commit dengan bendera STGC_CONSOLIDATE diatur.
Area rekam jepret, seperti area coretan, juga, biasanya, file sementara, dan ini juga dapat dipengaruhi dengan bendera STGM. Dengan menentukan bendera STGM_NOSNAPSHOT , file rekam jepret sementara terpisah tidak dibuat. Sebaliknya, data asli tidak pernah dimodifikasi, bahkan jika ada satu atau beberapa penulis per objek. Ketika perubahan dilakukan, perubahan ditambahkan ke file, tetapi data asli tetap utuh. Mode ini meningkatkan efisiensi karena mengurangi durasi dengan menghilangkan persyaratan pembuatan rekam jepret selama operasi terbuka. Namun, menggunakan mode ini dapat mengakibatkan file penyimpanan yang sangat besar karena data dalam file tidak pernah dapat ditimpa. Ini tidak terbatas pada ukuran file yang dibuka dalam mode NoSnapshot.
Direct Single-Writer, Multiple-Reader Mode
Seperti yang dijelaskan, dimungkinkan untuk memiliki satu penulis dan beberapa pembaca objek penyimpanan, jika objek tersebut dibuka dalam mode bertransaksi. Dimungkinkan juga untuk mencapai kasus penulis tunggal, multireader dalam mode langsung, dengan menentukan bendera STGM_DIRECT_SWMR .
Dalam mode STGM_DIRECT_SWMR , dimungkinkan bagi satu pemanggil untuk membuka objek untuk akses baca/tulis, sementara pemanggil lain secara bersamaan membuka file untuk akses baca-saja. Tidak valid untuk menggunakan bendera ini dalam kombinasi dengan bendera STGM_TRANSACTED . Dalam mode ini, penulis membuka objek dengan bendera berikut:
| STGM_DIRECT_SWMR | STGM_READWRITE STGM_SHARE_DENYWRITE
dan setiap pembaca membuka objek dengan bendera ini:
| STGM_DIRECT_SWMR | STGM_READ STGM_SHARE_DENY_NONE
Dalam mode ini, untuk memodifikasi objek penyimpanan, penulis harus mendapatkan akses eksklusif ke objek . Ini dimungkinkan ketika semua pembaca telah menutupnya. Penulis menggunakan antarmuka IDirectWriterLock untuk mendapatkan akses eksklusif ini.
Mode Sederhana
Mode sederhana (STGM_SIMPLE) berguna untuk aplikasi yang melakukan operasi penyimpanan lengkap. Ini efisien, tetapi memiliki batasan berikut:
- Tidak ada dukungan untuk substorase.
- Objek penyimpanan, dan objek aliran yang diperoleh darinya, tidak dapat dinamai marshal.
- Setiap aliran memiliki ukuran minimum. Jika kurang dari byte minimum ditulis ke dalam aliran saat aliran dirilis, aliran diperpanjang ke ukuran minimum. Misalnya, ukuran minimum untuk implementasi IStream tertentu adalah 4 KB. Aliran dibuat dan 1 KB ditulis untuk itu. Pada rilis akhir IStream tersebut, ukuran aliran akan secara otomatis diperpanjang hingga 4 KB. Selanjutnya, membuka aliran dan memanggil metode IStream::Stat akan menampilkan ukuran 4 KB.
- Tidak semua metode IStorage atau IStream akan didukung oleh implementasi. Untuk informasi selengkapnya, lihat IStorage - Implementasi File Campuran, dan IStream - Implementasi File Campuran.
Marshaling adalah proses pengemasan, pembukaan kemasan, dan pengiriman parameter metode antarmuka di seluruh utas atau batas proses dalam Panggilan Prosedur Jarak Jauh (RPC). Untuk informasi selengkapnya, lihat Detail Marsekal danMarsekal Antarmuka.
Saat objek penyimpanan diperoleh oleh operasi Buat dalam mode sederhana:
- Elemen stream dapat dibuat, tetapi tidak dibuka.
- Saat elemen stream dibuat dengan memanggil IStorage::CreateStream, tidak dimungkinkan untuk membuat aliran lain hingga objek stream tersebut dirilis.
- Setelah semua aliran ditulis, panggil IStorage::Commit untuk menghapus perubahan.
Ketika objek penyimpanan diperoleh oleh operasi Buka dalam mode sederhana:
- Dimungkinkan untuk membuka hanya satu elemen stream pada satu waktu.
- Tidak dimungkinkan untuk mengubah ukuran aliran dengan memanggil metode IStream::SetSize atau dengan mencari atau menulis di luar akhir aliran. Namun, karena semua aliran berukuran minimum, dimungkinkan untuk menggunakan aliran hingga ukuran tersebut, bahkan jika lebih sedikit data yang awalnya ditulis ke dalamnya. Untuk menentukan ukuran aliran, gunakan metode IStream::Stat .
Ketahuilah bahwa, jika elemen penyimpanan dimodifikasi oleh objek penyimpanan yang tidak dalam mode sederhana, tidak akan mungkin, sekali lagi, untuk membuka elemen penyimpanan tersebut dalam mode sederhana.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung |
Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung |
Windows 2000 Server [hanya aplikasi desktop] |
| Header |
|
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk