summaryrefslogtreecommitdiffstats
path: root/mailnews/base/search/public/nsIMsgTraitService.idl
blob: 78d9704e38002f74349ecf2bcc909fb18df74f4c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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);

};