// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.passwordsPrivate</code> API to add or remove password
// data from the settings UI.
namespace passwordsPrivate {
  dictionary UrlCollection {
    // The fully specified URL of the credential's origin.
    DOMString origin;

    // A human readable version of the URL of the credential's origin.
    DOMString shown;

    // The URL that will be linked to when an entry is clicked.
    DOMString link;
  };

  // Pair of a URL collection and a username saved for these URLs.
  dictionary LoginPair {
    UrlCollection urls;

    // The username used in conjunction with the saved password.
    DOMString username;
  };

  // Entry used to display a password in the settings UI.
  dictionary PasswordUiEntry {
    // The login information for this entry.
    LoginPair loginPair;

    // The number of characters in the password; used to display placeholder
    // dots in the UI.
    long numCharactersInPassword;

    // Text shown if the password was obtained via a federated identity.
    DOMString? federationText;

    // An index to refer back to a unique password entry record.
    long index;
  };

  // Dictionary passed to listeners for the onPlaintextPasswordRetrieved event.
  dictionary PlaintextPasswordEventParameters {
    // An index to refer back to a unique password entry record.
    long index;

    // The password in plaintext.
    DOMString plaintextPassword;
  };

  dictionary ExceptionEntry {
    UrlCollection urls;

    // An index to refer back to a unique exception entry record.
    long index;
  };

  callback PasswordListCallback = void(PasswordUiEntry[] entries);
  callback ExceptionListCallback = void(ExceptionEntry[] exceptions);

  interface Functions {
    // Removes the saved password corresponding to |loginPair|. If no saved
    // password for this pair exists, this function is a no-op.
    //
    // |index|: The index for the password entry being removed.
    static void removeSavedPassword(long index);

    // Removes the saved password exception corresponding to |exceptionUrl|. If
    // no exception with this URL exists, this function is a no-op.
    //
    // |index|: The index for the exception url entry being removed.
    static void removePasswordException(long index);

    // Undoes the last removal of a saved password or exception.
    static void undoRemoveSavedPasswordOrException();

    // Returns the plaintext password corresponding to |index|. Note that on
    // some operating systems, this call may result in an OS-level
    // reauthentication. Once the password has been fetched, it will be returned
    // via the onPlaintextPasswordRetrieved event.
    // TODO(hcarmona): Investigate using a callback for consistency.
    //
    // |index|: The index for the password entry being being retrieved.
    static void requestPlaintextPassword(long index);

    // Returns the list of saved passwords.
    // |callback|: Called with the list of saved passwords.
    static void getSavedPasswordList(PasswordListCallback callback);

    // Returns the list of password exceptions.
    // |callback|: Called with the list of password exceptions.
    static void getPasswordExceptionList(ExceptionListCallback callback);

    // Triggers the Password Manager password import functionality.
    static void importPasswords();

    // Triggers the Password Manager password export functionality.
    static void exportPasswords();
  };

  interface Events {
    // Fired when the saved passwords list has changed, meaning that an entry
    // has been added or removed.
    //
    // |entries|: The updated list of password entries.
    static void onSavedPasswordsListChanged(PasswordUiEntry[] entries);

    // Fired when the password exceptions list has changed, meaning that an
    // entry has been added or removed.
    //
    // |exceptions|: The updated list of password exceptions.
    static void onPasswordExceptionsListChanged(ExceptionEntry[] exceptions);

    // Fired when a plaintext password has been fetched in response to a call to
    // chrome.passwordsPrivate.requestPlaintextPassword().
    //
    // |index|: The index for the password entry being being retrieved.
    // |plaintextPassword|: The plaintext password which was retrieved.
    static void onPlaintextPasswordRetrieved(
        PlaintextPasswordEventParameters dict);
  };
};
