Fungsi PropVariantChangeType (propvarutil.h)

Artikel
03/15/2023

Memaksakan nilai yang disimpan sebagai struktur PROPVARIANT ke nilai yang setara dari jenis varian yang berbeda.

Sintaks

PSSTDAPI PropVariantChangeType(
  [out] PROPVARIANT          *ppropvarDest,
  [in]  REFPROPVARIANT       propvarSrc,
  [in]  PROPVAR_CHANGE_FLAGS flags,
  [in]  VARTYPE              vt
);

Parameter

[out] ppropvarDest

Jenis: PROPVARIANT*

Penunjuk ke struktur PROPVARIANT yang, ketika fungsi ini berhasil dikembalikan, menerima nilai yang dikoersi dan jenis barunya.

[in] propvarSrc

Jenis: REFPROPVARIANT

Referensi ke struktur PROPVARIANT sumber yang berisi nilai yang dinyatakan sebagai jenis aslinya.

[in] flags

Jenis: PROPVAR_CHANGE_FLAGS

Dicadangkan, harus 0.

[in] vt

Jenis: VARTYPE

Menentukan jenis baru untuk nilai tersebut. Lihat tabel di bawah ini untuk nama jenis yang dikenali.

Mengembalikan nilai

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan COM standar. Jika paksaan yang diminta tidak dimungkinkan, kesalahan akan dikembalikan.

Keterangan

Perhatikan bahwa struktur PROPVARIANT sumber dan tujuan harus berupa struktur terpisah. Anda tidak dapat menimpa data PROPVARIANT sumber dengan data tujuan baru; mencoba melakukannya akan mengakibatkan kesalahan.

PropVariantChangeType mengonversi nilai di antara jenis berikut sebagai berikut. Angka mengacu pada kondisi yang dijelaskan setelah tabel.

	VT_LPWSTR	VT_BSTR	VT_BOOL	VT_FILETIME	VT_DATE	VT_CLSID
VT_LPWSTR	Ya	Ya	Ya	Ya (2)	Ya (2)	Ya
VT_BSTR	Ya	Ya	Ya	Ya (2)	Ya (2)	Ya
VT_BOOL	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_I2	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_I4	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_I8	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_UI2	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_UI4	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_UI8	Ya	Ya	Ya	Tidak	Tidak	Tidak
VT_R8	Ya (3)	Ya (3)	Ya	Tidak	Tidak	Tidak
VT_FILETIME	Ya (2)	Ya (2)	Tidak	Ya	Ya	Tidak
VT_DATE	Ya (2)	Ya (2)	Tidak	Ya	Ya	Tidak
VT_CLSID	Ya	Ya	Tidak	Tidak	Tidak	Ya

	VT_I2	VT_I4	VT_I8	VT_UI2	VT_UI4	VT_UI8	VT_R8
VT_LPWSTR	Ya	Ya	Ya	Ya	Ya	Ya	Ya (3)
VT_BSTR	Ya	Ya	Ya	Ya	Ya	Ya	Ya (3)
VT_BOOL	Ya	Ya	Ya	Ya	Ya	Ya	Ya
VT_I2	Ya	Ya	Ya	Ya (1)	Ya (1)	Ya (1)	Ya (1)
VT_I4	Ya (1)	Ya	Ya	Ya (1)	Ya (1)	Ya (1)	Ya (1)
VT_I8	Ya (1)	Ya (1)	Ya	Ya (1)	Ya (1)	Ya (1)	Ya (1)
VT_UI2	Ya (1)	Ya	Ya	Ya	Ya	Ya	Ya (1)
VT_UI4	Ya (1)	Ya (1)	Ya	Ya (1)	Ya	Ya	Ya (1)
VT_UI8	Ya (1)	Ya (1)	Ya (1)	Ya (1)	Ya (1)	Ya	Ya (1)
VT_R8	Ya (1)	Ya (1)	Ya (1)	Ya (1)	Ya (1)	Ya (1)	Ya
VT_FILETIME	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak
VT_DATE	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak
VT_CLSID	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak

Kondisi

Saat mengonversi antara jenis numerik, konversi di luar rentang gagal. Misalnya, nilai bertanda tangan negatif ke jenis yang tidak ditandatangani, atau nilai tidak bertanda 4 byte yang lebih besar dari 65535 ke jenis tanpa tanda 2 byte.
Saat mengonversi antara string dan tanggal, formulir string kanonis digunakan daripada representasi yang dilokalkan atau "dapat dibaca manusia". Formatnya adalah "yyyy/mm/dd:hh:mm:ss.fff" (tahun, bulan, tanggal, jam, menit, detik, milidetik). Perhatikan bahwa ini kurang presisi daripada yang didukung oleh jenis FILETIME , tetapi harus cukup untuk sebagian besar tujuan.
Saat mengonversi antara angka titik mengambang dan string, pemisah desimal lokal saat ini digunakan. Perhatikan bahwa ini dapat menyebabkan masalah ketika nilai-nilai ini disimpan dalam file yang dipindahkan di antara lokal yang berbeda.

Catatan Jenis tambahan mungkin didukung di masa mendatang.

Konversi antara vektor (VT_VECTOR) dan array (VT_ARRAY) didukung dalam beberapa kasus. Ketika didukung, jumlah elemen harus sama di masing-masing elemen. Vektor bernilai tunggal dapat dikonversi ke nilai non-vektor, tetapi vektor multinilai tidak dapat dikonversi ke jenis non-vektor.

Koersi antar jenis dilakukan tanpa menghormati informasi khusus properti. Pemaksaan khusus properti harus dilakukan menggunakan PSCoerceToCanonicalValue. Selain itu, jika bentuk string dari nilai diperlukan untuk tujuan UI, PSFormatForDisplay harus digunakan untuk memformat nilai sesuai dengan informasi khusus properti dan lokal daripada menggunakan PropVariantChangeType untuk memaksa nilai ke string.

Contoh

Contoh kode berikut, untuk disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara menggunakan PropVariantChangeType untuk menginisialisasi nilai VT_FILETIME dari string.

PROPVARIANT propvarString = {0};
                    
HRESULT hr = InitPropVariantFromString(L"2007/01/30:12:00:00.000", &propvarString);
if (SUCCEEDED(hr))
{
    PROPVARIANT propvarFiletime = {0};

    hr = PropVariantChangeType(&propvarFiletime, propvarString, 0, VT_FILETIME);
    if (SUCCEEDED(hr))
    {
        // propvarFiletime now contains the FILETIME representation 
        // of 1/30/2007 12:00 PM
        PropVariantClear(&propvarFiletime);
    }
    PropVariantClear(&propvarString);
}

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	propvarutil.h
Pustaka	Propsys.lib
DLL	Propsys.dll (versi 6.0 atau yang lebih baru)
Redistribusi	Windows Desktop Search (WDS) 3.0