Edit

PropVariantToBuffer function (propvarutil.h)

  • Article

Extracts the buffer value from a PROPVARIANT structure of type VT_VECTOR | VT_UI1 or VT_ARRRAY | VT_UI1.

Syntax

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

Parameters

[in] propvar

Type: REFPROPVARIANT

The source PROPVARIANT structure.

[out] pv

Type: VOID*

Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value.

[in] cb

Type: UINT

The buffer length, in bytes.

Return value

Type: HRESULT

This function can return one of these values.

Return code Description
S_OK
 If successful, or an error value otherwise.
E_INVALIDARG
 ThePROPVARIANT was of the wrong type.
E_FAIL
 ThePROPVARIANT value had fewer than cb bytes.

Remarks

This function is used in places where the calling application expects aPROPVARIANT to hold a buffer value. The calling application should check that the value has the expected length before calling this function.

If the source PROPVARIANT has type VT_VECTOR | VT_UI1 or VT_ARRAY | VT_UI1, this function extracts the first cb bytes from the value and places them in the buffer pointed to by pv. If the value has fewer than cb bytes, then PropVariantToBuffer fails and the buffer is not modified. If the value has more than cb bytes, then PropVariantToBuffer succeeds and truncates the value.

Examples

The following example, to be included as part of a larger program, demonstrates how to use PropVariantToBuffer to access a structure that has been stored in a 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);
}

Requirements

Requirement Value
Minimum supported client Windows XP with SP2, Windows Vista [desktop apps only]
Minimum supported server Windows Server 2003 with SP1 [desktop apps only]
Target Platform Windows
Header propvarutil.h
Library Propsys.lib
DLL Propsys.dll (version 6.0 or later)
Redistributable Windows Desktop Search (WDS) 3.0

See also

InitPropVariantFromBuffer

VariantToBuffer