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. |