PropVariantToStringAlloc 函式 (propvarutil.h)
從 PROPVARIANT 結構擷取字串屬性值。
語法
PSSTDAPI PropVariantToStringAlloc(
[in] REFPROPVARIANT propvar,
[out] PWSTR *ppszOut
);
參數
[in] propvar
類型： REFPROPVARIANT
來源 PROPVARIANT 結構的參考。
[out] ppszOut
類型： PWSTR*
當此函式傳回時，如果存在，則包含所擷取屬性值的指標。
傳回值
類型： HRESULT
如果此函式成功，則會傳回 S_OK。 否則，它會傳回 HRESULT 錯誤碼。
備註
此協助程式函式用於呼叫應用程式預期 PROPVARIANT 保留字串值的位置。
如果來源 PROPVARIANT 的類型VT_LPWSTR或VT_BSTR，此函式會將字串擷取到新配置的緩衝區。 否則，它會嘗試將 PROPVARIANT 結構中的值轉換成字串。 如果無法轉換， PropVariantToStringAlloc 會傳回失敗碼，並將 ppszOut 設定為 NULL。 如需可能轉換的清單 ，請參閱 PropVariantChangeType 。 請注意， VT_EMPTY 已成功轉換成包含 「的已配置緩衝區」。
呼叫的應用程式會負責使用 CoTaskMemFree 在不再需要時釋放 ppszOut 所指向的字串。
除了 PropVariantChangeType 所提供的轉換之外，下列特殊案例也適用於 PropVariantToStringAlloc。
- 向量值 PROPV USERNAMET 會藉由使用 “; ”，將每個元素分隔為字串。 例如， PropVariantToStringAlloc 會將 3 個整數的向量 {3， 1， 4}轉換為字串 “3;1;4". 分號與目前的地區設定無關。
- VT_BLOB、VT_STREAM、VT_STREAMED_OBJECT和VT_UNKNOWN值會使用不支援的編碼轉換成字串。 無法以此方式譯碼建立的字串，而且格式未來可能會變更。
範例
// 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);
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP 搭配 SP2、Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 SP1 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | propvarutil.h |
| 程式庫 | Propsys.lib |
| Dll | Propsys.dll (6.0 版或更新版本) |
| 可轉散發套件 | Windows 桌面搜尋 (WDS) 3.0 |