IMAPIContainer::SetSearchCriteria

项目
04/04/2023

适用于：Outlook 2013 | Outlook 2016

为容器建立搜索条件。

HRESULT SetSearchCriteria(
  LPSRestriction lpRestriction,
  LPENTRYLIST lpContainerList,
  ULONG ulSearchFlags
);

参数

lpRestriction

[in]指向定义搜索条件的 SRestriction 结构的指针。如果在 lpRestriction 参数中传递 NULL，则再次使用此容器最近使用的搜索条件。不应在 lpRestriction 中为容器中的第一次搜索传递 NULL。

lpContainerList

[in]指向表示要包含在搜索中的容器的条目标识符数组的指针。如果客户端在 lpContainerList 参数中传递 NULL，则新搜索将使用最近用于搜索此容器的条目标识符。客户端不应在 lpContainerList 中为容器中的第一次搜索传递 NULL。

ulSearchFlags

[in]控制搜索执行方式的标志的位掩码。可以设置以下标志：

BACKGROUND_SEARCH

相对于其他搜索，搜索应以正常优先级运行。此标志不能与 FOREGROUND_SEARCH 标志同时设置。

FOREGROUND_SEARCH

相对于其他搜索，搜索应以高优先级运行。此标志不能与 BACKGROUND_SEARCH 标志同时设置。

NON_CONTENT_INDEXED_SEARCH

搜索不应使用内容索引来查找匹配的条目。此标志仅对 Exchange 存储有效。

RECURSIVE_SEARCH

搜索应包括 lpContainerList 参数中指定的容器及其所有子容器。此标志不能与 SHALLOW_SEARCH 标志同时设置。

RESTART_SEARCH

如果这是对 SetSearchCriteria 的第一次调用，则应启动搜索;如果搜索处于非活动状态，则应重新启动搜索。此标志不能与 STOP_SEARCH 标志同时设置。

SHALLOW_SEARCH

搜索应仅在 lpContainerList 参数中指定的容器中查找匹配项。此标志不能与 RECURSIVE_SEARCH 标志同时设置。

STOP_SEARCH

应停止搜索。此标志不能与 RESTART_SEARCH 标志同时设置。

返回值

S_OK

已成功设置搜索条件。

MAPI_E_TOO_COMPLEX

服务提供程序不支持指定的搜索条件。

备注

IMAPIContainer：：SetSearchCriteria 方法为支持搜索的容器（通常是搜索结果文件夹）建立搜索条件。搜索结果文件夹包含指向符合搜索条件的邮件的链接;实际消息仍存储在其原始位置。搜索结果文件夹中包含的唯一唯一数据是其内容表。应用搜索限制后，搜索结果文件夹的目录包含邮件存储的合并内容。

搜索操作仅适用于此合并的内容表;它不会搜索其他搜索结果文件夹。搜索结果仅返回与搜索条件匹配的邮件;不返回文件夹层次结构。

搜索完成后，控件将返回到客户端。

针对实现者的说明

通讯簿容器通过对其内容表应用限制来建立搜索条件。有关搜索条件和通讯簿容器的详细信息，请参阅实现高级搜索。

应支持对搜索结果文件夹中的邮件（而不是搜索结果文件夹本身）执行打开、复制、移动和删除操作。不允许在搜索结果文件夹中创建邮件或将其复制到搜索结果文件夹中。

给调用方的说明

若要搜索邮件收件人，请将 lpRestriction 设置为指向子对象限制，并将 SSubRestriction 结构中的 ulSubObject 成员设置为 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 。若要搜索附件，请将 ulSubObject 成员设置为 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 。将 lpRes 成员设置为指向描述收件人或附件搜索条件的属性限制。

例如，若要查找扩展名为 .mss 的文件附件，请将 ulSubObject 设置为 PR_MESSAGE_ATTACHMENTS ，将 lpRes 设置为与 PR_ATTACH_EXTENSION (PidTagAttachExtension) 与 .mss 匹配的属性限制。

在 ulSearchFlags 参数中设置FOREGROUND_SEARCH标志可能会导致系统性能降低。

可以使用 SetSearchCriteria 更改已在进行中的搜索的搜索条件。可以指定新的限制、要搜索的文件夹的新列表，以及新的搜索优先级，例如将搜索升级到更高的优先级。搜索优先级的更改不会导致现有搜索重启，但对搜索条件的其他更改可以。

使用搜索结果文件夹时，可以删除该文件夹或使其保持打开状态以供以后使用。如果确实删除了搜索结果文件夹，则只会删除邮件链接。实际邮件保留在其父文件夹中。

有关搜索结果文件夹的详细信息，请参阅 MAPI 搜索文件夹。

MFCMAPI 引用

有关 MFCMAPI 示例代码，请参阅下表。

文件	函数	Comment
HierarchyTableDlg.cpp	CHierarchyTableDlg：：OnEditSearchCriteria	MFCMAPI 使用 IMAPIContainer：：SetSearchCriteria 方法在用户编辑文件夹后为其编写搜索条件。