Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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);
};