Función PropVariantToStringWithDefault (propvarutil.h)

Artículo
03/01/2024

Extrae el valor de propiedad de cadena de una estructura PROPVARIANT . Si no existe ningún valor, se devuelve el valor predeterminado especificado.

Sintaxis

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

Parámetros

[in] propvarIn

Tipo: REFPROPVARIANT

Referencia a una estructura PROPVARIANT de origen.

[in] pszDefault

Tipo: LPCWSTR

Puntero a un valor de cadena Unicode predeterminado, para su uso cuando no existe ningún valor actualmente. Puede ser NULL.

Valor devuelto

Tipo: PCWSTR

Devuelve el valor de cadena o el valor predeterminado, o el valor predeterminado.

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 y desea usar un valor predeterminado si no lo hace. Por ejemplo, una aplicación que obtiene valores de un almacén de propiedades puede usarlo para extraer de forma segura el valor de cadena para las propiedades de cadena.

Si el PROPVARIANT de origen tiene el tipo VT_LPWSTR o VT_BSTR, esta función auxiliar devuelve un puntero al valor del PROPVARIANT de origen. Si el PROPVARIANT de origen tiene el tipo VT_EMPTY o una conversión no es posible, PropVariantToStringWithDefault devolverá el valor predeterminado proporcionado por pszDefault.

Tenga en cuenta que esta función devolverá punteros a los datos proporcionados en los parámetros. Por lo tanto, la aplicación debe asegurarse de que los datos proporcionados a los parámetros permanecen válidos hasta que el resultado ya no esté en uso.

Ejemplos

En el ejemplo siguiente, para incluirse como parte de un programa mayor, se muestra cómo usar PropVariantToStringWithDefault 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.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         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