PropVariantToStringWithDefault 函式 (propvarutil.h)

發行項
03/05/2024

擷取 PROPVARIANT 結構的字串屬性值。如果沒有值存在，則會傳回指定的預設值。

語法

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

參數

[in] propvarIn

類型： REFPROPVARIANT

來源 PROPVARIANT 結構的參考。

[in] pszDefault

類型： LPCWSTR

默認 Unicode 字串值的指標，用於目前沒有任何值存在的位置。可能是 NULL。

傳回值

類型： PCWSTR

傳回字串值或預設值，或預設值。

備註

這個協助程式函式用於呼叫應用程式預期 PROPVARIANT 保留字串值的位置，而且如果不是，則會使用預設值。例如，從屬性存放區取得值的應用程式，可以使用這個來安全地擷取字串屬性的字串值。

如果來源 PROPVARIANT 有類型VT_LPWSTR或VT_BSTR，這個協助程式函式會傳回來源 PROPVARIANT 中值的指標。如果來源 PROPVARIANT 的類型VT_EMPTY或無法轉換，則 PropVariantToStringWithDefault 會傳回 pszDefault 所提供的預設值。

請注意，此函式會傳回參數中提供之數據的指標。因此，應用程式必須確保提供給參數的數據會維持有效狀態，直到結果不再使用為止。

範例

下列範例要包含在較大的程式中，示範如何使用 PropVariantToStringWithDefault 來存取 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);
}

規格需求

需求	值
最低支援的用戶端	Windows XP 搭配 SP2、Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 SP1 [僅限傳統型應用程式]
目標平台	Windows
標頭	propvarutil.h
程式庫	Propsys.lib
Dll	Propsys.dll (6.0 版或更新版本)
可轉散發套件	Windows 桌面搜尋 (WDS) 3.0