Função PSFormatPropertyValue (propsys.h)

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

Sintaxe

PSSTDAPI PSFormatPropertyValue(
  [in]  IPropertyStore        *pps,
  [in]  IPropertyDescription  *ppd,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] LPWSTR                *ppszDisplay
);

Parâmetros

[in] pps

Tipo: IPropertyStore*

Ponteiro para um IPropertyStore, que representa o repositório de propriedades do qual o valor da propriedade é obtido.

[in] ppd

Tipo: IPropertyDescription*

Ponteiro para um IPropertyDescription, que representa a propriedade cujo valor está sendo recuperado.

[in] pdff

Tipo: PROPDESC_FORMAT_FLAGS

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

[out] ppszDisplay

Tipo: LPWSTR*

Quando a função retorna, contém um ponteiro para o valor formatado como uma cadeia de caracteres Unicode terminada em nulo.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função usa o parâmetro ppd para chamar IPropertyDescription::FormatForDisplay. 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.

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

A função aloca memória e retorna um ponteiro para essa memória em ppszDisplay. O aplicativo de chamada deve usar CoTaskMemFree para liberar a cadeia de caracteres especificada por ppszDisplay quando ela não for mais necessária.

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:

• displayInfo
• Stringformat
• booleanFormat
• Numberformat
• NMDATETIMEFORMAT
• enumeratedList

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 PSFormatPropertyValue para formatar um valor de classificação.

// IPropertyStore *pStore;
// Assume the variable pps is initialized and valid.
IPropertyDescription *pPropDesc;

HRESULT hr = PSGetPropertyDescription(PKEY_Rating, IID_PPV_ARGS(&pPropDesc));

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatPropertyValue(pStore, pPropDesc, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
        CoTaskMemFree(pszValue);
    }
    pPropDesc->Release();
}

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

PSFormatForDisplayAlloc

Esquema de descrição da propriedade