path: root/comm/mailnews/search/public/nsIMsgFilterPlugin.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * 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 "MailNewsTypes2.idl"

interface nsIMsgWindow;
interface nsIFile;

/**
 * This interface is still very much under development, and is not yet stable.
 */

[scriptable, uuid(e2e56690-a676-11d6-80c9-00008646b737)]
interface nsIMsgFilterPlugin : nsISupports
{
    /**
     * Do any necessary cleanup: flush and close any open files, etc.
     */
    void shutdown();

    /**
     * Some protocols (ie IMAP) can, as an optimization, avoid
     * downloading all message header lines.  If your plugin doesn't need
     * any more than the minimal set, it can return false for this attribute.
     */
    readonly attribute boolean shouldDownloadAllHeaders;

};

/*
 * These interfaces typically implement a Bayesian classifier of messages.
 *
 * Two sets of interfaces may be used: the older junk-only interfaces, and
 * the newer trait-oriented interfaces that treat junk classification as
 * one of a set of classifications to accomplish.
 */

[scriptable, uuid(b15a0f9c-df07-4af0-9ba8-80dca68ac35d)]
interface nsIJunkMailClassificationListener : nsISupports
{
  /**
   * Inform a listener of a message's classification as junk. At the end
   * of a batch of classifications, signify end of batch by calling with
   * null aMsgURI (other parameters are don't care)
   *
   * @param aMsgURI          URI of the message that was classified.
   * @param aClassification  classification of message as UNCLASSIFIED, GOOD,
   *                         or JUNK.
   * @param aJunkPercent     indicator of degree of uncertainty, with 100 being
   *                         probably junk, and 0 probably good
   */
  void onMessageClassified(in AUTF8String aMsgURI,
                           in nsMsgJunkStatus aClassification,
                           in uint32_t aJunkPercent);
};

[scriptable, uuid(AF247D07-72F0-482d-9EAB-5A786407AA4C)]
interface nsIMsgTraitClassificationListener : nsISupports
{
  /**
   * Inform a listener of a message's match to traits. The list
   * of traits being matched is in aTraits. Corresponding
   * indicator of match (percent) is in aPercents. At the end
   * of a batch of classifications, signify end of batch by calling with
   * null aMsgURI (other parameters are don't care)
   *
   * @param aMsgURI      URI of the message that was classified
   * @param aTraits      array of matched trait ids
   * @param aPercents    array of percent match (0 is unmatched, 100 is fully
   *                     matched) of the trait with the corresponding array
   *                     index in aTraits
   */
  void onMessageTraitsClassified(in AUTF8String aMsgURI,
    in Array<unsigned long> aTraits,
    in Array<unsigned long> aPercents);
};

[scriptable, uuid(12667532-88D1-44a7-AD48-F73719BE5C92)]
interface nsIMsgTraitDetailListener : nsISupports
{
  /**
   * Inform a listener of details of a message's match to traits.
   * This returns the tokens that were used in the calculation,
   * the calculated percent probability that each token matches the trait,
   * and a running estimate (starting with the strongest tokens) of the
   * combined total probability that a message matches the trait, when
   * only tokens stronger than the current token are used.
   *
   * @param aMsgURI         URI of the message that was classified
   * @param aProTrait       trait id of pro trait for the calculation
   * @param tokenStrings    the string for a particular token
   * @param tokenPercents   calculated probability that a message with that token
   *                        matches the trait
   * @param runningPercents calculated probability that the message matches the
   *                        trait, accounting for this token and all stronger tokens.
   */
    void onMessageTraitDetails(in AUTF8String aMsgUri,
                               in unsigned long aProTrait,
                               in Array<AString> tokenStrings,
                               in Array<unsigned long> tokenPercents,
                               in Array<unsigned long> runningPercents);
};

[scriptable, uuid(8EA5BBCA-F735-4d43-8541-D203D8E2FF2F)]
interface nsIJunkMailPlugin : nsIMsgFilterPlugin
{
    /**
     * Message classifications.
     */
    const nsMsgJunkStatus UNCLASSIFIED = 0;
    const nsMsgJunkStatus GOOD = 1;
    const nsMsgJunkStatus JUNK = 2;

