Edit File: Design.Storage.Mailbox.Search.txt
Mailbox Searching ================= 'mailbox_search_*()' functions should be used always when you're iterating through multiple messages. The search queries can be complex or as simple as "all messages". Without searching there's also a way to directly switch to a specific message by its sequence number or UID, but this should be avoided usually. Initializing ------------ Search is initialized with 'mailbox_search_init()' on top of a <transaction> [Design.Storage.Mailbox.Transaction.txt]. Although it would appear that a search is a read-only operation, it can actually write data to Dovecot's cache file. For example if you search for a specific header not yet in cache file, the results are saved to cache file so the next search will be fast. This is why you should always commit search transactions, even if the rest of your operation fails (you should use separate transactions for search and for updates if necessary). You'll need a search query. 'src/lib-storage/mail-search.h' and 'mail-search-build.h' contain all the functions and structures related to it. Usually you should start with 'mail_search_build_init()' and then start adding the search parameters, either manually or with one of the existing 'mail_search_build_add_*()' helper functions. The same search query structures can be saved and used for other searches later, but because search state is stored inside the structs you need to be careful that multiple searches aren't using them at the same time. This is usually more trouble than worth, so avoid doing it. Search results can be sorted by giving a sort program. Dovecot optimizes this by keeping sort indexes in the index files. Reading search results ---------------------- While 'mailbox_search_next()' returns TRUE, a new search result is found and it changes the given <mail> [Design.Storage.Mail.txt] to point to the search result. The mail's "wanted fields/headers" parameters don't need to include anything needed by the search query, Dovecot optimizes them internally. If the search needs to parse message bodies and the mailbox is large, this call can take a long time. If you want to do other things while searching, you can use 'mailbox_search_next_nonblock()' that does only a bit of work and then returns either with a result or "try again later" status. Dovecot attempts to keep each non-matching call to this function between 200 and 250 milliseconds, although the upper bound can't be guaranteed. It's possible that messages are being expunged while Dovecot is searching them, so it can't determine if they would have matched the search rule or not. In this case it skips over them, but if you want to know if this has happened, you can see if 'mailbox_search_seen_lost_data()' returns TRUE. Deinitializing -------------- 'mailbox_search_deinit()' finishes the search. If it returns -1, some error occurred and some search results might not have been returned. Example ------- Iterating through all messages in a mailbox goes like: ---%<------------------------------------------------------------------------- /* build search query */ search_args = mail_search_build_init(); mail_search_build_add_all(search_args); search_ctx = mailbox_search_init(trans, search_args, NULL); /* search context keeps args referenced */ mail_search_args_unref(&search_args); mail = mail_alloc(trans, 0, NULL); while (mailbox_search_next(ctx, mail)) { printf("matched uid %u\n", mail->uid); } mail_free(&mail); if (mailbox_search_deinit(&search_ctx) < 0) i_error("search failed"); ---%<------------------------------------------------------------------------- Saving search results --------------------- Search results can be saved for future use by calling 'mailbox_search_result_save()' just after initializing the search. The results as returned as UIDs with 'mailbox_search_result_get()' and may contain UIDs that are already expunged. Once you're done with the saved result, free it with 'mailbox_search_result_free()'. The search result can also be automatically updated whenever mailbox is synced if 'MAILBOX_SEARCH_RESULT_FLAG_UPDATE' is set. The update is optimized, so Dovecot doesn't do a full re-search, but matches only new and changed messages. If 'MAILBOX_SEARCH_RESULT_FLAG_QUEUE_SYNC' is also set, search result additions and removals are also tracked and can be retrieved with 'mailbox_search_result_sync()', i.e. with this you can implement "what changed in search results since last time I checked". (This file was created from the wiki on 2018-02-28 04:42)