Implementasi File IPropertyStorage-Compound
Implementasi COM dari arsitektur Penyimpanan Terstruktur disebut file campuran. Objek penyimpanan seperti yang diimplementasikan dalam file majemuk mencakup implementasi IPropertyStorage, antarmuka yang mengelola satu set properti persisten, dan IPropertySetStorage, antarmuka yang mengelola grup set properti persisten. Untuk informasi selengkapnya tentang antarmuka IPropertyStorage , lihat IPropertyStorage dan Pertimbangan Penyimpanan Properti.
Untuk mendapatkan penunjuk ke implementasi file majemuk IPropertyStorage, panggil StgCreateStorageEx untuk membuat objek file majemuk baru atau StgOpenStorageEx untuk membuka objek file majemuk yang dibuat sebelumnya. Dalam kasus StgCreateStorageEx, parameter stgfmt harus diatur ke STGFMT_STORAGE. Dalam kasus StgOpenStorageEx, parameter stgfmt harus diatur ke STGFMT_STORAGE atau STGFMT_ANY. Dalam kedua kasus, parameter riid harus diatur ke IID_IPropertySetStorage. Kedua fungsi menyediakan pointer ke antarmuka IPropertySetStorage objek. Dengan memanggil metode Buat atau Buka antarmuka tersebut, Anda akan mendapatkan pointer ke antarmuka IPropertyStorage , yang dapat Anda gunakan untuk memanggil salah satu metodenya.
Cara alternatif untuk mendapatkan penunjuk ke implementasi file majemuk IPropertySetStorage adalah dengan memanggil fungsi StgCreateDocfile dan StgOpenStorage yang lebih lama, atau untuk menentukan parameter riid IID_IStorage ke fungsi StgCreateStorageEx atau StgOpenStorageEx . Dalam kedua kasus, penunjuk ke antarmuka IStorage objek dikembalikan. Dengan set properti persisten, panggil QueryInterface untuk antarmuka IPropertySetStorage , menentukan nama yang ditentukan header untuk pengidentifikasi antarmuka (IID) IID_IPropertySetStorage.
Kapan Digunakan
Gunakan IPropertyStorage untuk mengelola properti dalam satu set properti. Metodenya mendukung membaca, menulis, dan menghapus properti dan nama string opsional yang dapat dikaitkan dengan pengidentifikasi properti. Metode lain mendukung operasi penyimpanan penerapan dan pengembalian standar. Ada juga metode yang memungkinkan Anda mengatur waktu yang terkait dengan penyimpanan properti, dan metode lain yang mengizinkan penugasan CLSID yang dapat digunakan untuk mengaitkan kode lain, seperti kode antarmuka pengguna, dengan kumpulan properti. Memanggil metode Enum memasok pointer ke implementasi file majemuk IEnumSTATPROPSTG, yang memungkinkan Anda menghitung properti dalam set.
Catatan
Jika Anda mendapatkan pointer ke IPropertyStorage dengan memanggil StgCreateDocfile, StgCreateStorageEx, StgOpenStorage atau StgOpenStorageEx pada penyimpanan set properti mode sederhana, metode IPropertyStorage mematuhi aturan aliran mode sederhana. Penyimpanan set properti adalah mode sederhana jika diperoleh untuk file yang dibuat atau dibuka dengan bendera STGM_SIMPLE. Dalam hal ini, tidak selalu mungkin untuk membuat aliran yang mendasar lebih besar dan tidak mungkin untuk mengganti properti yang ada dengan properti yang lebih besar. Untuk informasi selengkapnya, lihat Implementasi File IPropertySetStorage-Compound.
IPropertyStorage dan Caching
Implementasi file majemuk dari cache IPropertyStorage membuka kumpulan properti dalam memori untuk meningkatkan performa. Akibatnya, perubahan pada set properti tidak ditulis ke file gabungan hingga metode Penerapan atau Rilis (referensi terakhir) dipanggil.
Set Properti Mode Sederhana
Objek penyimpanan properti dalam mode sederhana jika dibuat dari objek penyimpanan set properti mode sederhana. Misalnya, objek penyimpanan set properti akan berada dalam mode sederhana jika diperoleh dari fungsi StgOpenStorageEx , dengan bendera STGM_SIMPLE diatur dalam parameter grfMode . Perhatikan bahwa "mode sederhana" tidak terkait dengan "set properti sederhana". Set properti sederhana jika dibuat dengan memanggil IPropertySetStorage::Create dengan bendera PROPSETFLAG_NONSIMPLE yang diatur dalam parameter grfFlags . Untuk informasi selengkapnya tentang set properti sederhana dan nonsimple, lihat Penyimpanan dan Objek Aliran untuk Kumpulan Properti.
Saat objek penyimpanan properti mode sederhana dibuat, tidak ada batasan penggunaannya. Ketika objek penyimpanan properti mode sederhana yang ada dibuka, objek aliran yang mendasar yang menyimpan kumpulan properti tidak dapat ditumbuhkan. Akibatnya, tidak selalu mungkin untuk memodifikasi objek penyimpanan properti seperti itu jika perubahan memerlukan aliran yang lebih besar.
Format Set Properti
Implementasi file majemuk IPropertyStorage mendukung format serialisasi set properti versi 0 dan versi 1. Format versi 1 didukung pada komputer yang berjalan pada Windows 2000. Untuk informasi selengkapnya, lihat Serialisasi Set Properti. Kumpulan properti dibuat dalam format versi 0 dan tetap dalam format tersebut kecuali fitur baru diminta. Ketika itu terjadi, format diperbarui ke versi 1.
Misalnya, jika kumpulan properti dibuat dengan bendera PROPSETFLAG_DEFAULT, formatnya adalah versi 0. Selama jenis properti yang sesuai dengan format versi 0 ditulis dan dibaca dari kumpulan properti tersebut, set properti tetap dalam format versi 0. Jika jenis properti versi 1 ditulis ke kumpulan properti, kumpulan properti secara otomatis diperbarui ke versi 1. Selanjutnya, set properti tersebut tidak dapat lagi dibaca oleh implementasi yang hanya mengenali versi 0.
Jenis IPropertyStorage dan Varian
Implementasi file majemuk IPropertyStorage tidak mendukung jenis varian VT_UNKNOWN atau VT_DISPATCH dalam anggota vt struktur PROPVARIANT .
Tabel berikut ini mencantumkan jenis varian yang didukung dalam SafeArray; artinya, nilai-nilai ini dapat dikombinasikan dengan VT_ARRAY dalam anggota vt struktur PROPVARIANT .
Jenis varian yang didukung dalam SafeArray oleh implementasi file majemuk IPropertyStorage
VT_I1
VT_UI1
VT_I2
VT_UI2
VT_I4
VT_UI4
VT_INT
VT_UINT
VT_R4
VT_R8
VT_CY
VT_DATE
VT_BSTR
VT_BOOL
VT_DECIMAL
VT_ERROR
VT_VARIANT
Ketika VT_VARIANT dikombinasikan dengan VT_ARRAY, SafeArray itu sendiri memegang struktur PROPVARIANT . Namun, jenis elemen ini harus diambil dari daftar sebelumnya, tidak dapat VT_VARIANT, dan tidak dapat menyertakan indikator VT_VECTOR, VT_ARRAY, atau VT_BYREF.
Metode IPropertyStorage
Implementasi file majemuk IPropertyStorage mendukung metode berikut:
-
Membaca properti yang ditentukan dalam array rgpspec dan memasok nilai semua properti yang valid dalam array rgvar PROPVARIANTs. Dalam implementasi file majemuk COM, pengidentifikasi properti duplikat yang merujuk ke jenis aliran atau penyimpanan menghasilkan beberapa panggilan ke IStorage::OpenStream atau IStorage::OpenStorage dan keberhasilan atau kegagalan ReadMultiple tergantung pada kemampuan implementasi penyimpanan yang mendasar untuk berbagi operasi pembukaan. Karena dalam file campuran STGM_SHARE_EXCLUSIVE dipaksa, beberapa upaya terbuka akan gagal. Membuka objek penyimpanan yang sama lebih dari sekali dari penyimpanan induk yang sama tidak didukung. Bendera STGM_SHARE_EXCLUSIVE harus ditentukan.
Selain itu, untuk memastikan operasi aman utas jika properti bernilai aliran atau penyimpanan yang sama diminta beberapa kali melalui penunjuk IPropertyStorage yang sama dalam implementasi file majemuk, operasi terbuka akan berhasil atau gagal tergantung pada apakah properti sudah terbuka dan apakah sistem file yang mendasar menangani beberapa pembukaan aliran atau penyimpanan. Dengan demikian, operasi ReadMultiple pada properti bernilai aliran atau penyimpanan selalu menghasilkan panggilan ke IStorage::OpenStream, atau IStorage::OpenStorage, yang melewati akses (STGM_READWRITE, dan sebagainya) dan berbagi bendera (STGM_SHARE_EXCLUSIVE, dan sebagainya) yang ditentukan ketika set properti asli dibuka atau dibuat.
Jika metode gagal, nilai yang ditulis ke rgvar[] tidak terdefinisi. Jika beberapa properti bernilai aliran atau penyimpanan berhasil dibuka tetapi kesalahan terjadi sebelum eksekusi selesai, properti ini harus dirilis sebelum metode kembali.
-
Menulis properti yang ditentukan dalam array rgpspec[], menetapkannya tag dan nilai PROPVARIANT yang ditentukan dalam rgvar[]. Properti yang sudah ada diberi nilai PROPVARIANT yang ditentukan. Properti yang saat ini tidak ada dibuat.
-
Menghapus properti yang ditentukan dalam rgpspec[].
-
Membaca nama string yang ada yang terkait dengan ID properti yang ditentukan dalam array rgpropid[].
-
Menetapkan nama string yang ditentukan dalam array rglpwstrName ke ID properti yang ditentukan dalam array rgpropid .
-
Menghapus nama properti untuk properti yang ditentukan dalam array rgpropid[].
-
Mengatur CLSID dari aliran set properti. Dalam implementasi file majemuk, mengatur CLSID pada kumpulan properti nonsimple (yang dapat secara legal berisi properti penyimpanan atau bernilai aliran, seperti yang dijelaskan dalam IPropertySetStorage::Create) juga mengatur CLSID pada substorage yang mendasar sehingga dapat diperoleh melalui panggilan ke IStorage::Stat.
-
Untuk set properti sederhana dan nonsimple, hapus properti yang mengatur gambar memori ke penyimpanan yang mendasar. Selain itu, untuk set properti mode bertransaksi nonsimple, metode ini melakukan penerapan (seperti dalam IStorage::Commit) pada penyimpanan yang berisi kumpulan properti.
-
Hanya untuk set properti nonsimple, panggil metode Kembalikan penyimpanan yang mendasar dan buka kembali aliran 'konten'. Untuk set properti sederhana, antarmuka ini selalu mengembalikan S_OK. Set properti nonsimple adalah yang dibuat menggunakan bendera PROPSETFLAG_NONSIMPLE di metode IPropertySetStorage::Create . Untuk informasi selengkapnya, lihat Penyimpanan dan Objek Stream untuk Kumpulan Properti .
-
Membuat instans IEnumSTATPROPSTG, metode yang dapat dipanggil untuk menghitung struktur STATPROPSTG yang memberikan informasi tentang masing-masing properti dalam set. Implementasi ini membuat array tempat seluruh set properti dibaca dan yang dapat dibagikan ketika IEnumSTATPROPSTG::Clone dipanggil. Perubahan pada kumpulan properti tidak tercermin dalam instans IEnumSTATPROPSTG terbuka. Untuk melihat perubahan tersebut, instans baru enumerator ini harus dibangun.
-
Mengisi anggota struktur STATPROPSETSTG , yang berisi data tentang kumpulan properti secara keseluruhan. Saat kembali, memasok pointer ke struktur. Untuk set penyimpanan nonsimple, implementasi ini memanggil IStorage::Stat (atau IStream::Stat) untuk mendapatkan waktu dari penyimpanan atau aliran yang mendasar. Untuk set penyimpanan sederhana, tidak ada waktu yang dipertahankan.
-
Untuk set properti nonsimple saja, mengatur waktu yang didukung oleh penyimpanan yang mendasar. Implementasi penyimpanan file gabungan mendukung ketiganya: modifikasi, akses, dan pembuatan. Implementasi SetTimes ini memanggil metode IStorage::SetElementTimes dari penyimpanan yang mendasarinya untuk mengambil waktu ini.
Topik terkait
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