/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1999
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

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

interface nsIMsgSearchAdapter;
interface nsIMsgSearchTerm;
interface nsIMsgSearchNotify;
interface nsIMsgHdr;
interface nsIMsgDatabase;

//////////////////////////////////////////////////////////////////////////////
// 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;
};
