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

/**
 * An interface for managing the state of passwords queried from the user and
 * from the password manager.
 *
 * This interface represents passwords as UTF-8 strings for cross-language
 * compatibility, but implementations may use alternative string representations
 * and convert to UTF-8 when crossing this interface boundary.
 */
[scriptable, uuid(2b876904-74d1-4be8-a1b4-d6ef1b371bfc)]
interface msgIPasswordAuthModule : nsISupports {

  /**
  * The plaintext representation of the password in UTF-8 stored in memory.
  */
  attribute AUTF8String cachedPassword;

  /**
   * Attempts to get the password first from the password manager, if that
   * fails it will attempt to get it from the user.
   *
   * Native consumers may use the method's return value as input to
   * prefill the password prompt with.
   *
   * @param username The username associated with the password.
   * @param hostname The hostname associated with the password.
   * @param serverType The server type.
   * @param promptString The text of the prompt if the user is prompted for
   *                      password.
   * @param promptTitle  The title of the prompt if the user is prompted.
   * @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.
   */
  AUTF8String queryPasswordFromUserAndCache(
    in AUTF8String username,
    in AUTF8String hostname,
    in AUTF8String serverType,
    in AUTF8String promptString,
    in AUTF8String promptTitle);

  /**
   * Attempt to get the password from the password manager and store it locally in
   * memory.
   *
   * If the password could not be obtained, the cache and return values will be
   * empty.
   *
   * @param username The username associated with the password.
   * @param hostname The hostname associated with the password.
   * @param serverType The server type.
   *
   * @return The obtained password, which could be empty.
   */
  AUTF8String queryPasswordFromManagerAndCache(
    in AUTF8String username,
    in AUTF8String hostname,
    in AUTF8String serverType);

  /**
   * Forget the password in memory and in the password manager.
   *
   * @param username The username associated with the password.
   * @param hostname The hostname associated with the password.
   * @param serverType The server type.
   */
  void forgetPassword(
    in AUTF8String username,
    in AUTF8String hostname,
    in AUTF8String serverType);

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

};