/* 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);

};