Função PSFormatForDisplayAlloc (propsys.h)

Artigo
08/25/2023

Obtém uma representação de cadeia de caracteres Unicode formatada de um valor de propriedade armazenado em uma estrutura PROPVARIANT . Essa função aloca memória para a cadeia de caracteres de saída.

Sintaxe

PSSTDAPI PSFormatForDisplayAlloc(
  [in]  REFPROPERTYKEY        key,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] PWSTR                 *ppszDisplay
);

Parâmetros

[in] key

Tipo: REFPROPERTYKEY

Referência a um PROPERTYKEY que nomeia a propriedade cujo valor está sendo recuperado.

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT que contém o tipo e o valor da propriedade .

[in] pdff

Tipo: PROPDESC_FORMAT_FLAGS

Um ou mais sinalizadores que especificam o formato a ser aplicado à cadeia de caracteres de propriedade. Consulte PROPDESC_FORMAT_FLAGS para obter valores possíveis.

[out] ppszDisplay

Tipo: PWSTR*

Quando a função retorna, contém um ponteiro para uma representação de cadeia de caracteres Unicode terminada em nulo do valor da propriedade solicitada.

Retornar valor

Tipo: HRESULT

Retorna um dos valores a seguir.

Código de retorno	Descrição
S_OK	A cadeia de caracteres formatada foi criada com êxito. S_OK juntamente com uma cadeia de caracteres de retorno vazia indica que havia uma cadeia de caracteres de entrada vazia ou um valor não vazio que foi formatado como uma cadeia de caracteres vazia.
S_FALSE	A cadeia de caracteres formatada não foi criada. S_FALSE junto com uma cadeia de caracteres de retorno vazia indica que a cadeia de caracteres vazia resultou de um VT_EMPTY.
E_OUTOFMEMORY	Indica que a alocação falhou.

Comentários

Essa função chama a implementação do subsistema de esquema de IPropertySystem::FormatForDisplayAlloc. Essa chamada fornece uma representação de cadeia de caracteres Unicode de um valor de propriedade, com formatação adicional com base em uma ou mais PROPDESC_FORMAT_FLAGS. Se PROPERTYKEY não for reconhecido pelo subsistema de esquema, IPropertySystem::FormatForDisplayAlloc tentará formatar o valor de acordo com VARTYPE do valor.

Você deve inicializar o COM (Component Object Model) com CoInitialize ou OleInitialize antes de chamar PSFormatForDisplayAlloc.

A função aloca memória por meio de CoTaskMemAlloc e retorna um ponteiro para essa memória por meio do parâmetro ppszDisplay . O aplicativo de chamada deve usar CoTaskMemFree para liberar esse recurso quando ele não for mais necessário.

A finalidade dessa função é converter dados em uma cadeia de caracteres adequada para exibição para o usuário. O valor é formatado de acordo com a localidade atual, o idioma do usuário, o PROPDESC_FORMAT_FLAGS e a descrição da propriedade especificada pela chave de propriedade. Para obter informações sobre como o esquema de descrição da propriedade influencia a formatação do valor, consulte os seguintes tópicos:

Normalmente, os PROPDESC_FORMAT_FLAGS são usados para modificar o formato prescrito pela descrição da propriedade.

A cadeia de caracteres de saída pode conter caracteres direcionais Unicode. Esses caracteres sem espaçamento influenciam o algoritmo bidirecional Unicode para que os valores apareçam corretamente quando uma linguagem LTR (da esquerda para a direita) é desenhada em uma janela da direita para a esquerda (RTL) ou uma RTL é desenhada em uma janela LTR. Esses caracteres incluem o seguinte: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

As propriedades a seguir usam formatos especiais e não são afetadas pelo PROPDESC_FORMAT_FLAGS. Observe que os exemplos citados são para cadeias de caracteres com uma localidade atual definida como inglês; normalmente, a saída é localizada, exceto quando indicada.

Propriedade	Formatar
System.FileAttributes	Os atributos de arquivo a seguir são convertidos em letras e acrescentados para criar uma cadeia de caracteres (por exemplo, um valor de 0x1801 (FILE_ATTRIBUTE_READONLY \| FILE_ATTRIBUTE_COMPRESSED \| FILE_ATTRIBUTE_OFFLINE) é convertido em "RCO"): FILE_ATTRIBUTE_READONLY (0x00000001) – 'R' FILE_ATTRIBUTE_SYSTEM (0x00000004) – 'S' FILE_ATTRIBUTE_ARCHIVE (0x00000020) -'A' FILE_ATTRIBUTE_COMPRESSED (0x00000800) – 'C' FILE_ATTRIBUTE_ENCRYPTED (0x00004000) – 'E' FILE_ATTRIBUTE_OFFLINE (0x00001000) – 'O' FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (0x00002000) – 'I'
System.Photo.ISOSpeed	Por exemplo, "ISO-400".
System.Photo.ShutterSpeed	O valor APEX é convertido em um tempo de exposição usando esta fórmula: `Exposure_time = 2^(-APEX_value)` Por exemplo, "2 s". ou "1/125 s".
System.Photo.ExposureTime	Por exemplo, "2 s". ou "1/125 s".
System.Photo.Aperture	O valor APEX é convertido em um número F usando esta fórmula: `F_Number = 2^(APEX_Value / 2)` Por exemplo, "f/5.6".
System.Photo.FNumber	Por exemplo, "f/5.6".
System.Photo.SubjectDistance	Por exemplo, "15 m" ou "250 mm".
System.Photo.FocalLength	Por exemplo, "50 mm".
System.Photo.FlashEnergy	Por exemplo, "500 bpcs".
System.Photo.ExposureBias	Por exemplo, "-2 etapa", "0 etapa" ou "+3 etapa".
System.Computer.DecoratedFreeSpace	Por exemplo, "105 MB livre de 13,2 GB".
System.ItemType	Por exemplo, "Application" ou "JPEG Image".
System.ControlPanel.Category	Por exemplo, "Aparência e Personalização".
System.ComputerName	Por exemplo, "LITWARE05 (este computador)" ou "testbox07".

Se a chave de propriedade não corresponder a uma descrição de propriedade em nenhum dos esquemas de propriedade registrados, essa função escolherá um formato com base no tipo do valor.

Tipo do valor	Formatar
VT_BOOLEAN	Não há suporte.
VT_FILETIME	Cadeia de caracteres de data/hora, conforme especificado por PROPDESC_FORMAT_FLAGS e a localidade atual. PDFF_SHORTTIME e PDFF_SHORTDATE são o padrão. Por exemplo, "13/11/2006 15:22".
VARTYPE numérico	Cadeia de caracteres decimal na localidade atual. Por exemplo, "42".
VT_LPWSTR ou outro	Convertido em uma cadeia de caracteres. Sequências de "\r", "\t" ou "\n" são substituídas por um único espaço.
VT_VECTOR \| Nada	Valores separados por ponto e vírgula. Um ponto e vírgula é usado independentemente da localidade.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PSFormatForDisplayAlloc para formatar um valor de classificação.

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	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	propsys.h
Biblioteca	Propsys.lib
DLL	Propsys.dll (versão 6.0 ou posterior)
Redistribuível	Pesquisa da Área de Trabalho do Windows (WDS) 3.0

Confira também

PSFormatForDisplay

PSFormatPropertyValue

Esquema de descrição da propriedade

Compartilhar via

Função PSFormatForDisplayAlloc (propsys.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Exemplos

Requisitos

Confira também

Comentários

Comentários

Recursos adicionais