1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 1998
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Seth Spitzer <sspitzer@netscape.com>
24 * Mark Banner <mark@standard8.demon.co.uk>
25 *
26 * Alternatively, the contents of this file may be used under the terms of
27 * either of the GNU General Public License Version 2 or later (the "GPL"),
28 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
29 * in which case the provisions of the GPL or the LGPL are applicable instead
30 * of those above. If you wish to allow use of your version of this file only
31 * under the terms of either the GPL or the LGPL, and not to allow others to
32 * use your version of this file under the terms of the MPL, indicate your
33 * decision by deleting the provisions above and replace them with the notice
34 * and other provisions required by the GPL or the LGPL. If you do not delete
35 * the provisions above, a recipient may use your version of this file under
36 * the terms of any one of the MPL, the GPL or the LGPL.
37 *
38 * ***** END LICENSE BLOCK ***** */
39
40 #include "nsISupports.idl"
41 #include "nsIAbCard.idl"
42
43 interface nsISimpleEnumerator;
44 interface nsIArray;
45 interface nsISupportsArray;
46
47 %{C++
48 /* RDF root for all types of address books */
49 /* use this to get all directories, create new directory*/
50 #define kAllDirectoryRoot "moz-abdirectory://"
51
52 #define kPersonalAddressbook "abook.mab"
53 #define kPersonalAddressbookUri "moz-abmdbdirectory://abook.mab"
54 #define kCollectedAddressbook "history.mab"
55 #define kCollectedAddressbookUri "moz-abmdbdirectory://history.mab"
56
57 #define kABFileName_PreviousSuffix ".na2" /* final v2 address book format */
58 #define kABFileName_PreviousSuffixLen 4
59 #define kABFileName_CurrentSuffix ".mab" /* v3 address book extension */
60 %}
61
62 [scriptable, uuid(55acf262-81e3-4ffe-bfd1-8b328adb49b4)]
63 interface nsIAbDirectory : nsISupports {
64
65 /**
66 * The chrome URI to use for bringing up a dialog to edit this directory.
67 * When opening the dialog, use a JS argument of
68 * {selectedDirectory: thisdir} where thisdir is this directory that you just
69 * got the chrome URI from.
70 */
71 readonly attribute ACString propertiesChromeURI;
72
73 // Types of operation
74 // Perform linear reading of directory card
75 // content
76 const long opRead = 0x1;
77 // Perform modification and deletion on a
78 // directories content
79 const long opWrite = 0x2;
80 // Perform searching on a directory card
81 // content via the uri format:
82 // scheme://path?query
83 const long opSearch = 0x4;
84
85 // The supported operations
86 readonly attribute long operations;
87
88 /**
89 * The description of the directory. If this directory is not a mailing list,
90 * then setting this attribute will send round a "DirName" update via
91 * nsIAddrBookSession.
92 */
93 attribute AString dirName;
94
95 // XXX This should really be replaced by a QI or something better
96 readonly attribute long dirType;
97
98 // eliminated a bit more.
99
100 // The filename for address books within this directory.
101 readonly attribute ACString fileName;
102
103 // The RDF resource URI of the address book
104 readonly attribute ACString URI;
105
106 // The position of the directory on the display.
107 readonly attribute long position;
108
109 // will be used for LDAP replication
110 attribute unsigned long lastModifiedDate;
111
112 // Defines whether this directory is a mail
113 // list or not
114 attribute PRBool isMailList;
115
116 // Get the children directories
117 readonly attribute nsISimpleEnumerator childNodes;
118
119 /**
120 * Get the cards associated with the directory. This will return the cards
121 * associated with the mailing lists too.
122 */
123 readonly attribute nsISimpleEnumerator childCards;
124
125 // Deletes either a mailing list or a top
126 // level directory, which also updates the
127 // preferences
128 void deleteDirectory(in nsIAbDirectory directory);
129
130 // Check if directory contains card
131 // If the implementation is asynchronous the card
132 // may not yet have arrived. If it is in the process
133 // of obtaining cards the method will throw an
134 // NS_ERROR_NOT_AVAILABLE exception if the card
135 // cannot be found.
136 boolean hasCard(in nsIAbCard cards);
137
138 // Check if directory contains directory
139 boolean hasDirectory(in nsIAbDirectory dir);
140
141 /**
142 * Adds a card to the database. card may be an abstract card.
143 *
144 * @return "Real" card (eg nsIAbMDBCard) that can be used for some
145 * extra functions.
146 */
147 nsIAbCard addCard(in nsIAbCard card);
148
149 /**
150 * Modifies a card in the database to match that supplied.
151 */
152 void modifyCard(in nsIAbCard modifiedCard);
153
154 /**
155 * Deletes the array of cards from the database.
156 *
157 * @param aCards The cards to delete from the database.
158 */
159 void deleteCards(in nsIArray aCards);
160
161 void dropCard(in nsIAbCard card, in boolean needToCopyCard);
162
163 /**
164 * directory is local (example, mork based) or remote (example, LDAP)
165 */
166 readonly attribute boolean isRemote;
167
168 /**
169 * directory is secure (as in LDAP over SSL)
170 */
171 readonly attribute boolean isSecure;
172
173 /**
174 * directory should be searched when doing local autocomplete
175 */
176 readonly attribute boolean searchDuringLocalAutocomplete;
177
178 /**
179 * Does this directory support mailing lists? Note that in the case
180 * this directory is a mailing list and nested mailing lists are not
181 * supported, this will return false rather than true which the parent
182 * directory might.
183 */
184 readonly attribute boolean supportsMailingLists;
185
186 // XXX todo
187 // fix this, ugh
188 // This attribute servers two purposes
189 // depending if the directory is a mail list.
190 // If not mail list directories are stored here
191 // If so mail list card entries are stored here
192 attribute nsISupportsArray addressLists;
193
194 // Specific to a directory which stores mail lists
195
196 /**
197 * Creates a new mailing list in the directory. Currently only supported
198 * for top-level directories.
199 *
200 * @param list The new mailing list to add.
201 */
202 void addMailList(in nsIAbDirectory list);
203
204 /**
205 * Nick Name of the mailing list. This attribute is only really used when
206 * the nsIAbDirectory represents a mailing list.
207 */
208 attribute AString listNickName;
209
210 /**
211 * Description of the mailing list. This attribute is only really used when
212 * the nsIAbDirectory represents a mailing list.
213 */
214 attribute AString description;
215
216 /**
217 * Edits an existing mailing list (specified as listCard) into its parent
218 * directory. You should call this function on the resource with the same
219 * uri as the listCard.
220 *
221 * @param listCard A nsIAbCard version of the mailing list with the new
222 * values.
223 */
224 void editMailListToDatabase(in nsIAbCard listCard);
225
226 // Copies mail list properties from the srcList
227 void copyMailList(in nsIAbDirectory srcList);
228
229 /*
230 Only creates a top level address book
231 which is stored in the preferences
232
233 Need to change to factory based approach
234 to create new address books
235
236 This method should become redundant or
237 be only associated with card folders
238 */
239 ACString createNewDirectory(in AString aDirName, in ACString aURI,
240 in unsigned long aType);
241
242 /* create a directory by passing the display name and address book uri */
243 void createDirectoryByURI(in AString displayName, in ACString aURI);
244
245 /**
246 * The id of the directory used in prefs e.g. "ldap_2.servers.pab"
247 * Setting this will cause directoryPrefs to be updated.
248 */
249 attribute ACString dirPrefId;
250
251 /**
252 * @name getXXXValue
253 *
254 * Helper functions to get different types of pref, but return a default
255 * value if a pref value was not obtained.
256 *
257 * @param aName The name of the pref within the branch dirPrefId to
258 * get a value from.
259 *
260 * @param aDefaultValue The default value to return if getting the pref fails
261 * or the pref is not present.
262 *
263 * @return The value of the pref or the default value.
264 *
265 * @exception NS_ERROR_NOT_INITIALIZED if the pref branch couldn't
266 * be obtained (e.g. dirPrefId isn't set).
267 */
268 //@{
269 long getIntValue(in string aName, in long aDefaultValue);
270 boolean getBoolValue(in string aName, in boolean aDefaultValue);
271 ACString getStringValue(in string aName, in ACString aDefaultValue);
272 AUTF8String getLocalizedStringValue(in string aName, in AUTF8String aDefaultValue);
273 //@}
274
275 /**
276 * @name setXXXValue
277 *
278 * Helper functions to set different types of pref values.
279 *
280 * @param aName The name of the pref within the branch dirPrefId to
281 * get a value from.
282 *
283 * @param aValue The value to set the pref to.
284 *
285 * @exception NS_ERROR_NOT_INITIALIZED if the pref branch couldn't
286 * be obtained (e.g. dirPrefId isn't set).
287 */
288 //@{
289 void setIntValue(in string aName, in long aValue);
290 void setBoolValue(in string aName, in boolean aValue);
291 void setStringValue(in string aName, in ACString aValue);
292 //@}
293 };