IMAPIContainer::SetSearchCriteria
Aplica-se a: Outlook 2013 | Outlook 2016
Estabelece critérios de pesquisa para o contêiner.
HRESULT SetSearchCriteria(
LPSRestriction lpRestriction,
LPENTRYLIST lpContainerList,
ULONG ulSearchFlags
);
Parâmetros
lpRestriction
[in] Um ponteiro para uma estrutura SRestriction que define os critérios de pesquisa. Se NULL for passado no parâmetro lpRestriction , os critérios de pesquisa usados mais recentemente para esse contêiner serão usados novamente. O NULL não deve ser passado em lpRestriction para a primeira pesquisa em um contêiner.
lpContainerList
[in] Um ponteiro para uma matriz de identificadores de entrada que representam contêineres a serem incluídos na pesquisa. Se um cliente passar NULL no parâmetro lpContainerList , os identificadores de entrada usados mais recentemente para pesquisar esse contêiner serão usados para a nova pesquisa. Um cliente não deve passar NULL no lpContainerList para a primeira pesquisa em um contêiner.
ulSearchFlags
[in] Um bitmask de sinalizadores que controlam como a pesquisa é executada. Os seguintes sinalizadores podem ser definidos:
BACKGROUND_SEARCH
A pesquisa deve ser executada com prioridade normal em relação a outras pesquisas. Esse sinalizador não pode ser definido ao mesmo tempo que o sinalizador FOREGROUND_SEARCH.
FOREGROUND_SEARCH
A pesquisa deve ser executada com alta prioridade em relação a outras pesquisas. Esse sinalizador não pode ser definido ao mesmo tempo que o sinalizador de BACKGROUND_SEARCH.
NON_CONTENT_INDEXED_SEARCH
A pesquisa não deve usar a indexação de conteúdo para encontrar entradas correspondentes. Esse sinalizador só é válido para repositórios do Exchange.
RECURSIVE_SEARCH
A pesquisa deve incluir os contêineres especificados no parâmetro lpContainerList e todos os contêineres filho. Esse sinalizador não pode ser definido ao mesmo tempo que o sinalizador SHALLOW_SEARCH.
RESTART_SEARCH
A pesquisa deve ser iniciada se essa for a primeira chamada para SetSearchCriteria ou reiniciada se a pesquisa estiver inativa. Esse sinalizador não pode ser definido ao mesmo tempo que o sinalizador STOP_SEARCH.
SHALLOW_SEARCH
A pesquisa deve procurar apenas nos contêineres especificados no parâmetro lpContainerList para entradas correspondentes. Esse sinalizador não pode ser definido ao mesmo tempo que o sinalizador RECURSIVE_SEARCH.
STOP_SEARCH
A pesquisa deve ser interrompida. Esse sinalizador não pode ser definido ao mesmo tempo que o sinalizador RESTART_SEARCH.
Valor de retorno
S_OK
Os critérios de pesquisa foram definidos com êxito.
MAPI_E_TOO_COMPLEX
O provedor de serviços não dá suporte aos critérios de pesquisa especificados.
Comentários
O método IMAPIContainer::SetSearchCriteria estabelece critérios de pesquisa para um contêiner que dá suporte a pesquisas, normalmente uma pasta de resultados de pesquisa. Uma pasta de resultados de pesquisa contém links para as mensagens que atendem aos critérios de pesquisa; as mensagens reais ainda são armazenadas em seus locais originais. Os únicos dados exclusivos contidos em uma pasta de resultados de pesquisa são sua tabela de conteúdo. A tabela de conteúdo de uma pasta de resultados de pesquisa tem o conteúdo mesclado do repositório de mensagens após a restrição de pesquisa ter sido aplicada.
Uma operação de pesquisa funciona apenas nesta tabela de conteúdo mesclada; ele não pesquisa em outras pastas de resultados de pesquisa. Os resultados da pesquisa retornam apenas as mensagens que correspondem aos critérios de pesquisa; a hierarquia de pastas não é retornada.
O controle é retornado ao cliente quando a pesquisa é concluída.
Observações para implementadores
Os contêineres do catálogo de endereços estabelecem critérios de pesquisa aplicando restrições às tabelas de conteúdo. Para obter mais informações sobre critérios de pesquisa e contêineres de catálogo de endereços, consulte Implementando pesquisa avançada.
Você deve dar suporte a operações abertas, copiar, mover e excluir nas mensagens dentro de pastas de resultados de pesquisa, não na pasta de resultados de pesquisa em si. Não permita que mensagens sejam criadas dentro ou copiadas em uma pasta de resultados de pesquisa.
Notas para chamadores
Para pesquisar destinatários de mensagens, defina lpRestriction para apontar para uma restrição de subobjecto com o membro ulSubObject na estrutura SSubRestriction definida como PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients). Para pesquisar anexos, defina o membro ulSubObject como PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments). Defina o membro lpRes para apontar para uma restrição de propriedade que descreve os critérios de pesquisa para os destinatários ou anexos.
Por exemplo, para procurar anexos de arquivo que tenham a extensão .mss, defina ulSubObject como PR_MESSAGE_ATTACHMENTS e lpRes para uma restrição de propriedade que corresponda PR_ATTACH_EXTENSION (PidTagAttachExtension) com .mss.
Definir o sinalizador FOREGROUND_SEARCH no parâmetro ulSearchFlags pode causar uma diminuição no desempenho do sistema.
Você pode usar SetSearchCriteria para alterar os critérios de pesquisa de uma pesquisa já em andamento. Você pode especificar novas restrições, novas listas de pastas a serem pesquisadas e uma nova prioridade de pesquisa, como atualizar uma pesquisa para uma prioridade maior. As alterações na prioridade de pesquisa não fazem com que uma pesquisa existente seja reiniciada, mas outras alterações nos critérios de pesquisa podem.
Ao usar uma pasta de resultados de pesquisa, você pode excluir a pasta ou deixá-la aberta para uso posterior. Se você excluir a pasta resultados da pesquisa, somente os links de mensagem serão excluídos. As mensagens reais permanecem em suas pastas pai.
Para obter mais informações sobre pastas de resultados de pesquisa, consulte Pastas de Pesquisa MAPI.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| HierarchyTableDlg.cpp |
CHierarchyTableDlg::OnEditSearchCriteria |
O MFCMAPI usa o método IMAPIContainer::SetSearchCriteria para gravar critérios de pesquisa para uma pasta depois que um usuário a editou. |