Función PSFormatForDisplayAlloc (propsys.h)
Obtiene una representación de cadena Unicode con formato de un valor de propiedad almacenado en una estructura PROPVARIANT . Esta función asigna memoria para la cadena de salida.
Sintaxis
PSSTDAPI PSFormatForDisplayAlloc(
[in] REFPROPERTYKEY key,
[in] REFPROPVARIANT propvar,
[in] PROPDESC_FORMAT_FLAGS pdff,
[out] PWSTR *ppszDisplay
);
Parámetros
[in] key
Tipo: REFPROPERTYKEY
Referencia a propertykey que asigna un nombre a la propiedad cuyo valor se está recuperando.
[in] propvar
Tipo: REFPROPVARIANT
Referencia a una estructura PROPVARIANT que contiene el tipo y el valor de la propiedad.
[in] pdff
Tipo: PROPDESC_FORMAT_FLAGS
Una o varias marcas que especifican el formato que se va a aplicar a la cadena de propiedad. Consulte PROPDESC_FORMAT_FLAGS para ver los valores posibles.
[out] ppszDisplay
Tipo: PWSTR*
Cuando la función devuelve, contiene un puntero a una representación de cadena Unicode terminada en null del valor de propiedad solicitado.
Valor devuelto
Tipo: HRESULT
Devuelve uno de los valores siguientes.
| Código devuelto | Descripción |
|---|---|
|
La cadena con formato se creó correctamente. S_OK junto con una cadena de retorno vacía indica que había una cadena de entrada vacía o un valor no vacío con formato de cadena vacía. |
|
No se creó la cadena con formato. S_FALSE junto con una cadena de retorno vacía indica que la cadena vacía resultó de un VT_EMPTY. |
|
Indica que se produjo un error en la asignación. |
Comentarios
Esta función llama a la implementación del subsistema de esquema de IPropertySystem::FormatForDisplayAlloc. Esa llamada proporciona una representación de cadena Unicode de un valor de propiedad, con formato adicional basado en una o varias PROPDESC_FORMAT_FLAGS. Si el subsistema de esquema no reconoce propertykey , IPropertySystem::FormatForDisplayAlloc intenta dar formato al valor según el VARTYPE del valor.
Debe inicializar component Object Model (COM) con CoInitialize o OleInitialize antes de llamar a PSFormatForDisplayAlloc.
La función asigna memoria a través de CoTaskMemAlloc y devuelve un puntero a esa memoria a través del parámetro ppszDisplay . La aplicación que realiza la llamada debe usar CoTaskMemFree para liberar ese recurso cuando ya no sea necesario.
El propósito de esta función es convertir los datos en una cadena adecuada para mostrar al usuario. El valor tiene el formato según la configuración regional actual, el idioma del usuario, el PROPDESC_FORMAT_FLAGS y la descripción de la propiedad especificada por la clave de propiedad. Para obtener información sobre cómo el esquema de descripción de propiedades influye en el formato del valor, vea los temas siguientes:
Normalmente, el PROPDESC_FORMAT_FLAGS se usa para modificar el formato prescrito por la descripción de la propiedad.La cadena de salida puede contener caracteres direccionales Unicode. Estos caracteres sin espaciado influyen en el algoritmo bidireccional Unicode para que los valores aparezcan correctamente cuando un lenguaje de izquierda a derecha (LTR) se dibuja en una ventana de derecha a izquierda (RTL) o se dibuja una RTL en una ventana LTR. Estos caracteres incluyen lo siguiente: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".
Las siguientes propiedades usan formatos especiales y no se ven afectados por el PROPDESC_FORMAT_FLAGS. Tenga en cuenta que los ejemplos citados son para cadenas con una configuración regional actual establecida en inglés; normalmente, la salida se localiza excepto donde se indica.
| Propiedad | Formato |
|---|---|
| System.FileAttributes | Los siguientes atributos de archivo se convierten en letras y se anexan para crear una cadena (por ejemplo, un valor de 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) se convierte en "RCO"):
|
| System.Photo.ISOSpeed | Por ejemplo, "ISO-400". |
| System.Photo.ShutterSpeed |
El valor de APEX se convierte en un tiempo de exposición mediante esta fórmula:
Por ejemplo, "2 s". o "1/125 s.". |
| System.Photo.ExposureTime | Por ejemplo, "2 s". o "1/125 s." |
| System.Photo.Aperture |
El valor de APEX se convierte en un número F mediante esta fórmula:
Por ejemplo, "f/5.6". |
| System.Photo.FNumber | Por ejemplo, "f/5.6". |
| System.Photo.SubjectDistance | Por ejemplo, "15 m" o "250 mm". |
| System.Photo.FocalLength | Por ejemplo, "50 mm". |
| System.Photo.FlashEnergy | Por ejemplo, "500 bpcs". |
| System.Photo.ExposureBias | Por ejemplo, "-2 step", "0 step" o "+3 step". |
| System.Computer.DecoratedFreeSpace | Por ejemplo, "105 MB libres de 13,2 GB". |
| System.ItemType | Por ejemplo, "Application" o "JPEG Image". |
| System.ControlPanel.Category | Por ejemplo, "Apariencia y personalización". |
| System.ComputerName | Por ejemplo, "LITWARE05 (este equipo)" o "testbox07". |
Si la clave de propiedad no corresponde a una descripción de propiedad en cualquiera de los esquemas de propiedad registrados, esta función elige un formato basado en el tipo del valor.
| Tipo del valor | Formato |
|---|---|
| VT_BOOLEAN | No compatible. |
| VT_FILETIME | Cadena de fecha y hora especificada por PROPDESC_FORMAT_FLAGS y la configuración regional actual. PDFF_SHORTTIME y PDFF_SHORTDATE son el valor predeterminado. Por ejemplo, "11/13/2006 3:22 PM". |
| VARTYPE numérico | Cadena decimal en la configuración regional actual. Por ejemplo, "42". |
| VT_LPWSTR u otro | Convertido en una cadena. Las secuencias de "\r", "\t" o "\n" se reemplazan por un solo espacio. |
| VT_VECTOR | Nada | Valores separados por punto y coma. Se usa un punto y coma independientemente de la configuración regional. |
Ejemplos
En el ejemplo siguiente, para incluirse como parte de un programa más grande, se muestra cómo usar PSFormatForDisplayAlloc para dar formato a un valor de clasificación.
PROPVARIANT propvar;
HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);
if (SUCCEEDED(hr))
{
PWSTR pszValue;
hr = PSFormatForDisplayAlloc(PKEY_Rating, propvar, PDFF_DEFAULT, &pszValue);
if (SUCCEEDED(hr))
{
// pszValue contains a formatted string similar to "3 stars".
CoTaskMemFree(pszValue);
}
PropVariantClear(&propvar);
}
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | propsys.h |
| Library | Propsys.lib |
| Archivo DLL | Propsys.dll (versión 6.0 o posterior) |
| Redistribuible | Búsqueda de escritorio de Windows (WDS) 3.0 |