Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

InitPropVariantFromPropVariantVectorElem function

Initializes a PROPVARIANT structure based on a specified PROPVARIANT vector element.

Syntax


HRESULT InitPropVariantFromPropVariantVectorElem(
  _In_   REFPROPVARIANT propvarIn,
  _In_   ULONG iElem,
  _Out_  PROPVARIANT *ppropvar
);

Parameters

propvarIn [in]

Type: REFPROPVARIANT

The source PROPVARIANT structure.

iElem [in]

Type: ULONG

The index of the source PROPVARIANT structure element.

ppropvar [out]

Type: PROPVARIANT*

When this function returns, contains the initialized 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 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 a single value, iElem must be 0.

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

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 InitPropVariantFromPropVariantVectorElem in an iteration statement to access the values in a 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 ++)
{
    PROPVARIANT propvarElem = {0};

    hr = InitPropVariantFromPropVariantVectorElem(propvar, iElem, &propvarElem);

    if (SUCCEEDED(hr))
    {
        // propvarElem is now valid.

        PropVariantClear(&propvarElem);
    }
}

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

PropVariantGetElem

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.