VariantToBuffer function (propvarutil.h)

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:

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

See also

InitVariantFromBuffer

PropVariantToBuffer