IMAPIContainer::GetHierarchyTable

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Retorna um ponteiro para a tabela de hierarquia do contêiner.

HRESULT GetHierarchyTable(
  ULONG ulFlags,
  LPMAPITABLE FAR * lppTable
);

Parâmetros

ulFlags

[in] Um bitmask de sinalizadores que controla como as informações são retornadas na tabela. Os seguintes sinalizadores podem ser definidos:

CONVENIENT_DEPTH

Preenche a tabela de hierarquia com contêineres de vários níveis. Se CONVENIENT_DEPTH não estiver definido, a tabela de hierarquia conterá apenas os contêineres filho imediatos do contêiner.

MAPI_DEFERRED_ERRORS

GetHierarchyTable pode retornar com êxito, possivelmente antes que a tabela seja disponibilizada para o chamador. Se a tabela não estiver disponível, fazer uma chamada de tabela subsequente poderá gerar um erro.

MAPI_UNICODE

Solicita que as colunas que contêm dados de cadeia de caracteres sejam retornadas no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, as cadeias de caracteres deverão ser retornadas no formato ANSI.

SHOW_SOFT_DELETES

Mostra itens que atualmente são marcados como excluídos suavemente, ou seja, eles estão na fase de tempo de retenção de item excluído.

lppTable

[out] Um ponteiro para um ponteiro para a tabela de hierarquia.

Valor de retorno

S_OK

A tabela de hierarquia foi recuperada com êxito.

MAPI_E_BAD_CHARWIDTH

O sinalizador MAPI_UNICODE foi definido e a implementação não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e a implementação dá suporte apenas ao Unicode.

MAPI_E_NO_SUPPORT

O contêiner não tem contêineres filho e não pode fornecer uma tabela de hierarquia.

Comentários

O método IMAPIContainer::GetHierarchyTable retorna um ponteiro para a tabela de hierarquia de um contêiner. Uma tabela de hierarquia contém informações de resumo sobre os contêineres filho no contêiner. Tabelas de hierarquia de pastas contêm informações sobre subpastas; Tabelas de hierarquia do catálogo de endereços contêm informações sobre contêineres de catálogo de endereços filho e listas de distribuição.

É possível que alguns contêineres não tenham contêineres filho. Esses contêineres retornam MAPI_E_NO_SUPPORT de suas implementações do GetHierarchyTable.

Quando o sinalizador CONVENIENT_DEPTH é definido, cada linha na tabela de hierarquia também inclui a propriedade PR_DEPTH (PidTagDepth) como uma coluna. PR_DEPTH indica o nível de cada contêiner em relação ao contêiner que implementa a tabela. Os contêineres filho imediatos do contêiner de implementação estão em profundidade zero, os contêineres filho nos contêineres de profundidade zero estão em profundidade e assim por diante. Os valores de PR_DEPTH aumentam sequencialmente à medida que a hierarquia de níveis se aprofunda.

Para obter uma lista completa de colunas necessárias e opcionais em tabelas de hierarquia, consulte Tabelas de Hierarquia.

Observações para implementadores

Se você dá suporte a uma tabela de hierarquia para o contêiner, também deve fazer o seguinte:

Dê suporte a uma chamada para o método IMAPIProp::OpenProperty do contêiner para abrir a propriedade PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy).
Retorne PR_CONTAINER_HIERARCHY de uma chamada para os métodos IMAPIProp::GetPropList ou IMAPIProp::GetProps do contêiner.

Notas para chamadores

Colunas de tabela de conteúdo binário e cadeia de caracteres podem ser truncadas. Normalmente, os provedores retornam 255 caracteres. Como você não pode saber de antemão se uma tabela inclui colunas truncadas, suponha que uma coluna seja truncada se o comprimento da coluna for de 255 ou 510 bytes. Você sempre pode recuperar o valor completo de uma coluna truncada, se necessário, diretamente do objeto usando seu identificador de entrada para abri-lo e chamando o método IMAPIProp::GetProps .

Dependendo da implementação do provedor, as restrições e as operações de classificação podem ser aplicadas a toda a cadeia de caracteres ou à versão truncada dessa cadeia de caracteres. Além disso, os provedores de armazenamento não têm garantia de honrar o conjunto de pedidos de classificação SSortOrderSet especificado para tabelas de hierarquia.

Referência do MFCMAPI

Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.

Arquivo	Função	Comentário
HierarchyTableTreeCtrl.cpp	CHierarchyTableTreeCtrl::GetHierarchyTable	A classe CHierarchyTableTreeCtrl usa GetHierarchyTable para obter tabelas de hierarquia a serem exibidas em um controle de exibição de árvore.