Función PropVariantToStringVectorAlloc (propvarutil.h)

Artículo
03/15/2023

Extrae datos de una estructura PROPVARIANT en cadenas recién asignadas en un vector recién asignado.

Sintaxis

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

Parámetros

[in] propvar

Tipo: REFPROPVARIANT

Referencia a una estructura PROPVARIANT de origen.

[out] pprgsz

Tipo: PWSTR**

Cuando se devuelve esta función, contiene un puntero a un vector de cadenas extraídas de la estructura PROPVARIANT de origen.

[out] pcElem

Tipo: ULONG*

Cuando esta función vuelve, contiene el recuento de elementos de cadena extraídos de la estructura PROPVARIANT de origen.

Valor devuelto

Tipo: HRESULT

Esta función puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	Devuelve S_OK si se ejecuta correctamente o un valor de error de lo contrario.
E_INVALIDARG	El PROPVARIANT no era del tipo adecuado.

Comentarios

Esta función auxiliar se usa en lugares donde la aplicación que realiza la llamada espera que un PROPVARIANT contenga un vector de valores de cadena.

Esta función auxiliar funciona para los siguientes tiposPROPVARIANT :

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Si el PROPVARIANT de origen tiene un tipo admitido, esta función extrae un vector de valores de cadena en un vector recién asignado de cadenas recién asignadas. La aplicación que realiza la llamada es responsable de usar CoTaskMemFree para liberar las cadenas contenidas en el vector de salida y el propio vector de salida, cuando ya no son necesarios.

Si un BSTR en el PROPVARIANT de origen es NULL, esta función colocará una cadena recién asignada que contenga "" en el vector de salida.

Ejemplos

En el ejemplo siguiente, para incluirse como parte de un programa más grande, se muestra cómo usar PropVariantToStringVectorAlloc para tener acceso a un valor de vector de cadena en un 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);
}

Requisitos


Cliente mínimo compatible	Windows XP con SP2, Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 con SP1 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	propvarutil.h
Library	Propsys.lib
Archivo DLL	Propsys.dll (versión 6.0 o posterior)
Redistribuible	Windows Desktop Search (WDS) 3.0