IMAPITable::SortTable
Aplica-se a: Outlook 2013 | Outlook 2016
O método IMAPITable::SortTable ordena as linhas da tabela, dependendo dos critérios de classificação.
HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);
Parâmetros
lpSortCriteria
[in] Ponteiro para uma estrutura SSortOrderSet que contém os critérios de classificação a serem aplicados. Passar uma estrutura SSortOrderSet que contém zero colunas indica que a tabela não precisa ser classificada em nenhuma ordem específica.
ulFlags
[in] Bitmask de sinalizadores que controla o tempo da operação IMAPITable::SortTable . Os seguintes sinalizadores podem ser definidos:
TBL_ASYNC
Inicia a operação de forma assíncrona e retorna antes que a operação seja concluída.
TBL_BATCH
Adia a conclusão do tipo até que os dados na tabela sejam necessários.
Valor de retorno
S_OK
A operação de classificação foi bem-sucedida.
MAPI_E_BUSY
Outra operação está em andamento que impede o início da operação de classificação. A operação em andamento deve ser autorizada a ser concluída ou deve ser interrompida.
MAPI_E_NO_SUPPORT
A tabela não dá suporte ao tipo de classificação solicitada.
MAPI_E_TOO_COMPLEX
A tabela não pode executar a operação porque os critérios de classificação específicos apontados pelo parâmetro lpSortCriteria são muito complexos. SortTable pode retornar MAPI_E_TOO_COMPLEX nas seguintes condições.
Uma operação de classificação é solicitada para uma coluna de propriedade que a implementação não pode classificar.
A implementação não dá suporte à ordem de classificação solicitada no membro ulOrder da estrutura SSortOrderSet .
O número de colunas a serem classificadas, conforme especificado no membro cSorts no SSortOrderSet, é maior do que a implementação pode lidar.
Uma operação de classificação é solicitada, conforme indicado por uma marca de propriedade no SSortOrderSet, com base em uma propriedade que não está no conjunto disponível ou ativo e a implementação não dá suporte à classificação em propriedades que não estão no conjunto disponível.
Uma propriedade é especificada várias vezes em um conjunto de pedidos de classificação, conforme indicado por várias instâncias da mesma marca de propriedade, e a implementação não pode executar tal operação de classificação.
Uma operação de classificação baseada em colunas de propriedade multivalued é solicitada usando MVI_FLAG e a implementação não dá suporte à classificação em propriedades multivaloradas.
Uma marca de propriedade para uma propriedade no SSortOrderSet especifica uma propriedade ou tipo que a implementação não dá suporte.
Uma operação de classificação diferente de uma que prossegue pela tabela da propriedade PR_RENDERING_POSITION (PidTagRenderingPosition) é especificada apenas para uma tabela de anexo que dá suporte a esse tipo de classificação.
Comentários
O método IMAPITable::SortTable ordena as linhas em uma exibição de tabela. Enquanto algumas tabelas dão suporte à classificação padrão e categorizada em várias colunas de chave de classificação, outras tabelas são mais limitadas em seu suporte. Normalmente, os provedores de catálogo de endereços não dão suporte à classificação de tabela. Os provedores do repositório de mensagens geralmente dão suporte à classificação na medida em que mantêm a ordem de classificação de pastas que resulta quando uma tabela completa (uma tabela sem restrições) é classificada.
Algumas tabelas permitem que a classificação seja feita em qualquer coluna de tabela. Outras tabelas não; colunas não incluídas no modo de exibição de tabela não são afetadas por uma chamada sortTable . Algumas tabelas exigem que as chaves de classificação sejam criadas apenas com colunas no conjunto de colunas atual da tabela.
Uma tabela pode retornar MAPI_E_NO_SUPPORT ou MAPI_E_TOO_COMPLEX da Classificação quando não puder concluir uma operação de classificação. Além disso, os provedores de armazenamento não têm garantia de honrar o conjunto de pedidos de classificação especificado para tabelas de hierarquia.
Quando não há colunas na estrutura SSortOrderSet apontadas pelo parâmetro lpSortCriteria , a tabela retorna o conjunto de colunas atual. A ordem de classificação atual pode ser recuperada chamando o método IMAPITable::QuerySortOrder da tabela.
Todos os indicadores de uma tabela são invalidados e devem ser excluídos quando uma chamada para SortTable for feita e o indicador BOOKMARK_CURRENT que indica a posição atual do cursor, deve ser definido como o início da tabela.
Se você estiver classificando uma coluna que contém uma propriedade multivalued sem o conjunto de sinalizadores MVI_FLAG, os valores da coluna serão tratados como uma tupla completamente ordenada. Uma comparação de duas colunas multivalorizados compara os elementos de coluna em ordem, relatando a relação das colunas na primeira desigualdade e retorna a igualdade somente se as colunas que estão sendo comparadas contiverem os mesmos valores na mesma ordem. Se uma coluna tiver menos valores que a outra, a relação relatada será a de um valor nulo para o outro valor.
Notas para chamadores
SortTable opera de forma síncrona, a menos que você defina um dos sinalizadores. Se você definir o sinalizador TBL_BATCH, o SortTable adiará a operação de classificação, a menos que você solicite os dados. Se o sinalizador TBL_ASYNC for definido, a SortTable funcionará de forma assíncrona, potencialmente retornando antes da conclusão da operação.
Chame o método IMAPITable::Abort para interromper uma operação assíncrona em andamento se sua classificação precisar ser feita imediatamente. Se SortTable não puder continuar porque uma ou mais operações assíncronas na tabela estão em andamento, ela retornará MAPI_E_BUSY.
Para obter o melhor desempenho, chame SetColumns para personalizar o conjunto de colunas da tabela e Restringir para limitar o número de linhas na tabela antes de chamar SortTable para executar a classificação.
Sempre que SortTable falhar, a ordem de classificação que estava em vigor antes da falha ainda está em vigor.