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