Método IMoniker::GetDisplayName (objidl.h)

  • Artigo

Recupera o nome de exibição do moniker.

Sintaxe

HRESULT GetDisplayName(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [out] LPOLESTR *ppszDisplayName
);

Parâmetros

[in] pbc

Um ponteiro para a interface IBindCtx no contexto de associação a ser usado nesta operação. O contexto de associação armazena em cache objetos associados durante o processo de associação, contém parâmetros que se aplicam a todas as operações usando o contexto de associação e fornece os meios pelos quais a implementação do moniker deve recuperar informações sobre seu ambiente.

[in] pmkToLeft

Se o moniker fizer parte de um moniker composto, ponteiro para o moniker à esquerda deste moniker. Esse parâmetro é usado principalmente por implementadores de moniker para habilitar a cooperação entre os vários componentes de um moniker composto. Os clientes Moniker devem passar NULL.

[out] ppszDisplayName

O endereço de uma variável de ponteiro que recebe um ponteiro para a cadeia de caracteres de nome de exibição do moniker. A implementação deve usar IMalloc::Alloc para alocar a cadeia de caracteres retornada em ppszDisplayName e o chamador é responsável por chamar IMalloc::Free para liberá-la. Tanto o chamador quanto a implementação desse método usam o alocador de tarefas COM retornado por CoGetMalloc. Se ocorrer um erro, a implementação deverá definir *ppszDisplayName deve ser definida como NULL.

Valor retornado

Esse método pode retornar os valores de retorno padrão E_OUTOFMEMORY, bem como os valores a seguir.

Código de retorno Descrição
S_OK
 O método foi concluído com sucesso.
MK_E_EXCEEDEDDEADLINE
 A operação de associação não pôde ser concluída dentro do limite de tempo especificado pela estrutura de BIND_OPTS do contexto de associação.
E_NOTIMPL
 Não há nenhum nome de exibição.

Comentários

GetDisplayName fornece uma cadeia de caracteres que é uma representação exibivel do moniker. Um nome de exibição não é uma representação completa do estado interno de um moniker; é simplesmente um formulário que pode ser lido pelos usuários. Como resultado, é possível (embora raro) que dois monikers diferentes tenham o mesmo nome de exibição. Embora não haja nenhuma garantia de que o nome de exibição de um moniker possa ser analisado novamente nesse moniker ao chamar a função MkParseDisplayName com ele, a falha em fazê-lo é rara.

Anotações para chamadores

É possível que recuperar o nome de exibição de um moniker possa ser uma operação cara. Para obter eficiência, convém armazenar em cache os resultados da primeira chamada bem-sucedida para GetDisplayName, em vez de fazer chamadas repetidas.

Anotações aos implementadores

Se você estiver escrevendo uma classe moniker na qual o nome de exibição não é alterado, basta armazenar em cache o nome de exibição e fornecer o nome armazenado em cache quando solicitado. Se o nome de exibição puder ser alterado ao longo do tempo, obter o nome de exibição atual pode significar que o moniker precisa acessar o armazenamento do objeto ou associar-se ao objeto, ou seja, uma das quais pode ser operações caras. Se esse for o caso, sua implementação de GetDisplayName deverá retornar MK_E_EXCEEDEDDEADLINE se o nome não puder ser recuperado pelo tempo especificado na estrutura BIND_OPTS do contexto de associação.

Um moniker destinado a fazer parte de um moniker composto genérico deve incluir qualquer delimitador anterior (como '') como parte de seu nome de exibição. Por exemplo, o nome de exibição retornado por um moniker de item inclui o delimitador especificado quando ele foi criado com a função CreateItemMoniker . O nome de exibição de um moniker de arquivo não inclui um delimitador porque os monikers de arquivo sempre devem ser o componente mais à esquerda de uma composição.

Notas específicas da implementação

Implementação Observações
Anti-moniker Para cada anti-moniker contido neste moniker, esse método retorna uma instância de "\..".
Moniker de classe O nome de exibição para monikers de classe é da seguinte forma: clsid:string-clsid-no-curly-braces *[";" clsid-param=value]:. Por exemplo, clsid:a7b90590-36fd-11cf-857d-00aa006d2ea4:.
Moniker de arquivo Esse método retorna o caminho que o moniker representa.
Moniker composto genérico Esse método retorna a concatenação dos nomes de exibição retornados por cada moniker de componente da composição.
Moniker de item Esse método retorna a concatenação do delimitador e o nome do item que foram especificados quando o moniker do item foi criado.
Moniker OBJREF Esse método obtém o nome de exibição para o moniker OBJREF. O nome de exibição é uma codificação de 64 bits que encapsula o local do computador, o ponto de extremidade do processo e a ID do ponteiro de interface (IPID) do objeto em execução. Para compatibilidade futura, o nome de exibição é restrito a caracteres que podem ser especificados como parte de uma URL.
Moniker de ponteiro Esse método retorna E_NOTIMPL.
Moniker de URL O moniker de URL tenta retornar sua cadeia de caracteres de URL completa. Se o moniker tiver sido criado com uma cadeia de caracteres de URL parcial (consulte CreateURLMonikerEx), ele primeiro tentará encontrar um moniker de URL no contexto de associação em SZ_URLCONTEXT e, em seguida, procurará o moniker à esquerda para obter informações contextuais. Se não puder retornar sua cadeia de caracteres de URL completa, ela retornará sua cadeia de caracteres de URL parcial.

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [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 objidl.h

Confira também

Imoniker

Mkparsedisplayname