Compartilhar via


IMAPITable::Restrict

Aplica-se a: Outlook 2013 | Outlook 2016

Aplica um filtro a uma tabela, reduzindo o conjunto de linhas para apenas essas linhas que correspondem aos critérios especificados.

HRESULT Restrict(
LPSRestriction lpRestriction,
ULONG ulFlags
);

Parâmetros

lpRestriction

[in] Ponteiro para uma estrutura SRestriction definindo as condições do filtro. Passar NULL no parâmetro lpRestriction remove o filtro atual.

ulFlags

[in] Bitmask de sinalizadores que controla o tempo da operação de restrição. Os seguintes sinalizadores podem ser definidos:

TBL_ASYNC

Inicia a operação de forma assíncrona e retorna antes da conclusão da operação.

TBL_BATCH

Adia a avaliação do filtro até que os dados na tabela sejam necessários.

Valor de retorno

S_OK

O filtro foi aplicado com êxito.

MAPI_E_BUSY

Outra operação está em andamento que impede o início da operação de restrição. A operação em andamento deve ser autorizada a ser concluída ou deve ser interrompida.

MAPI_E_TOO_COMPLEX

A tabela não pode executar a operação porque o filtro específico apontado pelo parâmetro lpRestriction é muito complicado.

Comentários

O método IMAPITable::Restrict estabelece uma restrição ou filtro em uma tabela. Se houver uma restrição anterior, ela será descartada e a nova aplicada. A aplicação de uma restrição não afeta os dados subjacentes de uma tabela; ele simplesmente altera a exibição limitando as linhas que podem ser recuperadas em linhas que contêm dados que satisfaçam a restrição.

Há vários tipos diferentes de restrições, cada uma descrita com uma estrutura diferente. A estrutura SRestriction contém dois membros: um valor que indica o tipo de restrição e a estrutura específica aplicável a esse tipo.

As notificações para linhas de tabela ocultas do modo de exibição por chamadas para Restringir nunca são geradas.

Uma restrição de propriedade em uma propriedade multivalida funciona como uma restrição em uma propriedade de valor único. Uma propriedade multivalida a ser usada em uma restrição de propriedade deve ter o sinalizador MVI_FLAG definido. Se ele não tiver esse sinalizador definido, ele será tratado como uma tupla totalmente ordenada. Uma comparação de duas colunas multivalidas compara os elementos de coluna em ordem, relatando a relação das colunas na primeira desigualdade. A igualdade será retornada somente se as colunas 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.

Para obter mais informações sobre restrições, consulte Sobre restrições.

Observação

Se você criar consultas dinâmicas para pesquisar dados no servidor, use o método FindRow em vez de usar o método Restrict e o método QueryRows juntos. O método Restrict cria uma exibição em cache usada para avaliar todas as mensagens adicionadas ou modificadas na pasta base. Se um aplicativo cliente usar o método Restrict para cada consulta dinâmica, um modo de exibição armazenado em cache será criado para cada consulta.

Notas para chamadores

Para descartar a restrição atual sem criar uma nova, passe NULL em lpRestriction.

Se outra chamada de tabela assíncrona estiver em andamento, fazendo com que Restrict retorne MAPI_E_BUSY, você pode chamar IMAPITable::Abortar para interromper a chamada.

Restrição opera de forma síncrona, a menos que você defina um dos sinalizadores. Se você definir o sinalizador TBL_BATCH, Restringir adiará a avaliação da restrição, a menos que você solicite os dados. Se o sinalizador TBL_ASYNC for definido, Restriçãofuncionará de forma assíncrona, potencialmente retornando antes da conclusão da operação.

Todos os indicadores de uma tabela são descartados quando uma chamada para Restrição é feita e BOOKMARK_CURRENT, a posição atual do cursor, é definida como o início da tabela.

Se você tentar impor uma restrição de propriedade a uma propriedade que não esteja no conjunto de colunas da tabela, os resultados serão indefinidos. Sempre que você não tiver certeza se uma propriedade tem suporte em uma tabela, combine a restrição de propriedade com uma restrição existente. A restrição existe verifica a existência da propriedade antes de tentar impor a restrição de propriedade.

Não espere receber uma notificação de tabela em uma linha que foi filtrada de uma tabela devido a uma restrição.

Referência do MFCMAPI

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

Arquivo Função Comentário
ContentsTableListCtrl.cpp
CContentsTableListCtrl::ApplyRestriction
O MFCMAPI usa o método IMAPITable::Restrict para definir uma restrição em uma tabela.

Confira também

IMAPITable::Abort

IMAPITable::ExpandRow

IMAPITable::GetRowCount

IMAPITable::QueryRows

SPropertyRestriction

IMAPITable : IUnknown

MFCMAPI como exemplo de código