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:
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"):
|
| System.Photo.ISOSpeed | Por exemplo, "ISO-400". |
| System.Photo.ShutterSpeed |
O valor APEX é convertido em um tempo de exposição usando esta fórmula:
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:
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 |