Función PropVariantToString (propvarutil.h)

Artículo
03/15/2023

Extrae un valor de cadena de una estructura PROPVARIANT .

Sintaxis

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Parámetros

[in] propvar

Tipo: REFPROPVARIANT

Referencia a una estructura PROPVARIANT de origen.

[out] psz

Tipo: PWSTR

Apunta a un búfer de cadena. Cuando se devuelve esta función, el búfer se inicializa con un valor de cadena Unicode terminada en NULL .

[in] cch

Tipo: UINT

Tamaño del búfer al que apunta psz, en caracteres.

Valor devuelto

Tipo: HRESULT

Esta función puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	El valor se extrajo y el búfer de resultados finalizó NULL .
STRSAFE_E_INSUFFICIENT_BUFFER	Error en la operación de copia debido a un espacio de búfer insuficiente. El búfer de destino contiene una versión truncada terminada en null del resultado previsto. En situaciones en las que el truncamiento es aceptable, es posible que esto no se vea necesariamente como una condición de error.
Algún otro valor de error	Error en la extracción por algún otro motivo.

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. Por ejemplo, una aplicación que obtiene valores de un almacén de propiedades puede usarlo para extraer de forma segura un valor de cadena para las propiedades de cadena.

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

Además del valor NULL de terminación, se escriben como máximo caracteres cch-1 en el búfer al que apunta psz. Si el valor del PROPVARIANT de origen es más largo de lo que cabe en el búfer, se escribe una copia terminada EN NULL truncada de la cadena en el búfer y esta función devuelve STRSAFE_E_INSUFFICIENT_BUFFER. La cadena resultante siempre estará terminada en NULL .

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

Las PROPIEDADES PROPVARIANTcon valores vectoriales se convierten en cadenas separando cada elemento con "; ". Por ejemplo, PropVariantToString 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

En el ejemplo siguiente, para incluirse como parte de un programa mayor, se muestra cómo usar PropVariantToString para tener acceso a un valor de cadena en un PROPVARIANT.

// 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.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

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