Función PropVariantToStrRet (propvarutil.h)

Artículo
08/25/2023

Extrae una cadena de una estructura PROPVARIANT y la coloca en una estructura STRRET .

Sintaxis

PSSTDAPI PropVariantToStrRet(
  [in]  REFPROPVARIANT propvar,
  [out] STRRET         *pstrret
);

Parámetros

[in] propvar

Tipo: REFPROPVARIANT

Referencia a una estructura PROPVARIANT de origen.

[out] pstrret

Tipo: STRRET*

Apunta a la estructura STRRET . Cuando se devuelve esta función, la estructura se ha inicializado para contener una copia de la cadena extraída.

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 aplicaciones que desean convertir un valor de cadena en una estructura PROPVARIANT en una estructura STRRET . Por ejemplo, una aplicación que implementa IShellFolder::GetDisplayNameOf puede resultar útil para esta función.

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

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

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

Si la extracción se realiza correctamente, la función inicializará el miembro uType de la estructura STRRET con STRRET_WSTR y establecerá el miembro pOleStr de esa estructura para que apunte a una copia asignada de la cadena. La aplicación que realiza la llamada es responsable de usar CoTaskMemFree o StrRetToStr para liberar esta cadena cuando ya no se necesite.

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_FileName, &propvar);

if (SUCCEEDED(hr))

{

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

    // PropVariantToStrRet will convert VT_EMPTY to "".

    // If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET

    STRRET strName;

    hr = PropVariantToStrRet(propvar, &strName);

    if (SUCCEEDED(hr))

    {

        // strName is now valid

 

        if (strName.uType == STRRET_WSTR)

        {

            CoTaskMemFree(strName.pOleStr);

        }

    }

    else

    {

        // the extraction failed

    }

    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	Windows Desktop Search (WDS) 3.0