Mailnews filters consist of a set of search terms, and a set of filter actions. Filter execution is done by evaluating the search terms using the core mailnews/base/search code, and then applying the filter hits when the search terms match. For new incoming messages, the protocol specific object that handles new messages calls nsIMsgFilterList::ApplyFiltersToHdr and passes itself in as nsIMsgFilterHitNotify interface to handle filter hits. E.g., IMAP, POP3.
ApplyFiltersToHdr will in turn call the applyFilterHit method of the passed in nsIMsgFilterHitNotify interface ptr. The protocol specific code will then apply all of the actions of the filter to the current msg header. If one of the actions is a move, or a stop filter execution action, we move on to the next header; otherwise, we move on to the next filter.
In the case of POP3, filter execution is synchronous. For each new header, we evaluate the filter criteria and apply the actions synchronously, including moving a message to an other local folder, and advance to the next header. For IMAP, we tend to initiate the urls synchronously, but because we don't run two urls simultaneously on the same folder, the urls don't run until we've finished downloading headers. We also coalesce moves to the same destination folder, so that we can do them in one url/command to the server, and we playback those moves when the header download is done.
After the Fact Filters
These are one or more filters run on one or more folders *after* the headers have been downloaded. These filters are initiated in the filter editor, and implemented in nsMsgFilterService.cpp. This is implemented by doing a search using the filter criteria and applying the actions en masse on the resulting hits. The search is executed locally, not on the server, so that criteria like "in address book" still work.
How to add a filter action
- Add your new action to nsIMsgFilterAction
- Add code to file out the new action here
- Add new action to the rulesActionTable
- Add string for the new action to the filter editor dtd file
- Add new action to the filter editor js code
- Add new action to the xbl widget in the filter editor
- If your action has a parameter, add code to initialize the ui editing an existing filter here and to save to the filter here
- Add your action to filter.properties so it will show up in the filter log.
- Finally, add protocol-specific code to apply your filter action in the various ApplyFilterHit methods IMAP POP3 News and "after the fact"
Since SeaMonkey and Thunderbird share the filter code, you will also need to update the SeaMonkey .dtd and .property files.
I may have missed some places, but that's a start, anyway. It would be really nice if we had a mechanism for extensions to add their own filter actions. Most if not all of the above pieces of code would be involved in the extension mechanism.