Función PropVariantToBSTR (propvarutil.h)
Extrae el valor de la propiedad BSTR de una estructura PROPVARIANT .
Sintaxis
PSSTDAPI PropVariantToBSTR(
[in] REFPROPVARIANT propvar,
[out] BSTR *pbstrOut
);
Parámetros
[in] propvar
Tipo: REFPROPVARIANT
Referencia a una estructura PROPVARIANT de origen.
[out] pbstrOut
Tipo: BSTR*
Puntero al valor de propiedad extraído si existe uno; de lo contrario, contiene una cadena vacía.
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 VT_BSTR o VT_LPWSTR, esta función extrae la cadena como un valor BSTR . De lo contrario, intenta convertir el valor de la estructura PROPVARIANT en una cadena. Si no es posible una conversión, PropVariantToBSTR devuelve un código de error y establece pbstrOut en NULL. Consulte PropVariantChangeType para obtener una lista de las posibles conversiones.
VT_EMPTY se convierte correctamente en un BSTR asignado que contiene "".
La aplicación que realiza la llamada es responsable de usar SysFreeString para liberar el BSTR al que apunta pbstrOut cuando ya no es necesario.
Además de las conversiones proporcionadas por PropVariantChangeType, los siguientes casos especiales se aplican a PropVariantToBSTR.
- Los PROPVARIANT con valores vectoriales se convierten en cadenas separando cada elemento con "; ". Por ejemplo, PropVariantToBSTR 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 a través de 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 más grande, se muestra cómo usar PropVariantToBSTR para tener acceso a un valor de cadena en un PROPVARIANT.
// IPropertyStore *ppropstore;
// Assume the 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.
// PropVariantToBSTR will convert VT_EMPTY to "".
BSTR bstrTitle;
hr = PropVariantToBSTR(propvar, &bstrTitle);
if (SUCCEEDED(hr))
{
// bstrTitle is now valid.
}
else
{
// bstrTitle 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 | Windows Desktop Search (WDS) 3.0 |