    /**
     * Message junk score constants. Junkscore can only be one of these two
     * values (or not set).
     */
    const nsMsgJunkScore IS_SPAM_SCORE = 100; // junk
    const nsMsgJunkScore IS_HAM_SCORE = 0; // not junk

    /**
     * Trait ids for junk analysis. These values are fixed to ensure
     * backwards compatibility with existing junk-oriented classification
     * code.
     */

    const unsigned long GOOD_TRAIT = 1; // good
    const unsigned long JUNK_TRAIT = 2; // junk

    /**
     * Given a message URI, determine what its current classification is
     * according to the current training set.
     */
    void classifyMessage(in AUTF8String aMsgURI, in nsIMsgWindow aMsgWindow,
                         in nsIJunkMailClassificationListener aListener);

    void classifyMessages(in Array<AUTF8String> aMsgURIs,
                          in nsIMsgWindow aMsgWindow,
                          in nsIJunkMailClassificationListener aListener);

    /**
     * Given a message URI, evaluate its relative match to a list of
     * traits according to the current training set.
     *
     * @param aMsgURI          URI of the message to be evaluated
     * @param aProTraits       array of trait ids for trained messages that
     *                         match the tested trait (for example,
     *                         JUNK_TRAIT if testing for junk)
     * @param aAntiTraits      array of trait ids for trained messages that
     *                         do not match the tested trait (for example,
     *                         GOOD_TRAIT if testing for junk)
     * @param aTraitListener   trait-oriented callback listener (may be null)
     * @param aMsgWindow       current message window (may be null)
     * @param aJunkListener    junk-oriented callback listener (may be null)
     */

    void classifyTraitsInMessage(
           in AUTF8String aMsgURI,
           in Array<unsigned long> aProTraits,
           in Array<unsigned long> aAntiTraits,
           in nsIMsgTraitClassificationListener aTraitListener,
           [optional] in nsIMsgWindow aMsgWindow,
           [optional] in nsIJunkMailClassificationListener aJunkListener);

    /**
     * Given an array of message URIs, evaluate their relative match to a
     * list of traits according to the current training set.
     *
     * @param aMsgURIs         array of URIs of the messages to be evaluated
     * @param aProTraits       array of trait ids for trained messages that
     *                         match the tested trait (for example,
     *                         JUNK_TRAIT if testing for junk)
     * @param aAntiTraits      array of trait ids for trained messages that
     *                         do not match the tested trait (for example,
     *                         GOOD_TRAIT if testing for junk)
     * @param aTraitListener   trait-oriented callback listener (may be null)
     * @param aMsgWindow       current message window (may be null)
     * @param aJunkListener    junk-oriented callback listener (may be null)
     */

    void classifyTraitsInMessages(
           in Array<AUTF8String> aMsgURIs,
           in Array<unsigned long> aProTraits,
           in Array<unsigned long> aAntiTraits,
           in nsIMsgTraitClassificationListener aTraitListener,
           [optional] in nsIMsgWindow aMsgWindow,
           [optional] in nsIJunkMailClassificationListener aJunkListener);

    /**
     * Called when a user forces the classification of a message. Should
     * cause the training set to be updated appropriately.
     *
     * @arg aMsgURI                     URI of the message to be classified
     * @arg aOldUserClassification      Was it previous manually classified
     *                                  by the user?  If so, how?
     * @arg aNewClassification          New manual classification.
     * @arg aListener                   Callback (may be null)
     */
    void setMessageClassification(
        in AUTF8String aMsgURI, in nsMsgJunkStatus aOldUserClassification,
        in nsMsgJunkStatus aNewClassification,
        in nsIMsgWindow aMsgWindow,
        in nsIJunkMailClassificationListener aListener);

