PropVariantToStringVectorAlloc function (propvarutil.h)

Extracts data from a PROPVARIANT structure into a newly allocated strings in a newly allocated vector.

Syntax

PSSTDAPI PropVariantToStringVectorAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          **pprgsz,
  [out] ULONG          *pcElem
);

Parameters

[in] propvar

Type: REFPROPVARIANT

Reference to a source PROPVARIANT structure.

[out] pprgsz

Type: PWSTR**

When this function returns, contains a pointer to a vector of strings extracted from source PROPVARIANT structure.

[out] pcElem

Type: ULONG*

When this function returns, contains the count of string elements extracted from source PROPVARIANT structure.

Return value

Type: HRESULT

This function can return one of these values.

Remarks

This helper function is used in places where the calling application expects a PROPVARIANT to hold a vector of string values.

This helper function works for the followingPROPVARIANT types:

• VT_VECTOR | VT_LPWSTR
• VT_VECTOR | VT_BSTR
• VT_ARRAY | VT_BSTR

If a BSTR in the source PROPVARIANT is NULL, this function will place a newly allocated string containing "" into the output vector.

Examples

The following example, to be included as part of a larger program, demonstrates how to use PropVariantToStringVectorAlloc to access a string vector value in a PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Keywords, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Keywords is expected to produce a VT_VECTOR | VT_LPWSTR, or VT_EMPTY
         // PropVariantToStringVectorAlloc will return an error for VT_EMPTY
         LPWSTR *prgKeywords;
         ULONG cElem;
         hr = PropVariantToStringVectorAlloc (propvar, &prgKeywords, &cElem);
         if (SUCCEEDED(hr))
         {
                 // prgKeywords contains cElem strings
                 for (ULONG i = 0; i < cElem; i++)
                 {
                          CoTaskMemFree(prgKeywords[i]);
                 }
                 CoTaskMemFree(prgKeywords);
         }
         else
         {
                 // propvar either is VT_EMPTY, or contains something other than a vector of  strings
         }
         PropVariantClear(&propvar);
}

Requirements

See also

InitPropVariantFromStringVector

PropVariantGetStringElem

PropVariantToString

PropVariantToStringVector

VariantToStringArray