Export (0) Print
Expand All
Expand Minimize

PropVariantToBuffer function

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

Syntax


HRESULT PropVariantToBuffer(
  _In_   REFPROPVARIANT propvar,
  _Out_  VOID *pv,
  _In_   UINT cb
);

Parameters

propvar [in]

Type: REFPROPVARIANT

The source PROPVARIANT structure.

pv [out]

Type: VOID*

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

cb [in]

Type: UINT

The buffer length, in bytes.

Return value

Type: HRESULT

This function can return one of these values.

Return codeDescription
S_OK

If successful, or an error value otherwise.

E_INVALIDARG

ThePROPVARIANTwas of the wrong type.

E_FAIL

ThePROPVARIANTvalue had fewer than cb bytes.

 

Remarks

This function is used in places where the calling application expects aPROPVARIANTto 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

Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 with SP1 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propvarutil.h

Library

Propsys.lib

DLL

Propsys.dll (version 6.0 or later)

See also

InitPropVariantFromBuffer
VariantToBuffer

 

 

Community Additions

ADD
Show:
© 2014 Microsoft