3.2.5.4 Processing a RopSetSearchCriteria ROP Request

When the server receives a RopSetSearchCriteria ROP request buffer ([MS-OXCROPS] section 2.2.4.4) from the client, the server parses the buffer. The server responds with a RopSetSearchCriteria ROP response buffer. For details about how the server parses buffers and processes ROPs, see [MS-OXCROPS] section 3.2.5.1. For details about how the server formats buffers for the response, see [MS-OXCROPS] section 3.2.5.2.

The server fills the search folder according to the search criteria and search scope that are specified in the RopSetSearchCriteria ROP request. The messages that satisfy the search criteria appear as links in the search folder. When new search criteria are applied, the server modifies the search folder to include only the messages that match the new search criteria. The server can return the RopSetSearchCriteria ROP response before the search folder is fully updated.

For static search folders, the contents of the search folder are not updated after the initial population is complete. For dynamic search folders, the contents of the search folder MUST continue to be updated as messages move around the mailbox and start to match or cease to match the search criteria. A static search causes the search folder to be populated once with all messages that match the search criteria at the point in time when the search is started or restarted. The server MUST NOT update the search folder after the initial population when new messages that match the search criteria arrive in the search scope or when existing messages that fit the search criteria are deleted. To trigger an update, another RopSetSearchCriteria ROP request with the RESTART_SEARCH bit set in the SearchFlags field, as specified in section 2.2.1.4.1, is required. A dynamic search causes the search folder to be initially populated with all messages that match the search criteria at the point in time when the search is started or restarted. The server continues to update the search folder with messages that enter or exit the search criteria. A RopSetSearchCriteria ROP request with the STOP_SEARCH bit set does not have any effect on a dynamic search that has already completed its initial population and also does not change the dynamic nature of the search folder.

The server can use context indexing by default at the discretion of the server implementation. Whether it is used is usually based on the nature of the restriction that is used. When using context indexing in searches, the server allows the client to quickly search text in messages through the use of prebuilt indexes, while searches that are not content-indexed are based on a sequential scan of all the messages in the search scope and can be expensive. In the worst case, a search that is not content-indexed can involve the entire contents of the mailbox while holding an exclusive lock on the mailbox. A content-indexed search MAY<15> be static regardless of the value of the STATIC_SEARCH bit in the RopSetSearchCriteria ROP request.

Some differences between searches that are content-indexed and those that are not content-indexed are listed in the following table.

When the server receives a subsequent RopSetSearchCriteria ROP request in which neither STOP_SEARCH nor RESTART_SEARCH is set or in which neither RECURSIVE_SEARCH nor SHALLOW_SEARCH is set, the server SHOULD<16> use the default values.

If the STOP_SEARCH bit is set in the SearchFlags field, the server SHOULD stop the initial population of the search folder. Due to the asynchronous nature of the call, the server can complete the operation before the RopSetSearchCriteria ROP request with STOP_SEARCH is serviced. The server can take some time to stop and might not stop at all. If the RESTART_SEARCH bit is set in the SearchFlags field, the server restarts the population of the search folder.

If the client does not specify FIDs, as specified in ([MS-OXCDATA] section 2.2.1.1), in the initial RopSetSearchCriteria ROP request, the server fails the ROP with ecNotInitialized (0x80040605). If the client does not specify FIDs in a subsequent RopSetSearchCriteria ROP request, the server uses the FIDs that were specified in the previous request. If the client sets the search scope to include the search folder itself, the server SHOULD<17> fail the ROP with ecSearchFolderScopeViolation (0x00000490). If the client sets an invalid bit in the SearchFlags field, the server SHOULD<18> fail the ROP with the error code ecInvalidParam (0x80070057).

The following specific error codes apply to this ROP. For more details about ROP errors, see [MS-OXCDATA] section 2.4.