Función PropVariantToStringVector (propvarutil.h)

Artículo
03/15/2023

Extrae un vector de cadenas de una estructura PROPVARIANT .

Sintaxis

PSSTDAPI PropVariantToStringVector(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *prgsz,
  [in]  ULONG          crgsz,
  [out] ULONG          *pcElem
);

Parámetros

[in] propvar

Tipo: REFPROPVARIANT

Referencia a una estructura PROPVARIANT de origen.

[out] prgsz

Tipo: PWSTR*

Puntero a un vector de punteros de cadena. Cuando se devuelve esta función, el búfer se ha inicializado con elementos pcElem que apuntan a cadenas recién asignadas que contienen los datos extraídos del PROPVARIANT de origen.

[in] crgsz

Tipo: ULONG

Tamaño del búfer al que apunta prgsz, en elementos.

[out] pcElem

Tipo: ULONG*

Cuando se devuelve esta función, contiene el recuento de cadenas extraídas 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.
TYPE_E_BUFFERTOOSMALL	ElPROPVARIANT de origen contenía más de valores crgsz . El búfer al que apunta prgsz.
E_INVALIDARG	ElPROPVARIANT 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 con un número fijo de elementos.

Esta función funciona para los siguientes tipos PROPVARIANT :

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Si el PROPVARIANT de origen tiene un tipo admitido, esta función auxiliar extrae hasta los valores de cadena crgsz y coloca una copia asignada de cada una en el búfer a la que apunta prgsz . Si el PROPVARIANT contiene más elementos de los que caben en el búfer prgsz , esta función devuelve un error y establece pcElem en 0.

Puesto que cada cadena a la que apunta el búfer de salida se ha asignado recientemente, la aplicación que realiza la llamada es responsable de usar CoTaskMemFree para liberar cada cadena del búfer de salida cuando ya no son necesarias.

Si un BSTR en el PROPVARIANT de origen es NULL, se convierte en una cadena recién asignada que contiene "" en la salida.

Ejemplos

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid
LPWSTR rgszStrings; // The application is expecting propvar to hold 4 strings in a vector
ULONG cElems;
HRESULT hr = PropVariantToStringVector(propvar, rgszStrings, ARRAYSIZE(rgszStrings), &cElems);
if (SUCCEEDED(hr))
{
     if (cElems == ARRAYSIZE(rgszStrings))
     {
         // The application got 4 string which are now stored in rgszStrings
     }
     else
     {
         // The application got cElems which are stored in the first cElems elements of rgLongs
     }
 
    // Free the cElems strings that PropVariantToStringVector allocated
    for (ULONG i = 0; i < cElems; i++)
    {
        CoTaskMemFree(rgszStrings[i]);
    }
}

Requisitos

Requisito	Value
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