Bagikan melalui

Metode IPropertyDescription::CoerceToCanonicalValue (propsys.h)

  • Artikel

Memaksakan nilai ke nilai kanonis, sesuai dengan deskripsi properti.

Sintaks

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Parameter

[in, out] ppropvar

Jenis: PROPVARIANT*

Pada entri, berisi penunjuk ke struktur PROPVARIANT yang berisi nilai asli. Ketika metode ini kembali, berisi nilai kanonis.

Nilai kembali

Jenis: HRESULT

Jika kode kegagalan tidak INPLACE_S_TRUNCATED atau E_INVALIDARG, maka paksaan dari jenis nilai ke jenis deskripsi properti tidak dimungkinkan, dan struktur PROPVARIANT telah dihapus.

Hasil yang mungkin mencakup hal-hal berikut:

Menampilkan kode Deskripsi
S_OK
 Fungsi berhasil. Nilai properti yang ditentukan oleh ppropvar sekarang dalam bentuk kanonis.
INPLACE_S_TRUNCATED
 Nilai properti yang ditentukan oleh ppropvar sekarang dalam bentuk kanonis yang terpotong.
E_INVALIDARG
 Parameter ppropvar tidak valid. Struktur PROPVARIANT telah dibersihkan.

Keterangan

Untuk informasi selengkapnya, lihat atribut jenis elemen typeInfo dalam file .propdesc properti.

Sebagian besar deskripsi properti menentukan jenis yang diharapkan untuk digunakan nilainya. Misalnya, deskripsi properti untuk System.Title menentukan bahwa nilai System.Title harus menggunakan VT_LPWSTR. Metode ini memaksa nilai ke jenis ini, dan memaksa hasilnya ke dalam bentuk kanonis.

Penting untuk dicatat bahwa jika metode ini gagal, metode ini akan sudah memanggil PropVariantClear pada struktur PROPVARIANT input. Hanya jika metode ini berhasil adalah aplikasi panggilan yang bertanggung jawab untuk memanggil PropVariantClear pada ppropvar ketika struktur tidak lagi diperlukan.

Koersi yang dilakukan oleh metode ini juga dilakukan oleh sistem properti selama panggilan IPropertyStore::GetValue dan IPropertyStore::SetValue . Aplikasi dapat bergantung pada sistem properti untuk melakukan pemaksaan, atau dapat menggunakan metode ini untuk melakukan pemaksaan pada saat yang dipilih aplikasi.

Pemakaian dilakukan dalam empat langkah, sebagai berikut:

  1. Nilai berikut dikonversi ke VT_EMPTY.
    • Nilai jenis VT_NULL.
    • Nilai jenis VT_LPWSTR, VT_BSTR, atau VT_LPSTR yang penunjuknya adalah NULL.
    • Nilai jenis VT_LPWSTR, VT_BSTR, atau VT_LPSTR yang kosong atau sepenuhnya terdiri dari spasi.
    • Nilai jenis VT_FILETIME sebelum tengah malam 1601/01/02.
  2. Jika nilainya tidak berjenis VT_EMPTY setelah Langkah 1, nilai akan dikonversi ke jenis yang ditentukan oleh deskripsi properti. Jenis deskripsi properti dapat diperoleh menggunakan IPropertyDescription::GetPropertyType. Lihat typeInfo untuk informasi tentang bagaimana skema properti memengaruhi jenis deskripsi properti. Konversi dilakukan sebagai berikut:
  3. Setelah Langkah 2 dan 3, nilai dikoercasi ke dalam bentuk kanonis berdasarkan jenisnya. Formulir kanonis dirangkum dalam tabel berikut.
    Jenis Nilai Formulir Kanonis
    VT_EMPTY Selalu kanonis.
    VT_LPWSTR
    • Tidak ada spasi di depan atau di belakang. String tidak kosong. Untai (karakter) non-NULL. Contohnya,L"Alice".
    • Jika ini adalah properti pohon (yaitu, jika atribut elemen isTreeProperty typeInfo adalah TRUE), maka tidak boleh memiliki garis miring maju atau berikutnya (/), tidak boleh memiliki spasi antara teks dan garis miring ke depan, dan tidak boleh memiliki dua garis miring maju berturut-turut(/). Misalnya, L"Friend/Bob"
    • Koersi menghapus karakter yang tidak perlu dan akan mengakibatkan VT_EMPTY jika tidak ada konten.
    VT_VECTOR | VT_LPWSTR
    • Setiap string dalam vektor harus mematuhi aturan untuk VT_LPWSTR tercantum di atas. Selain itu, vektor tidak boleh memiliki duplikat dan tidak memiliki pointer null.
    • Jika ini adalah properti pohon, maka tidak ada nilai yang dapat menjadi leluhur dari nilai lain. Misalnya, L"Friend" adalah leluhur L"Friend/Bob".
    • Jika tidak ada konten, koersi akan menghapus karakter duplikat dan leluhur dan akan menghasilkan VT_EMPTY.
     
  4. Jika berlaku, nilai diperiksa terhadap enumerasi jenis deskripsi properti. Pemeriksaan berikut berlaku.
    Jenis Enumerasi Jenis Nilai Formulir Kanonis
    Diskret atau Berkisar VT_EMPTY Selalu kanonis
    Diskrit VT_LPWSTR String cocok dengan salah satu string enumerasi yang diizinkan untuk properti . Perbandingan tidak peka huruf besar/kecil. Jika tidak, konversikan nilainya menjadi VT_EMPTY.
    Diskrit Numerik Angka cocok dengan salah satu nilai enumerasi yang diizinkan untuk properti . Jika tidak, konversikan nilainya menjadi VT_EMPTY.
    Diskrit VT_VECTOR | VT_LPWSTR Setiap string dalam vektor cocok dengan salah satu string enumerasi yang diizinkan untuk properti . Perbandingan tidak peka huruf besar/kecil. Jika tidak, hapus string tersebut dari vektor. Jika vektor yang dihasilkan kosong, konversikan nilainya menjadi VT_EMPTY.
    Diskrit VT_VECTOR | Numerik Setiap angka dalam vektor cocok dengan salah satu nilai enumerasi yang diizinkan untuk properti . Jika tidak, hapus angka tersebut dari vektor. Jika vektor yang dihasilkan kosong, konversikan nilainya menjadi VT_EMPTY.
    Berkisar VT_LPWSTR String ada dalam rentang yang diizinkan untuk properti . Perbandingan sifatnya peka huruf besar/kecil. Jika tidak, konversikan nilainya menjadi VT_EMPTY.
    Berkisar Numerik Angka ada dalam rentang yang diizinkan untuk properti . Jika tidak, konversikan nilai ke VT_EMPTY.
    Berkisar VT_VECTOR | VT_LPWSTR Setiap string dalam vektor ada dalam rentang yang diizinkan untuk properti . Perbandingan sifatnya peka huruf besar/kecil. Jika tidak, hapus string tersebut dari vektor. Jika vektor yang dihasilkan kosong, konversikan nilainya menjadi VT_EMPTY.
    Berkisar VT_VECTOR | Numerik Setiap angka dalam vektor ada dalam rentang yang diizinkan untuk properti . Jika tidak, hapus nomor tersebut dari vektor. Jika vektor yang dihasilkan kosong, konversikan nilai menjadi VT_EMPTY.
     

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Target Platform Windows
Header propsys.h

Lihat juga

IPropertyDescription

Skema Deskripsi Properti