/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** 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) 1999
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * 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 nsIMsgWindow;
interface nsIMsgMailNewsUrl;
interface nsIImapProtocol;
interface nsIImapUrl;
interface nsIImapMockChannel;

/**
 * nsIImapServerSink is designed to be used as a proxy to the application's UI
 * thread from the running IMAP threads.
 */
[scriptable, uuid(24136ca7-0000-4731-8d5f-fc0908aa7c75)]
interface nsIImapServerSink : nsISupports {
  /**
   * Check if the given folder path is a possible IMAP mailbox.
   * @param folderPath folder path to check
   * @param hierarchyDelimiter IMAP hierarchy delimiter in canonical format,
   *                           i.e., hierarchy delimiter has been replaced
   *                           with '/'
   * @param boxFlags IMAP folder flags (for subscription, namespaces etc.)
   * @return true if it's a new mailbox
   */
  boolean possibleImapMailbox(in ACString folderPath,
                              in char hierarchyDelimiter, in long boxFlags);
  boolean folderNeedsACLInitialized(in ACString folderPath);
  void addFolderRights(in ACString folderPath, in ACString userName, in ACString rights);
  void refreshFolderRights(in ACString folderPath);
  void discoveryDone();
  void onlineFolderDelete(in ACString folderName);
  void onlineFolderCreateFailed(in ACString aFolderName);
  void onlineFolderRename(in nsIMsgWindow msgWindow, in ACString oldName, in ACString newName);
  boolean folderIsNoSelect(in ACString folderName);
  void setFolderAdminURL(in ACString folderName, in ACString adminUrl);
  boolean folderVerifiedOnline(in ACString folderName);

  void setCapability(in unsigned long capability);
  /// RFC 2971 ID server response
  void setServerID(in ACString aServerID);
  boolean loadNextQueuedUrl(in nsIImapProtocol protocol);

  /**
   * Prepare to retry the given URL.
   * @param imapUrl the url we're going to retry
   * @return channel to associate with the url. We return this because access
   *         to the channel should only happen on the ui thread.
   */
  nsIImapMockChannel prepareToRetryUrl(in nsIImapUrl imapUrl);

  /**
   * Suspend the url. This puts it at the end of the queue. If the queue is
   * empty, the url will get resumed immediately. Currently, the plan is
   * do this when we have to download a lot of headers in chunks, though we
   * could find other uses for it.
   * @param imapUrl url to suspend
   */
  void suspendUrl(in nsIImapUrl aImapUrl);

  /**
   * Retry the given URL.
   * @param imapUrl url to retry
   * @param channel the channel to associate with the url
   */
  void retryUrl(in nsIImapUrl imapUrl, in nsIImapMockChannel channel);

  /**
   * If previous URL failed, this gives server chance to abort URLs with same
   * mock channel.
   */
  void abortQueuedUrls();
  AString getImapStringByID(in long msgId);

  /**
   * Alerts the user that the login to the IMAP server failed. Asks whether the
   * connection should: retry, cancel, or request a new password.
   *
   * @param aMsgWindow The message window associated with this action (cannot
   *                   be null).
   * @return           The button pressed. 0 for retry, 1 for cancel,
   *                   2 for enter a new password.
   */
  PRInt32 promptLoginFailed(in nsIMsgWindow aMsgWindow);

  /**
   * Alerts the user with the given string (FE = 'Front End').
   *
   * @param aAlertSring  The string to alert the user with.
   * @param aUrl         The running url.
   */
  void fEAlert(in AString aAlertSring, in nsIMsgMailNewsUrl aUrl);

  /**
   * Alerts the user with a localized string. It will attempt to fill in
   * the hostname into the string if necessary.
   *
   * @param aMsgId  The id of the string to present to the user..
   * @param aUrl    The running url.
   */
  void fEAlertWithID(in long aMsgId, in nsIMsgMailNewsUrl aUrl);

  /**
   * Takes a response from the server and prepends it with IMAP_SERVER_SAID 
   *
   * @param aServerString  The string to alert the user with.
   * @param url            The running url.
   */
  void fEAlertFromServer(in ACString aServerString, in nsIMsgMailNewsUrl aUrl);

  void commitNamespaces();

  /**
   * Returns a password via the out param, if we were able to prompt for one,
   * or had one stored.
   * If there is already a password prompt up, we return false, but we
   * ask the async prompt service to notify us when we can put up a prompt.
   * When that notification is received, we prompt the user and set the
   * password on the protocol object, and signal a monitor that the imap
   * thread should be waiting on.
   *
   * rv is NS_MSG_PASSWORD_PROMPT_CANCELLED if the user cancels the
   * password prompt. That's not an exception, however.
   *
   * @param aProtocol imap protocol object requesting the password.
   * @param aNewPasswordRequested Forces password prompt immediately
   * @param aPassword returns the password, unless we had to prompt or use the,
   *                  login manager and there was already a prompt up.
   */
  void asyncGetPassword(in nsIImapProtocol aProtocol,
                        in boolean aNewPasswordRequested,
                        out ACString aPassword);

  attribute boolean userAuthenticated;
  void setMailServerUrls(in ACString manageMailAccount, in ACString manageLists, in ACString manageFilters);

  readonly attribute ACString arbitraryHeaders;
  void forgetPassword();

  readonly attribute boolean showAttachmentsInline;
  string cramMD5Hash(in string decodedChallenge, in string key);
  /// String to send to the imap server as the login user name.
  readonly attribute ACString loginUsername;
};
