Metode IPropertyStorage::WriteMultiple (propidl.h)

Artikel
08/25/2023

Metode WriteMultiple menulis grup properti tertentu ke kumpulan properti saat ini. Jika properti dengan nama atau pengidentifikasi properti tertentu sudah ada, properti akan diganti, bahkan ketika jenis lama dan baru untuk nilai properti berbeda. Jika properti dari nama atau ID properti yang diberikan tidak ada, properti tersebut dibuat.

Sintaks

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

Parameter

[in] cpspec

Jumlah properti yang ditetapkan. Nilai parameter ini dapat diatur ke nol; namun, ini mengalahkan tujuan metode karena tidak ada properti yang kemudian ditulis.

[in] rgpspec

Array ID properti (PROPSPEC) tempat properti diatur. Ini tidak perlu dalam urutan tertentu, dan mungkin berisi duplikat, namun ID properti terakhir yang ditentukan adalah yang berlaku. Campuran ID properti dan nama string diizinkan.

[in] rgpropvar

Array ( ukuran cpspec) struktur PROPVARIANT yang berisi nilai properti yang akan ditulis. Array harus berukuran yang ditentukan oleh cpspec.

[in] propidNameFirst

Nilai minimum untuk ID properti yang harus ditetapkan metode jika parameter rgpspec menentukan properti bernama string yang saat ini tidak ada ID properti. Jika semua properti bernama string yang ditentukan sudah ada dalam set ini, dan dengan demikian sudah memiliki ID properti, nilai ini diabaikan. Ketika tidak diabaikan, nilai ini harus lebih besar dari, atau sama dengan, dua dan kurang dari 0x80000000. ID properti 0 dan 1 dan lebih besar dari 0x80000000 disediakan untuk penggunaan khusus.

Mengembalikan nilai

Metode ini mendukung nilai pengembalian standar E_UNEXPECTED, selain yang berikut ini:

Fungsi ini juga dapat mengembalikan kesalahan sistem file atau kesalahan Win32 yang dibungkus dalam jenis data HRESULT . Untuk informasi selengkapnya, lihat Strategi Penanganan Kesalahan.

Keterangan

Jika properti yang ditentukan sudah ada, nilainya diganti dengan yang ditentukan dalam rgpspec, bahkan ketika jenis lama dan baru untuk nilai properti berbeda. Jika properti yang ditentukan belum ada, properti tersebut dibuat. Perubahan tidak bertahan pada penyimpanan yang mendasar hingga IPropertyStorage::Commit telah dipanggil.

Nama properti disimpan di bagian kamus khusus dari kumpulan properti, yang memetakan nama tersebut ke ID properti. Semua properti memiliki ID, tetapi nama bersifat opsional. Nama string disediakan dengan menentukan PRSPEC_LPWSTR di anggota ulKind dari struktur PROPSPEC . Jika nama string disediakan untuk properti, dan nama belum ada dalam kamus, metode akan mengalokasikan ID properti, dan menambahkan ID properti dan nama ke kamus. ID properti dialokasikan singgah sehingga tidak berkonflik dengan ID lain dalam kumpulan properti. Nilai ID properti juga tidak kurang dari nilai yang ditentukan oleh parameter propidNameFirst . Jika parameter rgpspec menentukan properti bernama string yang saat ini tidak ada ID properti, parameter propidNameFirst menentukan nilai minimum untuk ID properti yang harus ditetapkan metode WriteMultiple .

Saat kumpulan properti baru dibuat, halaman kode khusus (PROPERTI ID 1) dan properti ID Lokal (ID Properti 0x80000000) ditulis ke kumpulan properti secara otomatis. Properti ini kemudian dapat dibaca, menggunakan metode IPropertyStorage::ReadMultiple , dengan menentukan ID properti dengan nilai PID_CODEPAGE dan PID_LOCALE yang ditentukan header. Jika set properti tidak kosong — memiliki satu atau beberapa properti selain halaman kode dan properti ID Lokal atau memiliki satu atau beberapa nama dalam kamusnya — halaman kode khusus dan properti ID Lokal tidak dapat dimodifikasi dengan memanggil IPropertyStorage::WriteMultiple. Namun, jika kumpulan properti kosong, salah satu atau kedua properti khusus ini dapat dimodifikasi.

Jika elemen dalam array rgspec diatur dengan nilai PRSPEC_PROPID 0xffffffff (PID_ILLEGAL), nilai yang sesuai dalam array rgvar diabaikan oleh IPropertyStorage::WriteMultiple. Misalnya, jika metode ini dipanggil dengan parameter cspec diatur ke 3, tetapi rgpspec[1].prspec diatur ke PRSPEC_PROPID dan rgpspec[1].propid diatur ke PID_ILLEGAL, hanya dua properti yang akan ditulis. Elemen rgpropvar[1] diabaikan secara diam-diam.

Gunakan makro PropVariantInit untuk menginisialisasi struktur PROPVARIANT .

Kumpulan properti, tidak termasuk data untuk properti nonsimple, dibatasi hingga 256 KB untuk Windows NT 4.0 dan yang lebih lama. Untuk Windows 2000, Windows XP dan Windows Server 2003, set properti OLE dibatasi hingga 1 MB. Jika batas ini terlampaui, operasi gagal dan pemanggil menerima pesan kesalahan. Tidak ada kemungkinan kebocoran memori atau diserbu. Untuk informasi selengkapnya, lihat Mengelola Set Properti.

Kecuali PROPSETFLAG_CASE_SENSITIVE diteruskan ke IPropertySetStorage::Create, nama set properti tidak peka huruf besar/kecil. Menentukan properti dengan namanya di IPropertyStorage::WriteMultiple akan menghasilkan pencarian nama yang tidak peka huruf besar/kecil dalam kumpulan properti. Untuk membandingkan string yang tidak peka huruf besar/kecil, lokal string harus diketahui. Untuk informasi selengkapnya, lihat IPropertyStorage::WritePropertyNames.

Untuk informasi selengkapnya, lihat Pertimbangan Penyimpanan Properti.

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	propidl.h (termasuk Objbase.h, Propidlbase.h)
Pustaka	Uuid.lib
DLL	Ole32.dll