summaryrefslogtreecommitdiffstats
path: root/mailnews/base/public/nsIMsgIncomingServer.idl
blob: a4349257dcd0a168c1c5952bc029e95a85e57467 (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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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 nsIMsgFolder;
interface nsIMsgFolderCache;
interface nsIMsgWindow;
interface nsIMsgProtocolInfo;
interface nsIMsgFilterList;
interface nsIMsgRetentionSettings;
interface nsIMsgDownloadSettings;
interface nsISpamSettings;
interface nsIMsgFilterPlugin;
interface nsIUrlListener;
interface nsIMsgDBHdr;
interface nsIFile;
interface nsIURI;
interface nsIMsgPluggableStore;

/*
 * Interface for incoming mail/news host
 * this is the base interface for all mail server types (imap, pop, nntp, etc)
 * often you will want to add extra interfaces that give you server-specific
 * attributes and methods.
 */
[scriptable, uuid(aa9a3389-9dac-41f1-9ec5-18287cfaa47c)]
interface nsIMsgIncomingServer : nsISupports {

  /**
   * internal pref key - guaranteed to be unique across all servers
   */
  attribute ACString key;

  /**
   * pretty name - should be "userid on hostname"
   * if the pref is not set
   */
  attribute AString prettyName;

  /**
  * helper function to construct the pretty name in a server type
  * specific way - e.g., mail for foo@test.com, news on news.mozilla.org
  */
  readonly attribute AString constructedPrettyName;

  /**
   * hostname of the server
   */
  attribute ACString hostName;
  
  /**
   * real hostname of the server (if server name is changed it's stored here)
   */
  attribute ACString realHostName;
  
  /* port of the server */
  attribute long port;

  /**
   * userid to log into the server
   */
  attribute ACString username;

  /**
   * real username of the server (if username is changed it's stored here)
   */
  attribute ACString realUsername;

  /**
   * protocol type, i.e. "pop3", "imap", "nntp", "none", etc
   * used to construct URLs
   */
  attribute ACString type;

  /**
   * The proper instance of nsIMsgProtocolInfo corresponding to this server type.
   */
  readonly attribute nsIMsgProtocolInfo protocolInfo;

  readonly attribute AString accountManagerChrome;

  /**
   * The schema for the local mail store, such as "mailbox", "imap", or "news"
   * used to construct URIs. The contractID for the nsIMsgMessageService
   * implementation that will manage access to messages associated with this
   * server is constructed using this type.
   */
  readonly attribute ACString localStoreType;

  /**
   * The schema for the nsIMsgDatabase implementation, such as "mailbox" or
   * "imap", that will be used to construct the database instance used by
   * message folders associated with this server.
   */
  readonly attribute ACString localDatabaseType;

  // Perform specific tasks (reset flags, remove files, etc) for account user/server name changes.
  void onUserOrHostNameChanged(in ACString oldName, in ACString newName,
                               in bool hostnameChanged);

  /* cleartext version of the password */
  attribute ACString password;

  /**
   * Attempts to get the password first from the password manager, if that
   * fails it will attempt to get it from the user if aMsgWindow is supplied.
   *
   * @param aPromptString  The text of the prompt if the user is prompted for
   *                       password.
   * @param aPromptTitle   The title of the prompt if the user is prompted.
   * @param aMsgWindow     A message window to associate the prompt with.
   * @return               The obtained password. Could be an empty password.
   *
   * @exception NS_ERROR_FAILURE  The password could not be obtained.
   *
   * @note NS_MSG_PASSWORD_PROMPT_CANCELLED is a success code that is returned
   *       if the prompt was presented to the user but the user cancelled the
   *       prompt.
   */
  ACString getPasswordWithUI(in AString aPromptString, in AString aPromptTitle,
                             in nsIMsgWindow aMsgWindow);

  /* forget the password in memory and in single signon database */
  void forgetPassword();

  /* forget the password in memory which is cached for the session */
  void forgetSessionPassword();

  /* should we download whole messages when biff goes off? */
  attribute boolean downloadOnBiff;

  /* should we biff the server? */
  attribute boolean doBiff;

  /* how often to biff */
  attribute long biffMinutes;

  /* current biff state */
  attribute unsigned long biffState;

  /* are we running a url as a result of biff going off? (different from user clicking get msg) */
  attribute boolean performingBiff; 

  /* the on-disk path to message storage for this server */
  attribute nsIFile localPath;

  /// message store to use for the folders under this server.
  readonly attribute nsIMsgPluggableStore msgStore;

  /* the RDF URI for the root mail folder */
  readonly attribute ACString serverURI;

  /* the root folder for this server, even if server is deferred */
  attribute nsIMsgFolder rootFolder;

  /* root folder for this account 
     - if account is deferred, root folder of deferred-to account */
  readonly attribute nsIMsgFolder rootMsgFolder;

  /* are we already getting new Messages on the current server..
     This is used to help us prevent multiple get new msg commands from
     going off at the same time. */
  attribute boolean serverBusy;

  /**
   * Is the server using a secure channel (SSL or STARTTLS).
   */
  readonly attribute boolean isSecure;

  /**
   * Authentication mechanism.
   *
   * @see nsMsgAuthMethod (in MailNewsTypes2.idl)
   * Same as "mail.server...authMethod" pref
   */
  attribute nsMsgAuthMethodValue authMethod;

  /**
   * Whether to SSL or STARTTLS or not
   *
   * @see nsMsgSocketType (in MailNewsTypes2.idl)
   * Same as "mail.server...socketType" pref
   */
  attribute nsMsgSocketTypeValue socketType;

  /* empty trash on exit */
  attribute boolean emptyTrashOnExit;

  /**
   * Get the server's list of filters.
   *
   * This SHOULD be the same filter list as the root folder's, if the server
   * supports per-folder filters. Furthermore, this list SHOULD be used for all
   * incoming messages.
   *
   * Since the returned nsIMsgFilterList is mutable, it is not necessary to call
   * setFilterList after the filters have been changed.
   *
   * @param aMsgWindow  @ref msgwindow "The standard message window"
   * @return            The list of filters.
   */
  nsIMsgFilterList getFilterList(in nsIMsgWindow aMsgWindow);

  /**
   * Set the server's list of filters.
   *
   * Note that this does not persist the filter list. To change the contents
   * of the existing filters, use getFilterList and mutate the values as
   * appopriate.
   *
   * @param aFilterList The new list of filters.
   */
  void setFilterList(in nsIMsgFilterList aFilterList);

  /**
   * Get user editable filter list. This does not have to be the same as
   * the filterlist above, typically depending on the users preferences.
   * The filters in this list are not processed, but only to be edited by
   * the user.
   * @see getFilterList
   *
   * @param aMsgWindow  @ref msgwindow "The standard message window"
   * @return            The list of filters.
   */
  nsIMsgFilterList getEditableFilterList(in nsIMsgWindow aMsgWindow);

  /**
   * Set user editable filter list.
   * This does not persist the filterlist, @see setFilterList
   * @see getEditableFilterList
   * @see setFilterList
   *
   * @param aFilterList The new list of filters.
   */
  void setEditableFilterList(in nsIMsgFilterList aFilterList);

  /* we use this to set the default local path.  we use this when migrating prefs */
  void setDefaultLocalPath(in nsIFile aDefaultLocalPath);

  /**
   * Verify that we can logon
   * 
   * @param  aUrlListener - gets called back with success or failure.
   * @param aMsgWindow         nsIMsgWindow to use for notification callbacks.
   * @return - the url that we run.
   */
  nsIURI verifyLogon(in nsIUrlListener aUrlListener, in nsIMsgWindow aMsgWindow);

  /* do a biff */
  void performBiff(in nsIMsgWindow aMsgWindow);
  
  /* get new messages */
  void getNewMessages(in nsIMsgFolder aFolder, in nsIMsgWindow aMsgWindow, 
                      in nsIUrlListener aUrlListener);
  /* this checks if a server needs a password to do biff */
  readonly attribute boolean serverRequiresPasswordForBiff;
  
  /* this gets called when the server is expanded in the folder pane */
  void performExpand(in nsIMsgWindow aMsgWindow);

  /* Write out all known folder data to panacea.dat */
  void writeToFolderCache(in nsIMsgFolderCache folderCache);

  /* close any server connections */
  void closeCachedConnections();
 
  /* ... */
  void shutdown();

  /**
   * Get or set the value as determined by the preference tree.
   *
   * These methods MUST NOT fail if the preference is not set, and therefore
   * they MUST have a default value. This default value is provided in practice
   * by use of a default preference tree. The standard format for the pref
   * branches are <tt>mail.server.<i>key</i>.</tt> for per-server preferences,
   * such that the preference is <tt>mail.server.<i>key</i>.<i>attr</i></tt>.
   *
   * The attributes are passed in as strings for ease of access by the C++
   * consumers of this method.
   *
   * @param attr  The value for which the preference should be accessed.
   * @param value The value of the preference to set.
   * @return      The value of the preference.
   * @{
   */
  boolean getBoolValue(in string attr);
  void setBoolValue(in string attr, in boolean value);

  ACString getCharValue(in string attr);
  void setCharValue(in string attr, in ACString value);

  AString getUnicharValue(in string attr);
  void setUnicharValue(in string attr, in AString value);
  
  long getIntValue(in string attr);
  void setIntValue(in string attr, in long value);
  /** @} */

  /**
   * Get or set the value as determined by the preference tree.
   *
   * These methods MUST NOT fail if the preference is not set, and therefore
   * they MUST have a default value. This default value is provided in practice
   * by use of a default preference tree. The standard format for the pref
   * branches are <tt>mail.server.<i>key</i>.</tt> for per-server preferences,
   * such that the preference is <tt>mail.server.<i>key</i>.<i>attr</i></tt>.
   *
   * The attributes are passed in as strings for ease of access by the C++
   * consumers of this method.
   *
   * There are two preference names on here for legacy reasons, where the first
   * is the name which will be using a (preferred) relative preference and the
   * second a deprecated absolute preference. Implementations that do not have
   * to worry about supporting legacy preferences can safely ignore this second
   * parameter. Callers must still provide a valid value, though.
   *
   * @param relpref The name of the relative file preference.
   * @param absref  The name of the absolute file preference.
   * @param aValue  The value of the preference to set.
   * @return        The value of the preference.
   * @{
   */
  nsIFile getFileValue(in string relpref, in string abspref);
  void setFileValue(in string relpref, in string abspref, in nsIFile aValue);
  /** @} */

  /**
   * this is really dangerous. this destroys all pref values
   * do not call this unless you know what you're doing!
   */
  void clearAllValues();

  /**
   * This is also very dangerous. This will low-level remove the files
   * associated with this server on disk. It does not notify any listeners.
   */
  void removeFiles();

  attribute boolean valid;

  AString toString();

  void displayOfflineMsg(in nsIMsgWindow aWindow);

  /* used for comparing nsIMsgIncomingServers */
  boolean equals(in nsIMsgIncomingServer server);

  /* Get Messages at startup */
  readonly attribute boolean downloadMessagesAtStartup; 

  /* check to this if the server supports filters */
  attribute boolean canHaveFilters;

  /**
   * can this server be removed from the account manager?  for
   * instance, local mail is not removable, but an imported folder is 
   */
  attribute boolean canDelete;

  attribute boolean loginAtStartUp;

  attribute boolean limitOfflineMessageSize;
  attribute long maxMessageSize;

  attribute nsIMsgRetentionSettings retentionSettings;

  /* check if this server can be a default server */
  readonly attribute boolean canBeDefaultServer;

  /* check if this server allows search operations */
  readonly attribute boolean canSearchMessages;

  /* check if this server allows canEmptyTrashOnExit operations */
  readonly attribute boolean canEmptyTrashOnExit;

  /* display startup page once per account per session */
  attribute boolean displayStartupPage;
  attribute nsIMsgDownloadSettings downloadSettings;

  /*
   * Offline support level. Support level can vary based on abilities 
   * and features each server can offer wrt to offline service.
   * Here is the legend to determine the each support level details
   *
   * supportLevel == 0  --> no offline support (default) 
   * supportLevel == 10 --> regular offline feature support
   * supportLevel == 20 --> extended offline feature support 
   *
   * Each server can initialize itself to the support level if needed
   * to override the default choice i.e., no offline support.
   *
   * POP3, None and Movemail will default to 0. 
   * IMAP level 10 and NEWS with level 20. 
   * 
   */
  attribute long offlineSupportLevel;

  /* create pretty name for migrated accounts */
  AString generatePrettyNameForMigration(); 

  /* does this server have disk space settings? */
  readonly attribute boolean supportsDiskSpace;

  /**
   * Hide this server/account from the UI - used for smart mailboxes.
   * The server can be retrieved from the account manager by name using the
   * various Find methods, but nsIMsgAccountManager's GetAccounts and 
   * GetAllServers methods won't return the server/account.
   */
  attribute boolean hidden;

  /**
   * If the server supports Fcc/Sent/etc, default prefs can point to 
   * the server. Otherwise, copies and folders prefs should point to
   * Local Folders.
   *
   * By default this value is set to true via global pref 'allows_specialfolders_usage'
   * (mailnews.js). For Nntp, the value is overridden to be false.
   * If ISPs want to modify this value, they should do that in their rdf file
   * by using this attribute. Please look at mozilla/mailnews/base/ispdata/aol.rdf for
   * usage example.
   */
  attribute boolean defaultCopiesAndFoldersPrefsToServer;

  /* can this server allows sub folder creation */
  attribute boolean canCreateFoldersOnServer;

  /* can this server allows message filing ? */
  attribute boolean canFileMessagesOnServer;

  /* can this server allow compacting folders ? */
  readonly attribute boolean canCompactFoldersOnServer;

  /* can this server allow undo delete ? */
  readonly attribute boolean canUndoDeleteOnServer;

  /* used for setting up the filter UI */
  readonly attribute nsMsgSearchScopeValue filterScope;

  /* used for setting up the search UI */
  readonly attribute nsMsgSearchScopeValue searchScope;

  /** 
   * If the password for the server is available either via authentication 
   * in the current session or from password manager stored entries, return
   * false. Otherwise, return true. If password is obtained from password 
   * manager, set the password member variable.
   */ 
  readonly attribute boolean passwordPromptRequired;

  /**
   * for mail, this configures both the MDN filter, and the server-side
   * spam filter filters, if needed.
   *
   * If we have set up to filter return receipts into
   * our Sent folder, this utility method creates
   * a filter to do that, and adds it to our filterList
   * if it doesn't exist.  If it does, it will enable it.
   *
   * this is not used by news filters (yet).
   */
  void configureTemporaryFilters(in nsIMsgFilterList filterList);

  /**
   * If Sent folder pref is changed we need to clear the temporary 
   * return receipt filter so that the new return receipt filter can
   * be recreated (by ConfigureTemporaryReturnReceiptsFilter()).
   */
  void clearTemporaryReturnReceiptsFilter();

  /**
   * spam settings
   */
  readonly attribute nsISpamSettings spamSettings;
  readonly attribute nsIMsgFilterPlugin spamFilterPlugin;

  nsIMsgFolder getMsgFolderFromURI(in nsIMsgFolder aFolderResource, in ACString aURI);

  /// Indicates if any other server has deferred storage to this account.
  readonly attribute boolean isDeferredTo;

  const long keepDups = 0;
  const long deleteDups = 1;
  const long moveDupsToTrash = 2;
  const long markDupsRead = 3;

  attribute long incomingDuplicateAction;

  // check if new hdr is a duplicate of a recently arrived header
  boolean isNewHdrDuplicate(in nsIMsgDBHdr aNewHdr);

  /**
   * Set a boolean to force an inherited propertyName to return empty instead
   * of inheriting from a parent folder, server, or the global
   *
   * @param propertyName         The name of the property
   * @param aForcePropertyEmpty  true if an empty inherited property should be returned
   */
  void setForcePropertyEmpty(in string propertyName, in boolean aForcePropertyEmpty);

  /**
   * Get a boolean to force an inherited propertyName to return empty instead
   * of inheriting from a parent folder, server, or the global
   *
   * @param propertyName      The name of the property
   *
   * @return                  true if an empty inherited property should be returned
   */
  boolean getForcePropertyEmpty(in string propertyName);

  /**
   * Return the order in which this server type should appear in the folder pane.
   * This sort order is a number between 100000000 and 900000000 so that RDF can
   * use it as a string.
   * The current return values are these:
   * 0 = default account,       100000000 = mail accounts (POP3/IMAP4),
   * 200000000 = Local Folders, 300000000 = IM accounts,
   * 400000000 = RSS,           500000000 = News
   * If a new server type is created a TB UI reviewer must decide its sort order.
   */
  readonly attribute long sortOrder;
};

%{C++
/*
 * Following values for offline support have been used by
 * various files. If you are modifying any of the values
 * below, please do take care of the following files.
 * - mozilla/mailnews/base/src/nsMsgAccountManagerDS.cpp
 * - mozilla/mailnews/base/util/nsMsgIncomingServer.cpp
 * - mozilla/mailnews/imap/src/nsImapIncomingServer.cpp
 * - mozilla/mailnews/local/src/nsPop3IncomingServer.cpp
 * - mozilla/mailnews/news/src/nsNntpIncomingServer.cpp
 * - mozilla/mailnews/base/content/msgAccountCentral.js
 * - mozilla/modules/libpref/src/init/mailnews.js
 * - ns/modules/libpref/src/init/mailnews-ns.js
 * - ns/mailnews/base/ispdata/aol.rdf
 * - ns/mailnews/base/ispdata/nswebmail.rdf
 */
#define OFFLINE_SUPPORT_LEVEL_NONE 0
#define OFFLINE_SUPPORT_LEVEL_REGULAR 10
#define OFFLINE_SUPPORT_LEVEL_EXTENDED 20
#define OFFLINE_SUPPORT_LEVEL_UNDEFINED -1

// Value when no port setting is found
#define PORT_NOT_SET -1

/* some useful macros to implement nsIMsgIncomingServer accessors */
#define NS_IMPL_SERVERPREF_STR(_class, _postfix, _prefname) \
NS_IMETHODIMP                              \
_class::Get##_postfix(nsACString& retval)  \
{                                          \
  return GetCharValue(_prefname, retval);  \
}                                          \
NS_IMETHODIMP                              \
_class::Set##_postfix(const nsACString& chvalue) \
{                                          \
  return SetCharValue(_prefname, chvalue); \
}

#define NS_IMPL_SERVERPREF_BOOL(_class, _postfix, _prefname)\
NS_IMETHODIMP                                               \
_class::Get##_postfix(bool *retval)                         \
{                                                           \
  return GetBoolValue(_prefname, retval);                   \
}                                                           \
NS_IMETHODIMP                                               \
_class::Set##_postfix(bool bvalue)                          \
{                                                           \
  return SetBoolValue(_prefname, bvalue);                   \
}

#define NS_IMPL_SERVERPREF_INT(_class, _postfix, _prefname)\
NS_IMETHODIMP                                              \
_class::Get##_postfix(int32_t *retval)                     \
{                                                          \
  return GetIntValue(_prefname, retval);                   \
}                                                          \
NS_IMETHODIMP                                              \
_class::Set##_postfix(int32_t ivalue)                      \
{                                                          \
  return SetIntValue(_prefname, ivalue);                   \
}

%}