PropVariantToStrRet 函式 (propvarutil.h)

發行項
03/05/2024

從 PROPVARIANT 結構擷取字串，並將它放入 STRRET 結構中。

語法

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

參數

[in] propvar

類型： REFPROPVARIANT

來源 PROPVARIANT 結構的參考。

[out] pstrret

類型： STRRET*

指向 STRRET 結構。當此函式傳回時，結構已初始化為包含所擷取字串的複本。

傳回值

類型： HRESULT

如果此函式成功，則會傳回 S_OK。否則，它會傳回 HRESULT 錯誤碼。

備註

這個協助程式函式用於想要將 PROPVARIANT 結構中的字串值轉換成 STRRET 結構的應用程式。例如，實作 IShellFolder：：GetDisplayNameOf 的應用程式可能會發現此函式很有用。

如果來源 PROPVARIANT 有類型VT_LPWSTR或VT_BSTR，此函式會擷取字串並將它放入 STRRET 結構中。否則，它會嘗試將 PROPVARIANT 結構中的值轉換成字串。如果無法轉換， PropVariantToString 會傳回失敗碼。如需可能的轉換清單，請參閱 PropVariantChangeType 。請注意，VT_EMPTY已成功轉換成 “ ”

除了 PropVariantChangeType 所提供的轉換之外，下列特殊案例也適用於 PropVariantToString。

向量值 PROPVARIANT會藉由使用 “; ”，將每個元素分隔成字串。例如， PropVariantToString 會將 3 個整數的向量 {3、1、4}轉換為字串 “3;1;4". 分號與目前的地區設定無關。
VT_BLOB、VT_STREAM、VT_STREAMED_OBJECT和VT_UNKNOWN值會使用不支援的編碼方式轉換成字串。無法以這種方式建立的字串譯碼，而且格式未來可能會變更。

如果擷取成功，函式將會使用 STRRET_WSTR 初始化 STRRET 結構的 uType 成員，並將該結構的 pOleStr 成員設定為指向字元串配置的複本。呼叫的應用程式負責在不再需要 CoTaskMemFree 或 StrRetToStr 時釋出此字串。

範例

下列範例要包含在較大的程式中，示範如何使用 PropVariantToString 來存取 PROPVARIANT 中的字串值。

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_FileName, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    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