Edit

VariantToBuffer function (propvarutil.h)

  • Article

Extracts the contents of a buffer stored in a VARIANT structure of type VT_ARRRAY | VT_UI1.

Syntax

PSSTDAPI VariantToBuffer(
  [in]  REFVARIANT varIn,
  [out] void       *pv,
  [in]  UINT       cb
);

Parameters

[in] varIn

Type: REFVARIANT

Reference to a source VARIANT 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 size of the pv buffer, in bytes. The buffer should be the same size as the data to be extracted, or smaller.

Return value

Type: HRESULT

Returns one of the following values:

Return code Description
S_OK
 Data successfully extracted.
E_INVALIDARG
 The VARIANT was not of type VT_ARRRAY | VT_UI1.
E_FAIL
 The VARIANT buffer value had fewer than cb bytes.

Remarks

This function is used when the calling application expects a VARIANT to hold a buffer value. The calling application should check that the value has the expected length before it calls this function.

If the source VARIANT has type VT_ARRAY | VT_UI1, this function extracts the first cb bytes from the structure and places them in the buffer pointed to by pv.

If the stored value has fewer than cb bytes, then VariantToBuffer fails and the buffer is not modified.

If the value has more than cb bytes, then VariantToBuffer succeeds and truncates the value.

Examples

The following example, to be included as part of a larger program, demonstrates how to use VariantToBuffer to access a structure that has been stored in a VARIANT.

// VARIANT var;
// Assume variable var is initialized and valid. 
// The application expects var to hold a WIN32_FIND_DATAW structure 
// with sizeof(WIN32_FIND_DATAW) bytes.

HRESULT hr = E_UNEXPECTED;

// Verify that the value length is acceptable before you call VariantToBuffer.
if (VariantGetElementCount(var) == sizeof(WIN32_FIND_DATAW))
{
    WIN32_FIND_DATAW wfd;

    hr = VariantToBuffer(var, &wfd, sizeof(wfd));

    if (SUCCEEDED(hr))
    {
        // wfd is now initialized.
    }
}

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

InitVariantFromBuffer

PropVariantToBuffer