nsIMsgSearchSession

The nsIMsgSearchSession interface allows you to create and manipulate search sessions within Thunderbird.

To create an instance, use:

 var searchSession = Components.classes["@mozilla.org/messenger/searchSession;1"]
                               .createInstance(Components.interfaces.nsIMsgSearchSession);

To use the instance append search terms, set the scope, and then call search().

searchSession.addScopeTerm(Components.interfaces.nsMsgSearchScope.offlineMail, aFolder);
var searchTerm = searchSession.createTerm();
var value = searchTerm.value;
value.str = aValue;
searchTerm.value = value;

searchTerm.op = searchSession.BooleanOR;
searchTerm.booleanAnd = false;

searchSession.appendTerm(searchTerm);
searchSession.search(null);

Inherits from: nsISupports

Method overview

void addSearchTerm(in nsMsgSearchAttribValue attrib, in nsMsgSearchOpValue op, in nsIMsgSearchValue value, in boolean BooleanAND, in string arbitraryHeader);
nsIMsgSearchTerm createTerm();
void appendTerm(in nsIMsgSearchTerm term);
void registerListener(in nsIMsgSearchNotify listener);
void unregisterListener(in nsIMsgSearchNotify listener);
void getNthSearchTerm(in long whichTerm, in nsMsgSearchAttribValue attrib, in nsMsgSearchOpValue op, in nsIMsgSearchValue value);
long countSearchScopes();
void getNthSearchScope(in long which,out nsMsgSearchScopeValue scopeId, out nsIMsgFolder folder);
void addScopeTerm(in nsMsgSearchScopeValue scope, in nsIMsgFolder folder);
void addDirectoryScopeTerm(in nsMsgSearchScopeValue scope);
void clearScopes();
[noscript] boolean ScopeUsesCustomHeaders(in nsMsgSearchScopeValue scope, in voidPtr selection, in boolean forFilters);
boolean IsStringAttribute(in nsMsgSearchAttribValue attrib);
void AddAllScopes(in nsMsgSearchScopeValue attrib);
void search(in nsIMsgWindow aWindow);
void interruptSearch();
void pauseSearch();
void resumeSearch();
[noscript] nsMsgSearchType SetSearchParam(in nsMsgSearchType type, in voidPtr param);
[noscript] void AddResultElement(in nsMsgResultElement element);
boolean MatchHdr(in nsIMsgDBHdr aMsgHdr, in nsIMsgDatabase aDatabase);
void addSearchHit(in nsIMsgDBHdr header, in nsIMsgFolder folder);

Attributes

Attribute Type Description
searchTerms nsISupportsArray Readonly:
numSearchTerms unsigned long Readonly:
runningAdapter nsIMsgSearchAdapter Readonly:
searchParam voidPtr Not scriptable and readonly:
searchType nsMsgSearchType Readonly:
numResults long Readonly:
window nsIMsgWindow

Constants

Name Value Description
BooleanOR 0
BooleanAND 1

Methods

addSearchTerm()

 void addSearchTerm(in nsMsgSearchAttribValue attrib,
                    in nsMsgSearchOpValue op,
                    in nsIMsgSearchValue value,
                    in boolean BooleanAND,
                    in string arbitraryHeader);
Parameters
attrib
Attribute for this term.
op
Operator e.g. opContains
value
Value e.g. "Dogbert"
BooleanAND
Set to true if associated boolean operator is AND.
arbitraryHeader
User defined arbitrary header. Ignored unless attrib = attribOtherHeader.

createTerm()

 nsIMsgSearchTerm createTerm();

appendTerm()

 void appendTerm(in nsIMsgSearchTerm term);
Parameters
term

registerListener()

Adds a listener to the search session.

 void registerListener(in nsIMsgSearchNotify listener);
Parameters
listener

unregisterListener()

Removes a listener from the search session.

 void unregisterListener (in nsIMsgSearchNotify listener);
Parameters
listener

getNthSearchTerm()

 void getNthSearchTerm(in long whichTerm,
                       in nsMsgSearchAttribValue attrib,
                       in nsMsgSearchOpValue op,

in nsIMsgSearchValue value);

Parameters
whichTerm
attrib
op
value
Note: This parameter should be an out.

countSearchScopes()

 long countSearchScopes();

getNthSearchScope()

 void getNthSearchScope(in long which,
                        out nsMsgSearchScopeValue scopeId,
                        out nsIMsgFolder folder);
Parameters
which
Return values
scopeId
folder

addScopeTerm()

Add a scope (e.g. a mail folder) to the search.

 void addScopeTerm(in nsMsgSearchScopeValue scope,
                   in nsIMsgFolder folder);
Parameters
scope
folder

addDirectoryScopeTerm()

 void addDirectoryScopeTerm(in nsMsgSearchScopeValue scope);
Parameters
scope

clearScopes()

 void clearScopes();

ScopeUsesCustomHeaders()

Call this function everytime the scope changes! It informs the FE if the current scope support custom header use. FEs should not display the custom header dialog if custom headers are not supported.

 [noscript] boolean ScopeUsesCustomHeaders(in nsMsgSearchScopeValue scope,
                                           in voidPtr selection,

in boolean forFilters);

Parameters
scope
selection
Could be a folder or server based on scope
forFilters

IsStringAttribute()

Use this to determine if your attribute is a string attribute.

 boolean IsStringAttribute(in nsMsgSearchAttribValue attrib);
Parameters
attrib

AddAllScopes()

Add all scopes of a given type to the search.

 void AddAllScopes(in nsMsgSearchScopeValue attrib);
Parameters
attrib

search()

 void search(in nsIMsgWindow aWindow);
Parameters
aWindow

interruptSearch()

 void interruptSearch();

pauseSearch()

These two methods are used when the search session is using a timer to do local search, and the search adapter needs to run a url (e.g., to reparse a local folder) and wants to pause the timer while running the url. This will fail if the current adapter is not using a timer.

 void pauseSearch();

resumeSearch()

 void resumeSearch();

SetSearchParam()

 [noscript] nsMsgSearchType SetSearchParam(in nsMsgSearchType type,
                                           in voidPtr param);
Parameters
type
param

AddResultElement()

 [noscript] void AddResultElement(in nsMsgResultElement element);
Parameters
element

MatchHdr()

 boolean MatchHdr(in nsIMsgDBHdr aMsgHdr,
                  in nsIMsgDatabase aDatabase);
Parameters
aMsgHdr
aDatabase

addSearchHit()

 void addSearchHit(in nsIMsgDBHdr header,
                   in nsIMsgFolder folder);
Parameters
header
folder