gecko-dev/mailnews/base/public/nsIMsgIncomingServer.idl

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Seth Spitzer <sspitzer@netscape.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"
#include "MailNewsTypes2.idl"

interface nsIFileSpec;
interface nsIMsgFolder;
interface nsIMsgFolderCache;
interface nsIMsgWindow;
interface nsIMsgFilterList;
interface nsIMsgRetentionSettings;
interface nsIMsgDownloadSettings;
interface nsISpamSettings;
interface nsIMsgFilterPlugin;
interface nsIUrlListener;

/*
 * 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(55569286-ee09-45ec-a83b-96d0273a5ed8)]
interface nsIMsgIncomingServer : nsISupports {

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

  /**
   * pretty name - should be "userid on hostname"
   * if the pref is not set
   */
  attribute wstring 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 wstring constructedPrettyName;

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

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

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

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

  /**
   * the schema for the local mail store, such
   * as "mailbox", "imap", or "news"
   * used to construct URIs
   */
  readonly attribute string localStoreType;

  // Perform specific tasks (reset flags, remove files, etc) for account user/server name changes.
  void OnUserOrHostNameChanged(in string oldName, in string newName);
  
  /* should we remember the password? */
  attribute boolean rememberPassword;

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

  /* prompt the user for a password */
  string getPasswordWithUI(in wstring aPromptString, in wstring aPromptTitle, in nsIMsgWindow aMsgWindow, out boolean okayValue);

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

  /**
   * logon succeeded - persist password, if user chooses.
   */
  void storePassword(); 

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

  /* should we download whole messages when biff goes off? */
  /* in 4.x, this was "mail.pop3_gets_new_mail" for pop */
  /* "mail.imap.new_mail_get_headers" for imap, and it was global.  in 5.x, it is per server */
  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 nsIFileSpec localPath;

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

  /* the root folder for this server */
  attribute nsIMsgFolder rootFolder;

  /* handy accessor when we want a msg folder */
  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;

  /* should we use a secure channel? */
  attribute boolean isSecure;

  /* should we use secure authentication? */
  attribute boolean useSecAuth;

  /* can server support a secure channel? */
  readonly attribute boolean isSecureServer;

  /* what kind of logon redirector to use for this server, if any */
  attribute string redirectorType;

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

  /* get filter list */
  nsIMsgFilterList getFilterList(in nsIMsgWindow aMsgWindow);

  /* set filter list */
  void setFilterList(in nsIMsgFilterList aFilterList);

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

  /* 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();

  /* access to generic attributes */
  boolean getBoolValue(in string attr);
  void setBoolValue(in string attr, in boolean value);

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

  wstring getUnicharValue(in string attr);
  void setUnicharValue(in string attr, in wstring value);
  
  long getIntValue(in string attr);
  void setIntValue(in string attr, in long value);

  nsIFileSpec getFileValue(in string attr);
  void setFileValue(in string attr, in nsIFileSpec value);

  /**
   * 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 remove the files
   * associated with this server on disk.
   */
  void removeFiles();
  
  attribute boolean valid;
  
  wstring 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 */
  readonly 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 */
  wstring generatePrettyNameForMigration(); 

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

  /**
   * 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;

  /** 
   * these generic getter / setters, useful for extending mailnews 
   * note, these attributes persist across sessions
   */
  wstring getUnicharAttribute(in string name);
  void setUnicharAttribute(in string name, in wstring value);
  
  string getCharAttribute(in string name);
  void setCharAttribute(in string name, in string value);

  boolean getBoolAttribute(in string name);
  void setBoolAttribute(in string name, in boolean value);

  long getIntAttribute(in string name);
  void setIntAttribute(in string name, in long value);

  /** 
   * 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
   */
  attribute nsISpamSettings spamSettings;
  readonly attribute nsIMsgFilterPlugin spamFilterPlugin;

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

  readonly attribute boolean isDeferredTo;
};

%{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/resources/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(char **retval)   			\
{											   	\
  return GetCharValue(_prefname, retval);		\
}												\
NS_IMETHODIMP	   								\
_class::Set##_postfix(const char *chvalue)			\
{												\
  return SetCharValue(_prefname, chvalue);		\
}

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

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

#define NS_IMPL_SERVERPREF_FILE(_class, _postfix, _prefname)\
NS_IMETHODIMP								   	\
_class::Get##_postfix(nsIFileSpec **retval)   		\
{											   	\
  return GetFileValue(_prefname, retval);			\
}												\
NS_IMETHODIMP	   								\
_class::Set##_postfix(nsIFileSpec* ivalue)			\
{												\
  return SetFileValue(_prefname, ivalue);			\
}


%}