propVariantToBuffer 函式 (propvarutil.h)

從類型為 VT_VECTOR 的 PROPVARIANT 結構擷取緩衝區值 |VT_UI1或VT_ARRRAY |VT_UI1。

語法

PSSTDAPI PropVariantToBuffer(
  [in]  REFPROPVARIANT propvar,
  [out] void           *pv,
  [in]  UINT           cb
);

參數

[in] propvar

類型： REFPROPVARIANT

來源 PROPVARIANT 結構。

[out] pv

類型： VOID*

長度 為 cb 位元組的緩衝區指標。 當此函式傳回時，會包含所擷取緩衝區值的第一 個 cb 位元組。

[in] cb

類型： UINT

緩衝區長度，以位元組為單位。

傳回值

類型： HRESULT

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

傳回碼	描述
S_OK	如果成功，則為 ，否則為錯誤值。
E_INVALIDARG	PROPVARIANT 的類型錯誤。
E_FAIL	PROPVARIANT 值少於 cb 位元組。

備註

此函式用於呼叫應用程式預期PROPVARIANT 保留緩衝區值的位置。 呼叫的應用程式應該先檢查值是否具有預期的長度，然後再呼叫此函式。

如果來源 PROPVARIANT 的類型VT_VECTOR |VT_UI1或VT_ARRAY |VT_UI1，此函式會從 值擷取第一 個 cb 位元組，並將其放在 pv 所指向的緩衝區中。 如果值少於 cb 位元組， 則 PropVariantToBuffer 會失敗，而且不會修改緩衝區。 如果值超過 cb 位元組， 則 PropVariantToBuffer 會成功並截斷值。

範例

下列範例要包含在較大的程式中，示範如何使用 PropVariantToBuffer 來存取已儲存在 PROPVARIANT 中的結構。

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_FindData, &propvar);

if (SUCCEEDED(hr))
{
    // PKEY_FindData is expected to produce a VT_VECTOR | VT_UI1 with sizeof(WIN32_FIND_DATAW) bytes
    // We need to verify that the value length is acceptable before calling PropVariantToBuffer
    hr = E_UNEXPECTED;
    
    if (PropVariantGetElementCount(propvar) == sizeof(WIN32_FIND_DATAW))
    {
        WIN32_FIND_DATAW wfd;
        hr = PropVariantToBuffer(propvar, &wfd, sizeof(wfd));
        
        if (SUCCEEDED(hr))
        {
            // wfd is now initialized
        }
    }
    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

另請參閱

InitPropVariantFromBuffer

VariantToBuffer