PropVariantGetElem function (propvarutil.h)

Initializes a PROPVARIANT structure based on a specified element in another PROPVARIANT structure.

Syntax

HRESULT PropVariantGetElem(
  [in]  REFPROPVARIANT propvarIn,
  [in]  ULONG          iElem,
  [out] PROPVARIANT    *ppropvar
);

Parameters

[in] propvarIn

Type: REFPROPVARIANT

Reference to the source PROPVARIANT structure.

[in] iElem

Type: ULONG

Index of a PROPVARIANT structure element in propvarIn.

[out] ppropvar

Type: PROPVARIANT*

When this function returns, contains a PROPVARIANT with the value specified from the source PROPVARIANT 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 PROPVARIANT structures of the following types:

  • VT_LPWSTR
  • VT_BSTR
  • VT_BOOL
  • VT_I2
  • VT_I4
  • VT_I8
  • VT_U12
  • VT_U14
  • VT_U18
  • VT_FILETIME
  • VT_VECTOR | (any one of VT_LPWSTR, VT_BSTR, VT_BOOL, VT_I2, VT_I4, VT_I8, VT_U12, VT_U14, VT_U18, VT_FILETIME)
  • VT_ARRAY | (any one of VT_BSTR, VT_BOOL, VT_I2, VT_I4, VT_I8, VT_U12, VT_U14, VT_U18)
Additional types may be supported in the future.

This is an inline function, with its source code provided in the header. It is not included in any .dll or .lib file.

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

If the source PROPVARIANT is a vector or array, iElem must be less than the number of elements in the vector or array.

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

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

Note  You can use PropVariantGetElementCount to obtain the number of elements in the vector or array.
 

Examples

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

// PROPVARIANT propvar;
// Assume propvar is initialized and valid.

UINT cElem = PropVariantGetElementCount(propvar);
HRESULT hr = <mark type="const">S_OK</mark>;

for (UINT iElem = 0; SUCCEEDED(hr) && iElem < cElem; iElem ++)
{
   <xref rid="_stg_propvariant"/>propvarElem = {0};
    
    hr = PropVariantGetElem(propvar, iElem, &propvarElem);

    if (SUCCEEDED(hr))
    {
        // propvarElem is valid now.
        PropVariantClear(&propvarElem);
    }
}

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
Redistributable Windows Desktop Search (WDS) 3.0

See also

InitPropVariantFromPropVariantVectorElem