Fungsi PropVariantToStringWithDefault (propvarutil.h)

Artikel
03/01/2024

Mengekstrak nilai properti string dari struktur PROPVARIANT . Jika tidak ada nilai, maka nilai default yang ditentukan akan dikembalikan.

Sintaks

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

Parameter

[in] propvarIn

Jenis: REFPROPVARIANT

Referensi ke struktur PROPVARIANT sumber.

[in] pszDefault

Jenis: LPCWSTR

Penunjuk ke nilai untai (karakter) Unicode default, untuk digunakan di mana saat ini tidak ada nilai. Mungkin NULL.

Nilai kembali

Jenis: PCWSTR

Mengembalikan nilai string atau default, atau default.

Keterangan

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

Jika PROPVARIANT sumber memiliki jenis VT_LPWSTR atau VT_BSTR, fungsi pembantu ini mengembalikan penunjuk ke nilai di PROPVARIANT sumber. Jika PROPVARIANT sumber memiliki jenis VT_EMPTY atau konversi tidak dimungkinkan, maka PropVariantToStringWithDefault akan mengembalikan default yang disediakan oleh pszDefault.

Perhatikan bahwa fungsi ini akan mengembalikan pointer ke data yang disediakan dalam parameter. Dengan demikian aplikasi harus memastikan bahwa data yang diberikan ke parameter tetap valid sampai hasilnya tidak lagi digunakan.

Contoh

Contoh berikut, untuk disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara menggunakan PropVariantToStringWithDefault 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.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         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