path: root/chrome/common/extensions/api/developer_private.idl

// Copyright (c) 2012 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.

// developerPrivate API.
// This is a private API exposing developing and debugging functionalities for
// apps and extensions.
[use_movable_types=true] namespace developerPrivate {

  // DEPRECATED: Prefer ExtensionType.
  enum ItemType {
    hosted_app,
    packaged_app,
    legacy_packaged_app,
    extension,
    theme
  };

  // DEPRECATED: Prefer ExtensionView.
  dictionary ItemInspectView {
    // path to the inspect page.
    DOMString path;

    // For lazy background pages, the value is -1.
    long render_process_id;
    // This actually refers to a render frame.
    long render_view_id;

    boolean incognito;
    boolean generatedBackgroundPage;
  };

  // DEPRECATED: Use OpenDevTools.
  dictionary InspectOptions {
    DOMString extension_id;
    (DOMString or long) render_process_id;
    (DOMString or long) render_view_id;
    boolean incognito;
  };

  dictionary InstallWarning {
    DOMString message;
  };

  enum ExtensionType {
    HOSTED_APP,
    PLATFORM_APP,
    LEGACY_PACKAGED_APP,
    EXTENSION,
    THEME,
    SHARED_MODULE
  };

  enum Location {
    FROM_STORE,
    UNPACKED,
    THIRD_PARTY,
    // "Unknown" includes crx's installed from chrome://extensions.
    UNKNOWN
  };

  enum ViewType {
    APP_WINDOW,
    BACKGROUND_CONTENTS,
    COMPONENT,
    EXTENSION_BACKGROUND_PAGE,
    EXTENSION_DIALOG,
    EXTENSION_GUEST,
    EXTENSION_POPUP,
    LAUNCHER_PAGE,
    PANEL,
    TAB_CONTENTS
  };

  enum ErrorType {
    MANIFEST,
    RUNTIME
  };

  enum ErrorLevel {
    LOG,
    WARN,
    ERROR
  };

  enum ExtensionState {
    ENABLED,
    DISABLED,
    TERMINATED
  };

  enum CommandScope {
    GLOBAL,
    CHROME
  };

  dictionary AccessModifier {
    boolean isEnabled;
    boolean isActive;
  };

  dictionary StackFrame {
    long lineNumber;
    long columnNumber;
    DOMString url;
    DOMString functionName;
  };

  dictionary ManifestError {
    ErrorType type;
    DOMString extensionId;
    boolean fromIncognito;
    DOMString source;
    DOMString message;
    long id;
    DOMString manifestKey;
    DOMString? manifestSpecific;
  };

  dictionary RuntimeError {
    ErrorType type;
    DOMString extensionId;
    boolean fromIncognito;
    DOMString source;
    DOMString message;
    long id;
    ErrorLevel severity;
    DOMString contextUrl;
    long occurrences;
    long renderViewId;
    long renderProcessId;
    boolean canInspect;
    StackFrame[] stackTrace;
  };

  dictionary DisableReasons {
    boolean suspiciousInstall;
    boolean corruptInstall;
    boolean updateRequired;
  };

  dictionary OptionsPage {
    boolean openInTab;
    DOMString url;
  };

  dictionary HomePage {
    DOMString url;
    boolean specified;
  };

  dictionary ExtensionView {
    DOMString url;
    long renderProcessId;
    // This actually refers to a render frame.
    long renderViewId;
    boolean incognito;
    boolean isIframe;
    ViewType type;
  };

  enum ControllerType {
    POLICY,
    CHILD_CUSTODIAN,
    SUPERVISED_USER_CUSTODIAN
  };

  dictionary ControlledInfo {
    ControllerType type;
    DOMString text;
  };

  dictionary Command {
    DOMString description;
    DOMString keybinding;
    DOMString name;
    boolean isActive;
    CommandScope scope;
    boolean isExtensionAction;
  };

  dictionary ExtensionInfo {
    boolean actionButtonHidden;
    DOMString? blacklistText;
    Command[] commands;
    ControlledInfo? controlledInfo;
    DOMString[] dependentExtensions;
    DOMString description;
    DisableReasons disableReasons;
    AccessModifier errorCollection;
    AccessModifier fileAccess;
    HomePage homePage;
    DOMString iconUrl;
    DOMString id;
    AccessModifier incognitoAccess;
    DOMString[] installWarnings;
    DOMString? launchUrl;
    Location location;
    DOMString? locationText;
    ManifestError[] manifestErrors;
    boolean mustRemainInstalled;
    DOMString name;
    boolean offlineEnabled;
    OptionsPage? optionsPage;
    DOMString? path;
    DOMString? prettifiedPath;
    AccessModifier runOnAllUrls;
    RuntimeError[] runtimeErrors;
    DOMString[] runtimeWarnings;
    ExtensionState state;
    ExtensionType type;
    DOMString updateUrl;
    boolean userMayModify;
    DOMString version;
    ExtensionView[] views;
  };

  dictionary ProfileInfo {
    boolean appInfoDialogEnabled;
    boolean canLoadUnpacked;
    boolean inDeveloperMode;
    boolean isIncognitoAvailable;
    boolean isSupervised;
  };

  // DEPRECATED: Prefer ExtensionInfo.
  dictionary ItemInfo {
    DOMString id;
    DOMString name;
    DOMString version;
    DOMString description;
    boolean may_disable;
    boolean enabled;
    boolean isApp;
    ItemType type;
    boolean allow_activity;
    boolean allow_file_access;
    boolean wants_file_access;
    boolean incognito_enabled;
    boolean is_unpacked;
    boolean allow_reload;
    boolean terminated;
    boolean allow_incognito;
    DOMString icon_url;

    // Path of an unpacked extension.
    DOMString? path;

    // Options settings page for the item.
    DOMString? options_url;
    DOMString? app_launch_url;
    DOMString? homepage_url;
    DOMString? update_url;
    InstallWarning[] install_warnings;
    any[] manifest_errors;
    any[] runtime_errors;
    boolean offline_enabled;

    // All views of the current extension.
    ItemInspectView[] views;
  };

  dictionary GetExtensionsInfoOptions {
    boolean? includeDisabled;
    boolean? includeTerminated;
  };

  dictionary ExtensionConfigurationUpdate {
    DOMString extensionId;
    boolean? fileAccess;
    boolean? incognitoAccess;
    boolean? errorCollection;
    boolean? runOnAllUrls;
    boolean? showActionButton;
  };

  dictionary ProfileConfigurationUpdate {
    boolean? inDeveloperMode;
  };

  dictionary ExtensionCommandUpdate {
    DOMString extensionId;
    DOMString commandName;
    CommandScope? scope;
    DOMString? keybinding;
  };

  dictionary ReloadOptions {
    // If false, an alert dialog will show in the event of a reload error.
    // Defaults to false.
    boolean? failQuietly;
  };

  dictionary LoadUnpackedOptions {
    // If false, an alert dialog will show in the event of a reload error.
    // Defaults to false.
    boolean? failQuietly;
  };

  enum PackStatus {
    SUCCESS,
    ERROR,
    WARNING
  };

  enum FileType {
    LOAD,
    PEM
  };

  enum SelectType {
    FILE,
    FOLDER
  };

  enum EventType {
    INSTALLED,
    UNINSTALLED,
    LOADED,
    UNLOADED,
    // New window / view opened.
    VIEW_REGISTERED,
    // window / view closed.
    VIEW_UNREGISTERED,
    ERROR_ADDED,
    ERRORS_REMOVED,
    PREFS_CHANGED,
    WARNINGS_CHANGED
  };

  dictionary PackDirectoryResponse {
    // The response message of success or error.
    DOMString message;

    // Unpacked items's path.
    DOMString item_path;

    // Permanent key path.
    DOMString pem_path;

    long override_flags;
    PackStatus status;
  };

  dictionary ProjectInfo {
    DOMString name;
  };

  dictionary EventData {
    EventType event_type;
    DOMString item_id;
    ExtensionInfo? extensionInfo;
  };

  dictionary RequestFileSourceProperties {
    // The ID of the extension owning the file.
    DOMString extensionId;

    // The path of the file, relative to the extension; e.g., manifest.json,
    // script.js, or main.html.
    DOMString pathSuffix;

    // The error message which was thrown as a result of the error in the file.
    DOMString message;

    // The key in the manifest which caused the error (e.g., "permissions").
    // (Required for "manifest.json" files)
    DOMString? manifestKey;

    // The specific portion of the manifest key which caused the error (e.g.,
    // "foo" in the "permissions" key). (Optional for "manifest.json" file).
    DOMString? manifestSpecific;

    // The line number which caused the error (optional for non-manifest files).
    long? lineNumber;
  };

  dictionary RequestFileSourceResponse {
    // The region of the code which threw the error, and should be highlighted.
    DOMString highlight;

    // The region before the "highlight" portion.
    // If the region which threw the error was not found, the full contents of
    // the file will be in the "beforeHighlight" section.
    DOMString beforeHighlight;

    // The region after the "highlight" portion.
    DOMString afterHighlight;

    // A title for the file in the form '<extension name>: <file name>'.
    DOMString title;

    // The error message.
    DOMString message;
  };

  dictionary OpenDevToolsProperties {
    // The ID of the extension. This is only needed if opening the background
    // page (where renderViewId and renderProcessId are -1).
    DOMString? extensionId;

    // The ID of the render frame in which the error occurred.
    // Despite being called renderViewId, this refers to a render frame.
    long renderViewId;

    // The ID of the process in which the error occurred.
    long renderProcessId;

    boolean? incognito;

    // The URL in which the error occurred.
    DOMString? url;

    // The line to focus the devtools at.
    long? lineNumber;

    // The column to focus the devtools at.
    long? columnNumber;
  };

  dictionary DeleteExtensionErrorsProperties {
    DOMString extensionId;
    long[]? errorIds;
    ErrorType? type;
  };

  callback VoidCallback = void ();
  callback BooleanCallback = void (boolean result);
  callback ExtensionInfosCallback = void (ExtensionInfo[] result);
  callback ExtensionInfoCallback = void (ExtensionInfo result);
  callback ItemsInfoCallback = void (ItemInfo[] result);
  callback ProfileInfoCallback = void (ProfileInfo info);
  callback GetProjectsInfoCallback = void (ProjectInfo[] result);
  callback PathCallback = void (DOMString path);
  callback PackCallback = void (PackDirectoryResponse response);
  callback VoidCallback = void();
  callback RequestFileSourceCallback =
      void (RequestFileSourceResponse response);

  interface Functions {
    // Runs auto update for extensions and apps immediately.
    // |callback| : Called with the boolean result, true if autoUpdate is
    // successful.
    static void autoUpdate(optional BooleanCallback callback);

    // Returns information of all the extensions and apps installed.
    // |options| : Options to restrict the items returned.
    // |callback| : Called with extensions info.
    static void getExtensionsInfo(optional GetExtensionsInfoOptions options,
                                  optional ExtensionInfosCallback callback);

    // Returns information of a particular extension.
    // |id| : The id of the extension.
    // |callback| : Called with the result.
    static void getExtensionInfo(DOMString id,
                                 optional ExtensionInfoCallback callback);

    // Returns information of all the extensions and apps installed.
    // |includeDisabled| : include disabled items.
    // |includeTerminated| : include terminated items.
    // |callback| : Called with items info.
    [deprecated="Use getExtensionsInfo"] static void getItemsInfo(
        boolean includeDisabled,
        boolean includeTerminated,
        ItemsInfoCallback callback);

    // Returns the current profile's configuration.
    static void getProfileConfiguration(ProfileInfoCallback callback);

    // Updates the active profile.
    // |update| : The parameters for updating the profile's configuration.  Any
    //     properties omitted from |update| will not be changed.
    static void updateProfileConfiguration(ProfileConfigurationUpdate update,
                                           optional VoidCallback callback);

    // Opens a permissions dialog.
    // |extensionId| : The id of the extension to show permissions for.
    static void showPermissionsDialog(DOMString extensionId,
                                      optional VoidCallback callback);

    // Reloads a given extension.
    // |extensionId| : The id of the extension to reload.
    // |options| : Additional configuration parameters.
    static void reload(DOMString extensionId,
                       optional ReloadOptions options,
                       optional VoidCallback callback);

    // Modifies an extension's current configuration.
    // |update| : The parameters for updating the extension's configuration.
    //     Any properties omitted from |update| will not be changed.
    static void updateExtensionConfiguration(
        ExtensionConfigurationUpdate update,
        optional VoidCallback callback);

    // Loads a user-selected unpacked item.
    // |options| : Additional configuration parameters.
    static void loadUnpacked(optional LoadUnpackedOptions options,
                             optional VoidCallback callback);

    // Loads an extension / app.
    // |directory| : The directory to load the extension from.
    static void loadDirectory(
        [instanceOf=DirectoryEntry] object directory,
        PathCallback callback);

    // Open Dialog to browse to an entry.
    // |selectType| : Select a file or a folder.
    // |fileType| : Required file type. For example, pem type is for private
    // key and load type is for an unpacked item.
    // |callback| : called with selected item's path.
    static void choosePath(SelectType selectType,
                           FileType fileType,
                           PathCallback callback);

    // Pack an extension.
    // |rootPath| : The path of the extension.
    // |privateKeyPath| : The path of the private key, if one is given.
    // |flags| : Special flags to apply to the loading process, if any.
    // |callback| : called with the success result string.
    static void packDirectory(DOMString path,
                              optional DOMString privateKeyPath,
                              optional long flags,
                              optional PackCallback callback);

    // Returns true if the profile is managed.
    static void isProfileManaged(BooleanCallback callback);

    // Reads and returns the contents of a file related to an extension which
    // caused an error.
    static void requestFileSource(RequestFileSourceProperties properties,
                                  RequestFileSourceCallback callback);

    // Open the developer tools to focus on a particular error.
    static void openDevTools(OpenDevToolsProperties properties,
                             optional VoidCallback callback);

    // Delete reported extension erors.
    // |properties| : The properties specifying the errors to remove.
    static void deleteExtensionErrors(
        DeleteExtensionErrorsProperties properties,
        optional VoidCallback callback);

    // Repairs the extension specified.
    // |extensionId| : The id of the extension to repair.
    static void repairExtension(DOMString extensionId,
                                optional VoidCallback callback);

    // Shows the options page for the extension specified.
    // |extensionId| : The id of the extension to show the options page for.
    static void showOptions(DOMString extensionId,
                            optional VoidCallback callback);

    // Shows the path of the extension specified.
    // |extensionId| : The id of the extension to show the path for.
    static void showPath(DOMString extensionId, optional VoidCallback callback);

    // (Un)suspends global shortcut handling.
    // |isSuspended| : Whether or not shortcut handling should be suspended.
    static void setShortcutHandlingSuspended(boolean isSuspended,
                                             optional VoidCallback callback);

    // Updates an extension command.
    // |update| : The parameters for updating the extension command.
    static void updateExtensionCommand(ExtensionCommandUpdate update,
                                       optional VoidCallback callback);

    [nocompile, deprecated="Use management.setEnabled"]
        static void enable(DOMString id,
                           boolean enabled,
                           optional VoidCallback callback);
    [nocompile, deprecated="Use updateExtensionConfiguration"]
        static void allowIncognito(DOMString extensionId,
                                   boolean allow,
                                   optional VoidCallback callback);
    [nocompile, deprecated="Use updateExtensionConfiguration"]
        static void allowFileAccess(DOMString extensionId,
                                    boolean allow,
                                    optional VoidCallback callback);
    [nocompile, deprecated="Use openDevTools"]
        static void inspect(InspectOptions options,
                            optional VoidCallback callback);
  };

  interface Events {
    // Fired when a item state is changed.
    static void onItemStateChanged(EventData response);

    // Fired when the profile's state has changed.
    static void onProfileStateChanged(ProfileInfo info);
  };

};