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

mailnews/base/search/public/nsIMsgTraitService.idl

@@ -0,0 +1,174 @@
+/* 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/. */
+
+ /**
+  * This interface provides management of traits that are used to categorize
+  * messages. A trait is some characteristic of a message, such as being "junk"
+  * or "personal", that may be discoverable by analysis of the message.
+  *
+  * Traits are described by a universal identifier "id" as a string, as well
+  * as a local integer identifer "index". One purpose of this service is to
+  * provide the mapping between those forms.
+  *
+  * Recommended (but not required) format for id:
+  * "extensionName@example.org#traitName"
+  */
+
+#include "nsISupports.idl"
+
+[scriptable, uuid(2CB15FB0-A912-40d3-8882-F2765C75655F)]
+interface nsIMsgTraitService : nsISupports
+{
+  /**
+   *  the highest ever index for a registered trait. The first trait is 1,
+   *  == 0 means no traits are defined
+   */
+  readonly attribute long lastIndex;
+
+  /**
+   * Register a trait. May be called multiple times, but subsequent
+   * calls do not register the trait
+   *
+   * @param id   the trait universal identifier
+   *
+   * @return     the internal index for the registered trait if newly
+   *             registered, else 0
+   */
+  unsigned long registerTrait(in ACString id);
+
+  /**
+   * Unregister a trait.
+   *
+   * @param id   the trait universal identifier
+   */
+  void unRegisterTrait(in ACString id);
+
+  /**
+   * is a trait registered?
+   *
+   * @param id   the trait universal identifier
+   *
+   * @return     true if registered
+   */
+  boolean isRegistered(in ACString id);
+
+  /**
+   * set the trait name, which is an optional short description of the trait
+   *
+   * @param id     the trait universal identifier
+   * @param name   description of the trait.
+   */
+  void setName(in ACString id, in ACString name);
+
+  /**
+   * get the trait name, which is an optional short description of the trait
+   *
+   * @param id   the trait universal identifier
+   *
+   * @return     description of the trait
+   */
+  ACString getName(in ACString id);
+
+  /**
+   * get the internal index number for the trait.
+   *
+   * @param id   the trait universal identifier
+   *
+   * @return     internal index number for the trait
+   */
+  unsigned long getIndex(in ACString id);
+
+  /**
+   * get the trait universal identifier for an internal trait index
+   *
+   * @param index   the internal identifier for the trait
+   *
+   * @return        trait universal identifier
+   */
+  ACString getId(in unsigned long index);
+
+  /**
+   * enable the trait for analysis. Each enabled trait will be analyzed by
+   * the bayesian code. The enabled trait is the "pro" trait that represents
+   * messages matching the trait. Each enabled trait also needs a corresponding
+   * anti trait defined, which represents messages that do not match the trait.
+   * The anti trait does not need to be enabled
+   *
+   * @param id        the trait universal identifier
+   * @param enabled   should this trait be processed by the bayesian analyzer?
+   */
+  void setEnabled(in ACString id, in boolean enabled);
+
+  /**
+   * Should this trait be processed by the bayes analyzer?
+   *
+   * @param id   the trait universal identifier
+   *
+   * @return     true if this is a "pro" trait to process
+   */
+  boolean getEnabled(in ACString id);
+
+  /**
+   * set the anti trait, which indicates messages that have been marked as
+   * NOT matching a particular trait.
+   *
+   * @param id      the trait universal identifier
+   * @param antiId  trait id for messages marked as not matching the trait
+   */
+  void setAntiId(in ACString id, in ACString antiId);
+
+  /**
+   * get the id of traits that do not match a particular trait
+   *
+   * @param id   the trait universal identifier for a "pro" trait
+   *
+   * @return     universal trait identifier for an "anti" trait that does not
+   *             match the "pro" trait messages
+   */
+  ACString getAntiId(in ACString id);
+
+  /**
+   * get an array of traits to be analyzed by the bayesian code. This is
+   * a pair of traits: a "pro" trait of messages that match the trait (and is
+   * set enabled) and an "anti" trait of messages that do not match the trait.
+   *
+   * @param count        length of proIndices and antiIndices arrays
+   * @param proIndices   trait internal index for "pro" trait to analyze
+   * @param antiIndices  trait internal index for corresponding "anti" traits
+   */
+  void getEnabledIndices(out unsigned long count,
+                         [array, size_is(count)] out unsigned long proIndices,
+                         [array, size_is(count)] out unsigned long antiIndices);
+
+  /**
+   * Add a trait as an alias of another trait. An alias is a trait whose
+   * counts will be combined with the aliased trait. This allows multiple sets
+   * of corpus data to be used to provide information on a single message
+   * characteristic, while allowing each individual set of corpus data to
+   * retain its own identity.
+   *
+   * @param aTraitIndex  the internal identifier for the aliased trait
+   * @param aTraitAlias  the internal identifier for the alias to add
+   */
+  void addAlias(in unsigned long aTraitIndex, in unsigned long aTraitAlias);
+
+  /**
+   * Removes a trait as an alias of another trait.
+   *
+   * @param aTraitIndex  the internal identifier for the aliased trait
+   * @param aTraitAlias  the internal identifier for the alias to remove
+   */
+  void removeAlias(in unsigned long aTraitIndex, in unsigned long aTraitAlias);
+
+  /**
+   * Get an array of trait aliases for a trait index, if any
+   *
+   * @param aTraitIndex  the internal identifier for the aliased trait
+   * @param aLength      length of array of aliases
+   * @param aAliases     array of internal identifiers for aliases
+   */
+  void getAliases(in unsigned long aTraitIndex, out unsigned long aLength,
+                  [retval, array, size_is(aLength)] out unsigned long aAliases);
+
+};