Función PropVariantToStringAlloc (propvarutil.h)

Artículo
08/25/2023

Extrae un valor de propiedad de cadena de una estructura PROPVARIANT .

Sintaxis

PSSTDAPI PropVariantToStringAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *ppszOut
);

Parámetros

[in] propvar

Tipo: REFPROPVARIANT

Referencia a una estructura PROPVARIANT de origen.

[out] ppszOut

Tipo: PWSTR*

Cuando esta función devuelve , contiene un puntero al valor de propiedad extraído si existe uno.

Valor devuelto

Tipo: HRESULT

Si esta función se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

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

Si el PROPVARIANT de origen tiene el tipo VT_LPWSTR o VT_BSTR, esta función extrae la cadena en un búfer recién asignado. De lo contrario, intenta convertir el valor en la estructura PROPVARIANT en una cadena. Si no es posible una conversión, PropVariantToStringAlloc devolverá un código de error y establecerá ppszOut en NULL. Consulte PropVariantChangeType para obtener una lista de las posibles conversiones. Tenga en cuenta que VT_EMPTY se convierte correctamente en un búfer asignado que contiene "".

La aplicación que realiza la llamada es responsable de usar CoTaskMemFree para liberar la cadena a la que apunta ppszOut cuando ya no es necesaria.

Además de las conversiones proporcionadas por PropVariantChangeType, los siguientes casos especiales se aplican a PropVariantToStringAlloc.

Los PROPVARIANT con valores vectoriales se convierten en cadenas separando cada elemento con "; ". Por ejemplo, PropVariantToStringAlloc convierte un vector de 3 enteros, {3, 1, 4}, en la cadena "3; 1; 4". El punto y coma es independiente de la configuración regional actual.
VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT y VT_UNKNOWN valores se convierten en cadenas mediante una codificación no admitida. No es posible descodificar cadenas creadas de esta manera y el formato puede cambiar en el futuro.

Ejemplos

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStringAlloc will convert VT_EMPTY to "".

    LPWSTR pszTitle;

    hr = PropVariantToString(propvar, &pszTitle);

    if (SUCCEEDED(hr))

    {

        // pszTitle is now valid

    }

    else

    {

        // pszTitle is always NULL

    }

    PropVariantClear(&propvar);

}

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	Búsqueda de escritorio de Windows (WDS) 3.0