Fungsi PropVariantToBSTR (propvarutil.h)

Artikel
03/15/2023

Mengekstrak nilai properti BSTR dari struktur PROPVARIANT .

Sintaks

PSSTDAPI PropVariantToBSTR(
  [in]  REFPROPVARIANT propvar,
  [out] BSTR           *pbstrOut
);

Parameter

[in] propvar

Jenis: REFPROPVARIANT

Referensi ke struktur PROPVARIANT sumber.

[out] pbstrOut

Jenis: BSTR*

Penunjuk ke nilai properti yang diekstrak jika ada; jika tidak, berisi string kosong.

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_BSTR atau VT_LPWSTR, fungsi ini mengekstrak string sebagai nilai BSTR . Jika tidak, ia mencoba mengonversi nilai dalam struktur PROPVARIANT menjadi string. Jika konversi tidak memungkinkan, PropVariantToBSTR mengembalikan kode kegagalan dan mengatur pbstrOut ke NULL. Lihat PropVariantChangeType untuk daftar kemungkinan konversi.

VT_EMPTY berhasil dikonversi ke BSTR yang dialokasikan yang berisi "".

Aplikasi panggilan bertanggung jawab untuk menggunakan SysFreeString untuk merilisBSTR yang ditujukkan oleh pbstrOut ketika tidak lagi diperlukan.

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

PROPVARIANTs bernilai vektor dikonversi menjadi string dengan memisahkan setiap elemen dengan menggunakan "; ". Misalnya, PropVariantToBSTR 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 menjadi string melalui 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 PropVariantToBSTR untuk mengakses nilai string dalam PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume the 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.
    // PropVariantToBSTR will convert VT_EMPTY to "".
    BSTR bstrTitle;
    
    hr = PropVariantToBSTR(propvar, &bstrTitle);
    
    if (SUCCEEDED(hr))
    {
        // bstrTitle is now valid.
    }
    else
    {
        // bstrTitle 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