propVariantToString 函式 (propvarutil.h)

發行項
08/25/2023

從 PROPVARIANT 結構擷取字串值。

語法

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

參數

[in] propvar

類型： REFPROPVARIANT

來源 PROPVARIANT 結構的參考。

[out] psz

類型： PWSTR

指向字串緩衝區。當此函式傳回時，會以 Null 終止的 Unicode 字串值初始化緩衝區。

[in] cch

類型： UINT

psz所指向緩衝區的大小，以字元為單位。

傳回值

類型： HRESULT

此函式可以傳回下列其中一個值。

傳回碼	描述
S_OK	已擷取值，且結果緩衝區已終止 Null 。
STRSAFE_E_INSUFFICIENT_BUFFER	複製作業因為緩衝區空間不足而失敗。目的地緩衝區包含已截斷且以 Null 終止之預期結果的版本。在可接受截斷的情況下，這可能不一定被視為失敗狀況。
一些其他錯誤值	擷取因其他原因而失敗。

備註

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

如果來源 PROPVARIANT 有類型VT_LPWSTR或 VT_BSTR，此函式會擷取字串，並將它放入提供的緩衝區。否則，它會嘗試將 PROPVARIANT 結構中的值轉換成字串。如果無法轉換， PropVariantToString 會傳回失敗碼，並將 psz 設定為 '\0'。如需可能轉換的清單，請參閱 PropVariantChangeType 。請注意， VT_EMPTY 已成功轉換成「」。

除了終止 Null之外，最多 會將 cch-1個字元寫入 psz所指向的緩衝區。如果來源 PROPVARIANT 中的值比符合緩衝區長，則會將字串的截斷 Null 終止複本寫入緩衝區，且此函式會 傳回STRSAFE_E_INSUFFICIENT_BUFFER。產生的字串一律會以 Null 終止。

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

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

範例

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

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    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