Fungsi PSCoerceToCanonicalValue (propsys.h)

Artikel
03/15/2023

Mengonversi nilai properti ke nilai kanonis, sesuai dengan deskripsi properti.

Sintaks

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Parameter

[in] key

Jenis: REFPROPERTYKEY

Referensi ke struktur PROPERTYKEY yang mengidentifikasi properti yang nilainya akan dikoersi.

[in, out] ppropvar

Jenis: PROPVARIANT*

Pada entri, berisi penunjuk ke struktur PROPVARIANT yang berisi nilai asli. Ketika fungsi ini berhasil dikembalikan, berisi nilai kanonis.

Nilai kembali

Jenis: HRESULT

Kemungkinan nilai yang dikembalikan meliputi yang berikut ini:

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.
TYPE_E_TYPEMISMATCH	Koersi dari jenis nilai ke jenis deskripsi properti tidak dimungkinkan. Struktur PROPVARIANT telah dibersihkan.
Kode kegagalan lainnya	Koersi dari jenis nilai ke jenis deskripsi properti tidak dimungkinkan. Struktur PROPVARIANT telah dibersihkan.

Keterangan

Fungsi ini adalah pembungkus di sekitar implementasi sistem IPropertyDescription::CoerceToCanonicalValue.

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

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

Koersi yang dilakukan oleh fungsi ini juga dilakukan oleh sistem properti selama panggilan ke IPropertyStore::GetValue dan IPropertyStore::SetValue. Aplikasi dapat bergantung pada sistem properti untuk melakukan paksaan atau dapat menggunakan fungsi ini untuk melakukan paksaan pada saat aplikasi memilih.

Pemakaian dilakukan dalam empat langkah, sebagai berikut:

Nilai berikut dikonversi ke VT_EMPTY.
- Nilai jenis VT_NULL.
- Nilai jenis VT_LPWSTR, VT_BSTR, atau VT_LPSTR yang pointer-nya 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.
Jika nilai tidak berjenis VT_EMPTY setelah Langkah 1, nilai dikonversi ke jenis yang ditentukan oleh deskripsi properti. Jenis deskripsi properti dapat diperoleh dengan memanggil IPropertyDescription::GetPropertyType. Untuk informasi tentang bagaimana skema properti memengaruhi jenis deskripsi properti, lihat typeInfo. Konversi dilakukan sebagai berikut:
- Nilai jenis VT_LPWSTR, VT_BSTR, atau VT_LPSTR dikonversi ke VT_VECTOR | VT_LPWSTR menggunakan InitPropVariantFromStringAsVector.
- Semua konversi lainnya dilakukan menggunakan PropVariantChangeType

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 dan bukan NULL. Misalnya, L"Alice". Jika ini adalah properti pohon (yaitu, jika atribut isTreeProperty elemen 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 ke depan (/). Misalnya, L"Friend/Bob". Koersi menghapus karakter yang tidak perlu dan menghasilkan VT_EMPTY jika tidak ada konten.
VT_VECTOR \| VT_LPWSTR	Setiap string dalam vektor harus mematuhi aturan untuk VT_LPWSTR yang 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 menghasilkan VT_EMPTY.

Jika berlaku, nilai diperiksa terhadap enumerasi jenis deskripsi properti. Pemeriksaan dalam tabel berikut ini 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 nilai ke VT_EMPTY.
Diskrit	Numerik	Angka cocok dengan salah satu nilai enumerasi yang diizinkan untuk properti . Jika tidak, konversikan nilai ke 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 nilai 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 nilai menjadi VT_EMPTY.
Berkisar	VT_LPWSTR	String ada dalam rentang yang diizinkan untuk properti . Perbandingan sifatnya peka huruf besar/kecil. Jika tidak, konversikan nilai ke 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 nilai menjadi VT_EMPTY.
Berkisar	VT_VECTOR \| Numerik	Setiap angka dalam vektor ada dalam rentang yang diizinkan untuk properti . Jika tidak, hapus angka tersebut dari vektor. Jika vektor yang dihasilkan kosong, konversikan nilai menjadi VT_EMPTY.

Contoh

Contoh berikut, untuk disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara menggunakan PSCoerceToCanonicalValue untuk memaksa nilai ke jenis yang diperlukan untuk PKEY_Keywords.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP dengan SP2, Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 dengan SP1 [hanya aplikasi desktop]
Target Platform	Windows
Header	propsys.h
Pustaka	Propsys.lib
DLL	Propsys.dll (versi 6.0 atau yang lebih baru)
Redistribusi	Windows Desktop Search (WDS) 3.0