Issue #1258 - Part 1: Import mailnews, ldap, and mork from comm-esr52.9.1

mailnews/base/search/public/nsIMsgSearchSession.idl

@@ -0,0 +1,147 @@
+/* -*- 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;
+};