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

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.

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.

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

Confira também

PSFormatForDisplay

PSFormatForDisplayAlloc

Esquema de descrição da propriedade