Função PSFormatForDisplayAlloc (propsys.h)
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 |
|---|---|
|
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. |
|
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. |
|
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"):
|
| 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 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 |