Compartilhar via

Método IShellFolder::GetDisplayNameOf (shobjidl_core.h)

  • Artigo

Recupera o nome de exibição do objeto de arquivo ou subpasta especificado.

Sintaxe

HRESULT GetDisplayNameOf(
  [in]  PCUITEMID_CHILD pidl,
  [in]  SHGDNF          uFlags,
  [out] STRRET          *pName
);

Parâmetros

[in] pidl

Tipo: PCUITEMID_CHILD

PIDL que identifica exclusivamente o objeto de arquivo ou a subpasta em relação à pasta pai.

[in] uFlags

Tipo: SHGDNF

Sinalizadores usados para solicitar o tipo de nome de exibição a ser retornado. Para obter uma lista de valores possíveis, consulte o tipo enumerado SHGDNF .

[out] pName

Tipo: STRRET*

Quando esse método retorna, contém um ponteiro para uma estrutura STRRET na qual retornar o nome de exibição. O tipo de nome retornado nessa estrutura pode ser o tipo solicitado, mas a pasta Shell pode retornar um tipo diferente.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

É responsabilidade do chamador liberar recursos alocados por essa função.

Normalmente, pidl pode se referir apenas a itens contidos na pasta pai. O PIDL deve ser de nível único e conter exatamente uma estrutura SHITEMID seguida por um zero de terminação. Se você quiser recuperar o nome de exibição de um item mais profundo do que um nível de distância da pasta pai, use SHBindToParent para associar à pasta pai imediata do item e, em seguida, passe o PIDL de nível único do item para IShellFolder::GetDisplayNameOf.

Além disso, se o sinalizador SHGDN_FORPARSING estiver definido em uFlags e o sinalizador SHGDN_INFOLDER não estiver definido, pidl poderá se referir a um objeto em qualquer nível abaixo da pasta pai na hierarquia de namespace. Ao mesmo tempo, pidl pode ser um PIDL de vários níveis, em relação à pasta pai, e pode conter várias estruturas SHITEMID . No entanto, isso não tem mais suporte e o pidl agora deve se referir apenas a um único item filho.

A maneira mais simples de recuperar o nome de exibição da estrutura apontada por pName é passá-lo para StrRetToBuf ou StrRetToStr. Essas funções pegam uma estrutura STRRET e retornam o nome. Você também pode examinar o membro uType da estrutura e recuperar o nome do membro apropriado.

Os sinalizadores especificados em uFlags são dicas sobre o uso pretendido do nome. Eles não garantem que IShellFolder retornará a forma solicitada do nome. Se esse formulário não estiver disponível, um diferente poderá ser retornado. Em particular, não há nenhuma garantia de que o nome retornado pelo sinalizador SHGDN_FORPARSING será analisado com êxito por IShellFolder::P arseDisplayName. Também há algumas combinações de sinalizadores que podem fazer com que a viagem de ida e volta GetDisplayNameOf/ParseDisplayName não retorne a lista de identificadores original. Essa ocorrência é excepcional, mas você deve marcar ter certeza.

Nota O nome de análise retornado quando uFlags tem o sinalizador SHGDN_FORPARSING definido não é necessariamente uma cadeia de caracteres de texto normal. Pastas virtuais como Meu Computador podem retornar uma cadeia de caracteres que contém o GUID do objeto de pasta no formato "::{GUID}". Os desenvolvedores que implementam IShellFolder::GetDisplayNameOf são incentivados a retornar nomes de análise o mais próximo possível dos nomes de exibição, pois o usuário final geralmente precisa digitar ou editar esses nomes.
 

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shobjidl_core.h (inclua Shobjidl.h)
DLL Shell32.dll (versão 4.0 ou posterior)

Confira também

Ishellfolder

IShellFolder2