Dactyloidae/mailnews/base/search/public/nsIMsgSearchSession.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIMsgSearchValue.idl"

interface nsIMsgSearchAdapter;
interface nsIMsgSearchTerm;
interface nsIMsgSearchNotify;
interface nsIMsgHdr;
interface nsIMsgDatabase;
// Disable deprecation warnings generated by nsISupportsArray and associated
// classes.
%{C++
#if defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
#elif defined(_MSC_VER)
#pragma warning (disable : 4996)
#endif
%}
interface nsISupportsArray;
interface nsIMsgWindow;

//////////////////////////////////////////////////////////////////////////////
// The Msg Search Session is an interface designed to make constructing
// searches easier. Clients typically build up search terms, and then run
// the search
//////////////////////////////////////////////////////////////////////////////

[scriptable, uuid(1ed69bbf-7983-4602-9a9b-2f2263a78878)]
interface nsIMsgSearchSession :  nsISupports {

/**
 * add a search term to the search session
 *
 * @param   attrib        search attribute (e.g. nsMsgSearchAttrib::Subject)
 * @param   op            search operator (e.g. nsMsgSearchOp::Contains)
 * @param   value         search value (e.g. "Dogbert", see nsIMsgSearchValue)
 * @param   BooleanAND    set to true if associated boolean operator is AND
 * @param   customString  if attrib > nsMsgSearchAttrib::OtherHeader,
 *                            a user defined arbitrary header
 *                        if attrib == nsMsgSearchAttrib::Custom, the custom id
 *                        otherwise ignored
 */
  void addSearchTerm(in nsMsgSearchAttribValue attrib,
                     in nsMsgSearchOpValue op,
                     in nsIMsgSearchValue value,
                     in boolean BooleanAND,
                     in string customString);

  readonly attribute nsISupportsArray searchTerms;

  nsIMsgSearchTerm createTerm ();
  void appendTerm(in nsIMsgSearchTerm term);

  /**
   * @name Search notification flags
   * These flags determine which notifications will be sent.
   * @{
   */
  /// search started notification
  const long onNewSearch = 0x1;

  /// search finished notification
  const long onSearchDone = 0x2;

  /// search hit notification
  const long onSearchHit = 0x4;

  const long allNotifications = 0x7;
  /** @} */

  /**
   * Add a listener to get notified of search starts, stops, and hits.
   *
   * @param aListener listener
   * @param aNotifyFlags which notifications to send. Defaults to all
   */
  void registerListener (in nsIMsgSearchNotify aListener,
                         [optional] in long aNotifyFlags);
  void unregisterListener (in nsIMsgSearchNotify listener);

  readonly attribute unsigned long numSearchTerms;

  readonly attribute nsIMsgSearchAdapter runningAdapter;

  void getNthSearchTerm(in long whichTerm,
                        in nsMsgSearchAttribValue attrib,
                        in nsMsgSearchOpValue op,
                        in nsIMsgSearchValue value); // wrong, should be out

  long countSearchScopes();

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

  /* add a scope (e.g. a mail folder) to the search */
  void addScopeTerm(in nsMsgSearchScopeValue scope,
                    in nsIMsgFolder folder);

  void addDirectoryScopeTerm(in nsMsgSearchScopeValue scope);

  void clearScopes();

  /* 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,
                                 /* could be a folder or server based on scope */
                                 in voidPtr selection,
                                 in boolean forFilters);

  /* use this to determine if your attribute is a string attrib */
  boolean IsStringAttribute(in nsMsgSearchAttribValue attrib);

  /* add all scopes of a given type to the search */
  void AddAllScopes(in nsMsgSearchScopeValue attrib);

  void search(in nsIMsgWindow aWindow);
  void interruptSearch();

  // 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();
  void resumeSearch();

  [noscript] readonly attribute voidPtr searchParam;
  readonly attribute nsMsgSearchType searchType;

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

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

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

  readonly attribute long numResults;
  attribute nsIMsgWindow window;

  /* these longs are all actually of type nsMsgSearchBooleanOp */
  const long BooleanOR=0;
  const long BooleanAND=1;
};