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

// Use the <code>chrome.quickUnlockPrivate</code> API to change whether the
// lock screen is enabled and which modes are allowed (active) for unlocking a
// Chrome OS device from the lock screen. The API is also used to set quick
// unlock credentials.
// Note: The API is named 'quickUnlock' for historical reasons but it should be
// used for all lock screen settings.
// Note: This API can not be used to actually unlock the device.

[platforms=("chromeos")]
namespace quickUnlockPrivate {
  dictionary TokenInfo {
    // The authentication token that can be passed to $(ref:setModes) calls.
    DOMString token;

    // The number of seconds until the token expires. The UI should refresh the
    // token before it expires.
    long lifetimeSeconds;
  };

  // TODO(jdufault): Add more quick unlock modes, such as a pattern unlock.
  enum QuickUnlockMode {
    PIN
  };

  // The problems a given PIN might have.
  enum CredentialProblem {
    TOO_SHORT,
    TOO_LONG,
    TOO_WEAK,
    CONTAINS_NONDIGIT
  };

  dictionary CredentialCheck {
    // The given PINs errors. Users cannot proceed with an error.
    CredentialProblem[] errors;

    // THe given PINs warnings. Users can, but are not advised to proceed with
    // a warning.
    CredentialProblem[] warnings;
  };

  dictionary CredentialRequirements {
    // The minimum allowed length for a PIN.
    long minLength;

    // The maximum allowed length for a PIN. A value of 0 indicates no maximum
    // length.
    long maxLength;
  };

  callback VoidResultCallback = void ();
  callback BooleanResultCallback = void (boolean value);
  callback TokenResultCallback = void (TokenInfo result);
  callback ModesCallback = void (QuickUnlockMode[] modes);
  callback CredentialCheckCallback = void (CredentialCheck check);
  callback CredentialRequirementsCallback =
      void (CredentialRequirements requirements);

  interface Functions {
    // Returns a token that can be used for future operations and the number
    // of seconds until the token expires.
    // |accountPassword|: The account password for the logged in user.
    static void getAuthToken(
        DOMString accountPassword,
        TokenResultCallback onComplete);

    // Sets the lock screen enabled state. NOTE: The lock enabled state is
    // reflected in the settings.enable_screen_lock pref, which can be read
    // but not written using the settings_private API (which also provides
    // policy information). This API must be used to change the pref.
    // |token|: The token returned by $(ref:getAuthToken).
    // |enabled|: Whether to enable the lock screen.
    static void setLockScreenEnabled(
        DOMString token,
        boolean enabled,
        optional VoidResultCallback onComplete);

    // Sets the PIN auto submit enabled state. NOTE: The PIN autosubmit state is
    // reflected in the pin_unlock_autosubmit_enabled pref, which can be read
    // but not written using the settings_private API (which also provides
    // policy information). This API must be used to change the pref.
    // |token|: The authentication token.
    // |pin|: The PIN of the logged in user.
    // |enabled|: Whether to enable PIN auto submit.
    // |onComplete|: Called with true if the quick unlock state was updated,
    //     false otherwise. The update is treated as a single atomic operation.
    static void setPinAutosubmitEnabled(
        DOMString token,
        DOMString pin,
        boolean enabled,
        BooleanResultCallback onComplete);

    // Tests wether it is currently possible to authenticate using PIN.
    static void canAuthenticatePin(
        BooleanResultCallback onComplete);

    // Returns the set of quick unlock modes that are available for the user to
    // use. Some quick unlock modes may be disabled by policy.
    static void getAvailableModes(
        ModesCallback onComplete);

    // Returns the quick unlock modes that are currently enabled and usable on
    // the lock screen.
    static void getActiveModes(ModesCallback onComplete);


    // Checks if the given credential can be used for the given unlock mode.
    // Enterprise policy can change credential requirements.
    // |mode|: The quick unlock mode that is used.
    // |credential|: The given credential.
    // |onComplete|: Called with a list of warnings and errors the given
    //     |credential| has (or an empty list if there are none).
    static void checkCredential(
        QuickUnlockMode mode,
        DOMString credential,
        CredentialCheckCallback onComplete);

    // Gets the credential requirements for the given unlock mode.
    // |mode|: The quick unlock mode that is used.
    // |onComplete|: Called with the credential requirements of the given
    //     |mode|.
    static void getCredentialRequirements(
        QuickUnlockMode mode,
        CredentialRequirementsCallback onComplete);

    // Update the set of quick unlock modes that are currently active/enabled.
    // |token|: The token returned by $(ref:getAuthToken).
    // |modes|: The quick unlock modes that should be active.
    // |credentials|: The associated credential for each mode. To keep the
    //     credential the same for the associated mode, pass an empty string.
    // |onComplete|: Called with true if the quick unlock state was updated,
    //     false otherwise. The update is treated as a single atomic operation.
    static void setModes(
        DOMString token,
        QuickUnlockMode[] modes,
        DOMString[] credentials,
        VoidResultCallback onComplete);
  };

  interface Events {
    // Called after the active set of quick unlock modes has changed.
    // |activeModes|: The set of quick unlock modes which are now active.
    static void onActiveModesChanged(QuickUnlockMode[] activeModes);
  };
};