chrome/common/extensions/api/settings_private.idl

// Copyright 2015 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.settingsPrivate</code> API to get or set preferences
// from the settings UI. Access is restricted to a set of allowed user facing
// preferences.
namespace settingsPrivate {
  enum PrefType { BOOLEAN, NUMBER, STRING, URL, LIST, DICTIONARY };

  enum ControlledBy {
    DEVICE_POLICY,
    USER_POLICY,
    OWNER,
    PRIMARY_USER,
    EXTENSION,

    // Preferences are controlled by the parent of the child user.
    PARENT,

    // Preferences are controlled neither by parent nor the child user.
    // Preference values are hard-coded values and can not be changed.
    CHILD_RESTRICTION
  };

  enum Enforcement {
    // Value cannot be changed by user.
    ENFORCED,
    // Value can be changed, but the administrator recommends a default.
    RECOMMENDED,
    // Value is protected by a code that only parents can access. The logic to
    // require the code is NOT automatically added to a preference using this
    // enforcement. This is only used to display the correct pref indicator.
    PARENT_SUPERVISED
  };

  dictionary PrefObject {
    // The key for the pref.
    DOMString key;

    // The type of the pref (e.g., boolean, string, etc.).
    PrefType type;

    // The current value of the pref.
    any? value;

    // The policy source of the pref; an undefined value means there is no
    // policy.
    ControlledBy? controlledBy;

    // The owner name if controlledBy == OWNER.
    // The primary user name if controlledBy == PRIMARY_USER.
    // The extension name if controlledBy == EXTENSION.
    DOMString? controlledByName;

    // The policy enforcement of the pref; must be specified if controlledBy is
    // also present.
    Enforcement? enforcement;

    // The recommended value if enforcement == RECOMMENDED.
    any? recommendedValue;

    // If enforcement == ENFORCED this optionally specifies preference values
    // that are still available for selection by the user. If set, must contain
    // at least 2 distinct values, as must contain |value| and
    // |recommendedValue| (if present).
    any[]? userSelectableValues;

    // If true, user control of the preference is disabled for reasons unrelated
    // to controlledBy (e.g. no signed-in profile is present). A false value is
    // a no-op.
    boolean? userControlDisabled;

    // The extension ID if controlledBy == EXTENSION.
    DOMString? extensionId;

    // Whether the controlling extension can be disabled if controlledBy ==
    // EXTENSION.
    boolean? extensionCanBeDisabled;
  };

  callback OnPrefSetCallback = void (boolean success);
  callback GetAllPrefsCallback = void (PrefObject[] prefs);
  callback GetPrefCallback = void (PrefObject pref);
  callback GetDefaultZoomCallback = void (double zoom);
  callback SetDefaultZoomCallback = void (boolean success);

  interface Functions {
    // Sets a pref value.
    // |name|: The name of the pref.
    // |value|: The new value of the pref.
    // |pageId|: An optional user metrics identifier.
    // |callback|: The callback for whether the pref was set or not.
    [supportsPromises] static void setPref(DOMString name,
                                           any value,
                                           optional DOMString pageId,
                                           optional OnPrefSetCallback callback);

    // Gets an array of all the prefs.
    [supportsPromises] static void getAllPrefs(GetAllPrefsCallback callback);

    // Gets the value of a specific pref.
    [supportsPromises] static void getPref(DOMString name,
                                           GetPrefCallback callback);

    // Gets the default page zoom factor. Possible values are currently between
    // 0.25 and 5. For a full list, see zoom::kPresetZoomFactors.
    [supportsPromises] static void getDefaultZoom(
        GetDefaultZoomCallback callback);

    // Sets the page zoom factor. Must be less than 0.001 different than a value
    // in zoom::kPresetZoomFactors.
    [supportsPromises] static void setDefaultZoom(
        double zoom,
        optional SetDefaultZoomCallback callback);
  };

  interface Events {
    // Fired when a set of prefs has changed.
    //
    // |prefs| The prefs that changed.
    static void onPrefsChanged(PrefObject[] prefs);
  };
};