InitVariantFromVariantArrayElem function (propvarutil.h)

Article
10/13/2021

Initializes a VARIANT structure with a value stored in another VARIANT structure.

Syntax

PSSTDAPI InitVariantFromVariantArrayElem(
  [in]  REFVARIANT varIn,
  [in]  ULONG      iElem,
  [out] VARIANT    *pvar
);

Parameters

[in] varIn

Type: REFVARIANT

Reference to the source VARIANT structure.

[in] iElem

Type: ULONG

Index of one of the source VARIANT structure elements.

[out] pvar

Type: VARIANT*

When this function returns, contains the initialized VARIANT structure.

Return value

Type: HRESULT

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This helper function works for VARIANT structures of the following types:

VT_BSTR
VT_BOOL
VT_I2
VT_I4
VT_I8
VT_U12
VT_U14
VT_U18
VT_DATE
VT_ARRAY | (any one of VT_BSTR, VT_BOOL, VT_I2, VT_I4, VT_I8, VT_U12, VT_U14, VT_U18, VT_DATE)

Additional types may be supported in the future.

This function extracts a single value from the source VARIANT structure and uses that value to initialize the output VARIANT structure. The calling application must use VariantClear to free the VARIANT referred to by pvar when it is no longer needed.

If the source VARIANT is an array, iElem must be less than the number of elements in the array.

If the source VARIANT has a single value, iElem must be 0.

If the source VARIANT is empty, this function always returns an error code.

You can use VariantGetElementCount to obtain the number of elements in the array or array.

Examples

The following example, to be included as part of a larger program, demonstrates how to use InitVariantFromVariantArrayElem in an iteration statement to access the values in a VARIANT.

// VARIANT var;
// Assume var is initialized and valid.
UINT cElem = VariantGetElementCount(var);
HRESULT hr = <mark type="const">S_OK</mark>;

for (UINT iElem = 0; SUCCEEDED(hr) && iElem < cElem; iElem ++)
{
    VARIANT varElem = {0};

    hr = InitVariantFromVariantArrayElem(var, iElem, &varElem);

    if (SUCCEEDED(hr))
    {
        // varElem is now valid.
        VariantClear(&varElem);
    }
}

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

Share via