Fungsi PropVariantToStringAlloc (propvarutil.h)
Mengekstrak nilai properti string dari struktur PROPVARIANT .
Sintaks
PSSTDAPI PropVariantToStringAlloc(
[in] REFPROPVARIANT propvar,
[out] PWSTR *ppszOut
);
Parameter
[in] propvar
Jenis: REFPROPVARIANT
Referensi ke struktur PROPVARIANT sumber.
[out] ppszOut
Jenis: PWSTR*
Ketika fungsi ini kembali, berisi penunjuk ke nilai properti yang diekstrak jika ada.
Nilai kembali
Jenis: HRESULT
Jika fungsi ini berhasil, fungsi akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.
Keterangan
Fungsi pembantu ini digunakan di tempat-tempat di mana aplikasi panggilan mengharapkan PROPVARIANT untuk menyimpan nilai string.
Jika PROPVARIANT sumber memiliki jenis VT_LPWSTR atau VT_BSTR, fungsi ini mengekstrak string ke dalam buffer yang baru dialokasikan. Jika tidak, ia mencoba mengonversi nilai dalam struktur PROPVARIANT menjadi string. Jika konversi tidak memungkinkan, PropVariantToStringAlloc akan mengembalikan kode kegagalan dan mengatur ppszOut ke NULL. Lihat PropVariantChangeType untuk daftar kemungkinan konversi. Dari catatan, VT_EMPTY berhasil dikonversi ke buffer yang dialokasikan yang berisi "".
Aplikasi panggilan bertanggung jawab untuk menggunakan CoTaskMemFree untuk merilis string yang ditujukkan oleh ppszOut ketika tidak lagi diperlukan.
Selain konversi yang disediakan oleh PropVariantChangeType, kasus khusus berikut berlaku untuk PropVariantToStringAlloc.
- PROPVARIANTs bernilai vektor dikonversi menjadi string dengan memisahkan setiap elemen dengan menggunakan "; ". Misalnya, PropVariantToStringAlloc mengonversi vektor 3 bilangan bulat, {3, 1, 4}, ke string "3; 1; 4". Titik koma tidak bergantung pada lokal saat ini.
- nilai VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT, dan VT_UNKNOWN dikonversi ke string menggunakan pengodean yang tidak didukung. Tidak dimungkinkan untuk mendekode string yang dibuat dengan cara ini dan formatnya dapat berubah di masa mendatang.
Contoh
// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);
if (SUCCEEDED(hr))
{
// PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.
// PropVariantToStringAlloc will convert VT_EMPTY to "".
LPWSTR pszTitle;
hr = PropVariantToString(propvar, &pszTitle);
if (SUCCEEDED(hr))
{
// pszTitle is now valid
}
else
{
// pszTitle is always NULL
}
PropVariantClear(&propvar);
}
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 |