Fungsi PropVariantToString (propvarutil.h)

Artikel
03/15/2023

Mengekstrak nilai string dari struktur PROPVARIANT .

Sintaks

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Parameter

[in] propvar

Jenis: REFPROPVARIANT

Referensi ke struktur PROPVARIANT sumber.

[out] psz

Jenis: PWSTR

Menunjuk ke buffer string. Ketika fungsi ini kembali, buffer diinisialisasi dengan nilai untai Unicode yang dihentikan NULL .

[in] cch

Jenis: UINT

Ukuran buffer yang diacu oleh psz, dalam karakter.

Nilai kembali

Jenis: HRESULT

Fungsi ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode	Deskripsi
S_OK	Nilai diekstrak dan buffer hasil dihentikan NULL .
STRSAFE_E_INSUFFICIENT_BUFFER	Operasi penyalinan gagal karena ruang buffer tidak mencukupi. Buffer tujuan berisi versi hasil yang dihentikan dengan null dan dihentikan dari hasil yang dimaksud. Dalam situasi di mana pemotokan dapat diterima, ini mungkin belum tentu dipandang sebagai kondisi kegagalan.
Beberapa nilai kesalahan lainnya	Ekstraksi gagal karena alasan lain.

Keterangan

Fungsi pembantu ini digunakan di tempat-tempat di mana aplikasi panggilan mengharapkan PROPVARIANT untuk menyimpan nilai string. Misalnya, aplikasi yang mendapatkan nilai dari penyimpanan properti dapat menggunakan ini untuk mengekstrak nilai string dengan aman untuk properti string.

Jika SUMBER PROPVARIANT memiliki jenis VT_LPWSTR atau VT_BSTR, fungsi ini mengekstrak string dan menempatkannya ke dalam buffer yang disediakan. Jika tidak, ia mencoba mengonversi nilai dalam struktur PROPVARIANT menjadi string. Jika konversi tidak memungkinkan, PropVariantToString akan mengembalikan kode kegagalan dan mengatur psz ke '\0'. Lihat PropVariantChangeType untuk daftar kemungkinan konversi. Dari catatan, VT_EMPTY berhasil dikonversi menjadi "".

Selain NULL yang mengakhiri, paling banyak karakter cch-1 ditulis ke dalam buffer yang ditujukkan oleh psz. Jika nilai dalam PROPVARIANT sumber lebih panjang dari yang akan masuk ke dalam buffer, salinan null terpotok Dihentikan string ditulis ke buffer dan fungsi ini mengembalikan STRSAFE_E_INSUFFICIENT_BUFFER. String yang dihasilkan akan selalu dihentikan NULL .

Selain konversi yang disediakan oleh PropVariantChangeType, kasus khusus berikut berlaku untuk PropVariantToString.

PROPVARIANTs bernilai vektor dikonversi menjadi string dengan memisahkan setiap elemen dengan menggunakan "; ". Misalnya, PropVariantToString 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

Contoh berikut, untuk disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara menggunakan PropVariantToString untuk mengakses nilai string dalam PROPVARIANT.

// 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.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    PropVariantClear(&propvar);

}

Persyaratan


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