Función PSFormatForDisplay (propsys.h)

Artículo
03/05/2024

Obtiene una representación de cadena Unicode con formato de un valor de propiedad almacenado en una estructura PROPVARIANT . El autor de la llamada es responsable de asignar el búfer de salida.

Sintaxis

PSSTDAPI PSFormatForDisplay(
  [in]  REFPROPERTYKEY        propkey,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdfFlags,
  [out] LPWSTR                pwszText,
  [in]  DWORD                 cchText
);

Parámetros

[in] propkey

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] pdfFlags

Tipo: PROPDESC_FORMAT_FLAGS

Marca que especifica el formato que se va a aplicar a la cadena de propiedad. Consulte PROPDESC_FORMAT_FLAGS para ver los valores posibles.

[out] pwszText

Tipo: LPWSTR

Cuando la función devuelve, contiene un puntero al valor con formato como una cadena Unicode terminada en null. La aplicación que realiza la llamada es responsable de asignar memoria para el búfer antes de llamar a PSFormatForDisplay.

[in] cchText

Tipo: DWORD

Especifica la longitud del búfer en pwszText en WCHARs, incluido el carácter nulo de terminación.

Valor devuelto

Tipo: HRESULT

Devuelve uno de los valores siguientes.

Código devuelto	Descripción
S_OK	La cadena con formato se creó correctamente.
S_FALSE	No se creó la cadena con formato. S_FALSE indica que una cadena vacía ha resultado de un VT_EMPTY.
E_OUTOFMEMORY	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::FormatForDisplay. 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::FormatForDisplay 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 PSFormatPropertyValue.

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 se convierte en "RCO"):
	FILE_ATTRIBUTE_READONLY- "R"
	FILE_ATTRIBUTE_SYSTEM : "S"
	FILE_ATTRIBUTE_ARCHIVE -'A'
	FILE_ATTRIBUTE_COMPRESSED : "C"
	FILE_ATTRIBUTE_ENCRYPTED : "E"
	FILE_ATTRIBUTE_OFFLINE: "O"
	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED - "I"
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: `Exposure_time = 2^(-APEX_value)` 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: `F_Number = 2^(APEX_Value / 2)` 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 otros	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 PSFormatForDisplay para dar formato a un valor de clasificación.

PROPVARIANT propvar;

HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);

if (SUCCEEDED(hr))
{
    WCHAR szValue[100];

    hr = PSFormatForDisplay(PKEY_Rating, propvar, PDFF_DEFAULT, szValue, ARRAYSIZE(szValue));

    if (SUCCEEDED(hr))
    {
        // szValue contains a formatted string similar to "3 stars".
    }
    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	Windows Desktop Search (WDS) 3.0

Consulte también

PSFormatForDisplayAlloc

PSFormatPropertyValue

Esquema de descripción de propiedad

Compartir a través de

Función PSFormatForDisplay (propsys.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Consulte también

Comentarios

Recursos adicionales