    /**
     * Called when a user forces a change in the classification of a message.
     * Should cause the training set to be updated appropriately.
     *
     * @param aMsgURI           URI of the message to be classified
     * @param aOldTraits        array of trait IDs of the old
     *                          message classification(s), if any
     * @param aNewTraits        array of trait IDs of the new
     *                          message classification(s), if any
     * @param aTraitListener    trait-oriented listener (may be null)
     * @param aMsgWindow        current message window (may be null)
     * @param aJunkListener     junk-oriented listener (may be null)
     */
    void setMsgTraitClassification(
        in AUTF8String aMsgURI,
        in Array<unsigned long> aOldTraits,
        in Array<unsigned long> aNewTraits,
        [optional] in nsIMsgTraitClassificationListener aTraitListener,
        [optional] in nsIMsgWindow aMsgWindow,
        [optional] in nsIJunkMailClassificationListener aJunkListener);

    readonly attribute boolean userHasClassified;

    /** Removes the training file and clears out any in memory training tokens.
        User must retrain after doing this.
    **/
    void resetTrainingData();

    /**
     * Given a message URI, return a list of tokens and their contribution to
     * the analysis of a message's match to a trait according to the
     * current training set.
     *
     * @param aMsgURI          URI of the message to be evaluated
     * @param aProTrait        trait id for trained messages that match the
     *                         tested trait (for example, JUNK_TRAIT if testing
     *                         for junk)
     * @param aAntiTrait       trait id for trained messages that do not match
     *                         the tested trait (for example, GOOD_TRAIT
     *                         if testing for junk)
     * @param aListener        callback listener for results
     * @param aMsgWindow       current message window (may be null)
     */
    void detailMessage(
        in AUTF8String aMsgURI,
        in unsigned long aProTrait,
        in unsigned long aAntiTrait,
        in nsIMsgTraitDetailListener aListener,
        [optional] in nsIMsgWindow aMsgWindow);

};

/**
 * The nsIMsgCorpus interface manages a corpus of mail data used for
 * statistical analysis of messages.
 */
[scriptable, uuid(70BAD26F-DFD4-41bd-8FAB-4C09B9C1E845)]
interface nsIMsgCorpus : nsISupports
{
  /**
   * Clear the corpus data for a trait id.
   *
   * @param aTrait       trait id
   */
   void clearTrait(in unsigned long aTrait);

  /**
   * Update corpus data from a file.
   * Uses the parallel arrays aFromTraits and aToTraits. These arrays allow
   * conversion of the trait id stored in the file (which may be originated
   * externally) to the trait id used in the local corpus (which is defined
   * locally using nsIMsgTraitService, and mapped by that interface to a
   * globally unique trait id string).
   *
   * @param aFile       the file with the data, in the format:
   *
   *                    Format of the trait file for version 1:
   *                    [0xFCA93601]  (the 01 is the version)
   *                    for each trait to write:
   *                    [id of trait to write] (0 means end of list)
   *                    [number of messages per trait]
   *                    for each token with non-zero count
   *                    [count]
   *                    [length of word]word
   *
   * @param aIsAdd      should the data be added, or removed? True if
   *                    adding, false if removing.
   *
   * @param aFromTraits array of trait ids used in aFile. If aFile contains
   *                    trait ids that are not in this array, they are not
   *                    remapped, but assumed to be local trait ids.
   *
   * @param aToTraits   array of trait ids, corresponding to elements of
   *                    aFromTraits, that represent the local trait ids to
   *                    be used in storing data from aFile into the local corpus.
   */
  void updateData(in nsIFile aFile, in boolean aIsAdd,
                  [optional] in Array<unsigned long> aFromTraits,
                  [optional] in Array<unsigned long> aToTraits);

  /**
   * Get the corpus count for a token as a string.
   *
   * @param aWord    string of characters representing the token
   * @param aTrait   trait id
   *
   * @return         count of that token in the corpus
   *
   */
  unsigned long getTokenCount(in AUTF8String aWord, in unsigned long aTrait);

  /**
   * Gives information on token and message count information in the
   * training data corpus.
   *
   * @param aTrait           trait id (may be null)
   * @param aMessageCount    count of messages that have been trained with aTrait
   *
   * @return                 token count for all traits
   */

  unsigned long corpusCounts(in unsigned long aTrait, out unsigned long aMessageCount);
};