chrome/common/extensions/api/screenlock_private.idl

// Copyright 2013 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.

// Control and monitor the screen locker.
[permissions=screenlockPrivate, nodoc]
namespace screenlockPrivate {
  // Supported authentication types shown on the user pod.
  // |offlinePassword|: The standard password field, which authenticates using
  //                   the user's regular password. The $(ref:onAuthAttempted)()
  //                   event will not be fired for this authentication type.
  // |numericPin|: An input field for a 4 digit numeric pin code.
  // |userClick|: Makes the user pod clickable when it is focused, and
  //                 clicking on it attempts the authentication. If |value| is
  //                 specified with $(ref:setAuthType)(), the text is displayed
  //                 in the password field.
  enum AuthType {offlinePassword, numericPin, userClick};

  // Extension resource for a icon representation for a scale factor.
  dictionary IconRepresentation {
    // The scale factor the representation is for.
    double scaleFactor;
    // The image resource URL.
    DOMString url;
  };

  callback BooleanCallback = void(boolean locked);
  callback AuthTypeCallback = void(AuthType authType);

  interface Functions {
    // Returns true if the screen is currently locked, false otherwise.
    static void getLocked(BooleanCallback callback);

    // Set <code>locked=true</code> to lock the screen,
    // <code>locked=false</code> to unlock it.
    static void setLocked(boolean locked);

    // Show a message to the user on the unlock UI if the screen is locked.
    static void showMessage(DOMString message);

    // Show a custom icon beside the input field on the user pod.
    // |icon|: Extension resoucres for the icon's multi-scale representations.
    //     Currently, only scales 1 and 2 are supported. The list must have a
    //     resource for at least scale 1.
    static void showCustomIcon(IconRepresentation[] icon);

    // Hides the custom icon added by $(ref:showCustomIcon)().
    static void hideCustomIcon();

    // Returns the current auth type used for the user pod.
    static void getAuthType(AuthTypeCallback callback);

    // Set the type of the authentication for the user pod. The input field
    // area of the user pod below the user's portrait will be changed.
    // |authType|: The type of authentication to use.
    // |initialValue|: The initial value to populate the input field.
    static void setAuthType(AuthType authType, optional DOMString initialValue);

    // Accepts or rejects the current auth attempt.
    static void acceptAuthAttempt(boolean accept);
  };

  interface Events {
    // Fires whenever the screen is locked or unlocked.
    static void onChanged(boolean locked);

    // Fires when the user attempts to authenticate with the user's input.
    // There will be at most one auth attempt active at any time.
    // Call $(ref:acceptAuthAttempt)() to accept or reject this attempt.
    // Note: Some authentication types will not have an input.
    static void onAuthAttempted(AuthType type, DOMString input);
  };
};